21e982c2c6
* feat: add specification and quality checklist for Shell Reload API endpoints * feat: implement Shell Reload API endpoints and associated documentation * feat: enhance Shell Reload API documentation and add tasks for implementation phases * feat: implement Shell Reload API features with endpoints, interface contracts, models, and component tests * feat: update Shell Reload API responses and tests to reflect changes in error handling and response structure * Fix shell reload follow-up review issues (#7354) * Initial plan * Address shell reload review feedback Co-authored-by: sfmskywalker <938393+sfmskywalker@users.noreply.github.com> * Dispose shell reload semaphore Co-authored-by: sfmskywalker <938393+sfmskywalker@users.noreply.github.com> * Harden shell reload follow-up fixes Co-authored-by: sfmskywalker <938393+sfmskywalker@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: sfmskywalker <938393+sfmskywalker@users.noreply.github.com> * Update src/modules/Elsa.Workflows.Api/Endpoints/Shells/Reload/Endpoint.cs Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> * Potential fix for pull request finding 'Missed opportunity to use Where' Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com> * Update src/modules/Elsa.Workflows.Api/Endpoints/Shells/Reload/Endpoint.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com> Co-authored-by: sfmskywalker <938393+sfmskywalker@users.noreply.github.com> Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
178 lines
10 KiB
Markdown
178 lines
10 KiB
Markdown
# Tasks: Shell Reload API Endpoints
|
|
|
|
**Input**: Design documents from `/specs/001-shell-reload-api/`
|
|
**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/, quickstart.md
|
|
|
|
**Tests**: Tests are required for this feature by the repository constitution, so each user story includes component-test coverage.
|
|
|
|
**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
|
|
|
|
## Phase 1: Setup (Shared Infrastructure)
|
|
|
|
**Purpose**: Add the minimum project references and client resource scaffolding required by the feature.
|
|
|
|
- [X] T001 Update `src/modules/Elsa.Workflows.Api/Elsa.Workflows.Api.csproj` to reference the `CShells` package needed for `IShellManager`, `IShellSettingsProvider`, and `IShellSettingsCache`
|
|
- [X] T002 [P] Create the shell API client contract scaffold in `src/clients/Elsa.Api.Client/Resources/Shells/Contracts/IShellsApi.cs`
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Prerequisites)
|
|
|
|
**Purpose**: Establish shared orchestration infrastructure and shared non-endpoint result types used by all shell reload stories.
|
|
|
|
**⚠️ CRITICAL**: No user story work can begin until this phase is complete
|
|
|
|
- [X] T003 Create shared orchestration result contracts in `src/modules/Elsa.Workflows.Api/Contracts/ShellReloadStatus.cs`, `src/modules/Elsa.Workflows.Api/Contracts/ShellReloadItemResult.cs`, and `src/modules/Elsa.Workflows.Api/Contracts/ShellReloadResult.cs`
|
|
- [X] T004 [P] Create shared client-side reload DTOs in `src/clients/Elsa.Api.Client/Resources/Shells/Models/ShellReloadItemResult.cs`, `src/clients/Elsa.Api.Client/Resources/Shells/Models/ShellReloadStatus.cs`, and `src/clients/Elsa.Api.Client/Resources/Shells/Responses/ShellReloadResponse.cs`
|
|
- [X] T005 Create the reload orchestration contract and base implementation in `src/modules/Elsa.Workflows.Api/Contracts/IShellReloadOrchestrator.cs` and `src/modules/Elsa.Workflows.Api/Services/ShellReloadOrchestrator.cs`
|
|
- [X] T006 Register the shell reload orchestrator in `src/modules/Elsa.Workflows.Api/ShellFeatures/WorkflowsApiFeature.cs`
|
|
|
|
**Checkpoint**: Shared DTOs and orchestration infrastructure are ready for story implementation.
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 - Reload all shells after configuration changes (Priority: P1) 🎯 MVP
|
|
|
|
**Goal**: Let operators trigger a full shell reload and receive detailed per-shell results.
|
|
|
|
**Independent Test**: Change shell configuration for one or more shells, call the reload-all endpoint, and verify the updated behavior is active without restarting the host.
|
|
|
|
### Tests for User Story 1
|
|
|
|
- [X] T007 [P] [US1] Add component tests for successful full-shell reload results in `test/component/Elsa.Workflows.ComponentTests/Scenarios/RestApis/Endpoints/Shells/ReloadAllTests.cs`
|
|
|
|
### Implementation for User Story 1
|
|
|
|
- [X] T008 [US1] Implement full-reload snapshotting and successful per-shell result mapping around the current full-reload fallback in `src/modules/Elsa.Workflows.Api/Services/ShellReloadOrchestrator.cs`
|
|
- [X] T009 [P] [US1] Implement the reload-all endpoint and collocated response handling in `src/modules/Elsa.Workflows.Api/Endpoints/Shells/ReloadAll/Endpoint.cs` and `src/modules/Elsa.Workflows.Api/Endpoints/Shells/ReloadAll/Models.cs`
|
|
- [X] T010 [P] [US1] Add the reload-all client method to `src/clients/Elsa.Api.Client/Resources/Shells/Contracts/IShellsApi.cs`
|
|
|
|
**Checkpoint**: User Story 1 is independently functional through the API and client surface.
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 - Request reload for one shell (Priority: P2)
|
|
|
|
**Goal**: Expose a targeted shell reload endpoint that validates the shell ID and enforces requested-shell strict success semantics while still using the current full-reload fallback.
|
|
|
|
**Independent Test**: Call the targeted reload endpoint for a known shell and verify the requested shell refreshes; call it for an unknown shell and verify a not-found outcome.
|
|
|
|
### Tests for User Story 2
|
|
|
|
- [X] T011 [P] [US2] Add component tests for targeted reload success, unknown shell handling, and requested-shell strict outcomes in `test/component/Elsa.Workflows.ComponentTests/Scenarios/RestApis/Endpoints/Shells/ReloadTests.cs`
|
|
|
|
### Implementation for User Story 2
|
|
|
|
- [X] T012 [US2] Extend targeted reload validation and requested-shell strict result handling in `src/modules/Elsa.Workflows.Api/Services/ShellReloadOrchestrator.cs`
|
|
- [X] T013 [P] [US2] Implement the targeted reload endpoint and collocated models in `src/modules/Elsa.Workflows.Api/Endpoints/Shells/Reload/Endpoint.cs` and `src/modules/Elsa.Workflows.Api/Endpoints/Shells/Reload/Models.cs`
|
|
- [X] T014 [P] [US2] Add the targeted reload client method to `src/clients/Elsa.Api.Client/Resources/Shells/Contracts/IShellsApi.cs`
|
|
|
|
**Checkpoint**: User Story 2 works independently for known and unknown shell IDs.
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 - Handle failed reload attempts safely (Priority: P3)
|
|
|
|
**Goal**: Return clear busy, unavailable, and partial-success outcomes without falsely reporting that shells refreshed.
|
|
|
|
**Independent Test**: Simulate concurrent reloads, unavailable shell settings, and invalid configuration for one shell, then verify the API returns the required error or partial-success responses with shell-level detail.
|
|
|
|
### Tests for User Story 3
|
|
|
|
- [X] T015 [P] [US3] Add component tests for busy rejection, unavailable configuration, and partial-success reload behavior in `test/component/Elsa.Workflows.ComponentTests/Scenarios/RestApis/Endpoints/Shells/ShellReloadFailureTests.cs`
|
|
|
|
### Implementation for User Story 3
|
|
|
|
- [X] T016 [US3] Implement busy-state rejection and provider-unavailable failure handling in `src/modules/Elsa.Workflows.Api/Services/ShellReloadOrchestrator.cs`
|
|
- [X] T017 [US3] Implement partial-success reconciliation for invalid shell configurations in `src/modules/Elsa.Workflows.Api/Services/ShellReloadOrchestrator.cs`
|
|
- [X] T018 [US3] Map busy, partial-success, requested-shell failure, and provider-failure outcomes to HTTP responses in `src/modules/Elsa.Workflows.Api/Endpoints/Shells/ReloadAll/Endpoint.cs` and `src/modules/Elsa.Workflows.Api/Endpoints/Shells/Reload/Endpoint.cs`
|
|
|
|
**Checkpoint**: All failure and partial-success behaviors are independently testable through the API.
|
|
|
|
---
|
|
|
|
## Phase 6: Polish & Cross-Cutting Concerns
|
|
|
|
**Purpose**: Bring implementation, client surface, and planning artifacts into final alignment.
|
|
|
|
- [X] T019 [P] Update `specs/001-shell-reload-api/contracts/shell-reload-api.yaml` to match the final implemented routes, statuses, and response payloads
|
|
- [X] T020 Run the quickstart validation against `specs/001-shell-reload-api/quickstart.md` using `test/component/Elsa.Workflows.ComponentTests/Elsa.Workflows.ComponentTests.csproj` and fix any mismatches in `src/modules/Elsa.Workflows.Api/Endpoints/Shells/` and `src/clients/Elsa.Api.Client/Resources/Shells/`
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
### Phase Dependencies
|
|
|
|
- **Setup (Phase 1)**: No dependencies; start immediately.
|
|
- **Foundational (Phase 2)**: Depends on Phase 1; blocks all user story work.
|
|
- **User Story 1 (Phase 3)**: Depends on Phase 2 only.
|
|
- **User Story 2 (Phase 4)**: Depends on Phase 2 only.
|
|
- **User Story 3 (Phase 5)**: Depends on Phase 2 only.
|
|
- **Polish (Phase 6)**: Depends on the user stories you intend to ship.
|
|
|
|
### User Story Dependencies
|
|
|
|
- **US1**: No dependency on other user stories; this is the MVP.
|
|
- **US2**: No functional dependency on US1, but it reuses the shared orchestrator and response models from Phase 2.
|
|
- **US3**: No functional dependency on US1 or US2, but it extends the same orchestrator and endpoint files, so coordinate file ownership if multiple developers work in parallel.
|
|
|
|
### Within Each User Story
|
|
|
|
- Write the component tests first and confirm they fail before implementation.
|
|
- Implement orchestration logic before endpoint wiring.
|
|
- Add API client methods after the corresponding endpoint contract is stable.
|
|
- Validate the story through the hosted component-test server before moving on.
|
|
|
|
### Parallel Opportunities
|
|
|
|
- `T002` can run in parallel with `T001`.
|
|
- `T004` can run in parallel with `T003` once Phase 1 is complete.
|
|
- `T007`, `T009`, and `T010` can proceed in parallel after `T008` starts stabilizing the shared orchestration shape.
|
|
- `T011`, `T013`, and `T014` can proceed in parallel after `T012` defines the targeted behavior.
|
|
- `T015` can run in parallel with `T016` because tests are in a separate file.
|
|
- `T019` can run in parallel with final cleanup before `T020`.
|
|
|
|
---
|
|
|
|
## Parallel Example: User Story 1
|
|
|
|
```bash
|
|
# After T008 defines the US1 orchestration behavior:
|
|
Task: "Add component tests for successful full-shell reload results in test/component/Elsa.Workflows.ComponentTests/Scenarios/RestApis/Endpoints/Shells/ReloadAllTests.cs"
|
|
Task: "Implement the reload-all endpoint and collocated response handling in src/modules/Elsa.Workflows.Api/Endpoints/Shells/ReloadAll/Endpoint.cs and src/modules/Elsa.Workflows.Api/Endpoints/Shells/ReloadAll/Models.cs"
|
|
Task: "Add the reload-all client method to src/clients/Elsa.Api.Client/Resources/Shells/Contracts/IShellsApi.cs"
|
|
```
|
|
|
|
---
|
|
|
|
## Implementation Strategy
|
|
|
|
### MVP First (User Story 1 Only)
|
|
|
|
1. Complete Phase 1: Setup.
|
|
2. Complete Phase 2: Foundational.
|
|
3. Complete Phase 3: User Story 1.
|
|
4. Validate the reload-all endpoint and client flow with the component tests.
|
|
|
|
### Incremental Delivery
|
|
|
|
1. Deliver US1 to provide immediate operational value.
|
|
2. Add US2 so automation can target one shell explicitly while still using the full-reload fallback.
|
|
3. Add US3 to complete the failure-handling and partial-success contract.
|
|
4. Finish with Phase 6 to ensure the generated contract and quickstart remain accurate.
|
|
|
|
### Parallel Team Strategy
|
|
|
|
1. One developer completes Phase 1 and Phase 2.
|
|
2. Then split work by story, with coordination around `src/modules/Elsa.Workflows.Api/Services/ShellReloadOrchestrator.cs` and `src/clients/Elsa.Api.Client/Resources/Shells/Contracts/IShellsApi.cs` because those files are shared touchpoints.
|
|
3. Rejoin for Phase 6 validation and contract alignment.
|
|
|
|
---
|
|
|
|
## Notes
|
|
|
|
- `[P]` tasks are limited to work that can proceed without editing the same files concurrently.
|
|
- Story labels map directly to the prioritized stories in `spec.md`.
|
|
- The task list assumes the design decision to keep this feature inside `Elsa.Workflows.Api`, `Elsa.Api.Client`, and `Elsa.Workflows.ComponentTests`.
|
|
- `T020` is the final verification checkpoint before handing the feature off for implementation completion. |