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>
79 lines
3.4 KiB
Markdown
79 lines
3.4 KiB
Markdown
# Data Model: Shell Reload API Endpoints
|
||
|
||
## Entity: Shell Reload Command
|
||
|
||
- **Purpose**: Represents an administrative request to refresh shell runtime state.
|
||
- **Fields**:
|
||
- `Scope`: `All` or `Targeted`.
|
||
- `RequestedShellId`: optional shell identifier; required when scope is `Targeted`.
|
||
- `RequestedAt`: execution timestamp captured for result reporting and diagnostics.
|
||
- **Validation rules**:
|
||
- `RequestedShellId` is required for targeted commands.
|
||
- Shell identifiers are matched case-insensitively to align with `ShellId` semantics in CShells.
|
||
|
||
## Entity: Shell Reload Result
|
||
|
||
- **Purpose**: Represents the top-level outcome returned by either reload endpoint.
|
||
- **Fields**:
|
||
- `Status`: one of `Completed`, `Partial`, `Failed`, `Busy`, `NotFound`, or `RequestedShellFailed`.
|
||
- `RequestedShellId`: optional shell identifier echoed for targeted requests.
|
||
- `Shells`: collection of `Shell Reload Item Result` records for each affected shell.
|
||
- `ReloadedAt`: timestamp indicating when the orchestration completed.
|
||
- **Validation rules**:
|
||
- `Shells` must be populated for `Completed`, `Partial`, and `RequestedShellFailed` outcomes.
|
||
- `RequestedShellId` must be populated for `Targeted` requests.
|
||
|
||
## Entity: Shell Reload Item Result
|
||
|
||
- **Purpose**: Describes the shell-level result used to explain a full or targeted reload outcome.
|
||
- **Fields**:
|
||
- `ShellId`: shell identifier.
|
||
- `Outcome`: one of `Reloaded`, `Unchanged`, `Removed`, `InvalidConfiguration`, `Unknown`, or `Skipped`.
|
||
- `Requested`: boolean indicating whether this item is the caller’s explicitly requested shell.
|
||
- `Message`: optional human-readable detail describing why the shell remained unchanged or failed.
|
||
- **Validation rules**:
|
||
- Each `ShellId` appears at most once per response.
|
||
- `Requested` is true for at most one item.
|
||
|
||
## Entity: Shell Reload Scope Snapshot
|
||
|
||
- **Purpose**: Internal planning concept representing the latest provider settings compared with the current cache before orchestration runs.
|
||
- **Fields**:
|
||
- `CurrentShellIds`: current in-memory shell identifiers from the settings cache.
|
||
- `LatestShellSettings`: latest shell settings from the provider.
|
||
- `MissingShellIds`: current shells absent from the latest provider view.
|
||
- **Why it matters**: The orchestration needs this snapshot to distinguish updates, additions, removals, unknown shell requests, and unchanged shells.
|
||
|
||
## State Transitions
|
||
|
||
### Full Reload Command
|
||
|
||
`Pending` → `Completed`
|
||
when all affected shells refresh successfully.
|
||
|
||
`Pending` → `Partial`
|
||
when at least one shell refreshes successfully and at least one shell remains unchanged because of invalid configuration or a shell-specific failure.
|
||
|
||
`Pending` → `Busy`
|
||
when another reload is already in progress.
|
||
|
||
`Pending` → `Failed`
|
||
when the shell settings provider cannot supply usable configuration for the operation.
|
||
|
||
### Targeted Reload Command
|
||
|
||
`Pending` → `NotFound`
|
||
when the requested shell ID does not exist in the authoritative configuration view.
|
||
|
||
`Pending` → `Busy`
|
||
when another reload is already in progress.
|
||
|
||
`Pending` → `Completed`
|
||
when the current full-reload fallback completes and the requested shell refreshes successfully.
|
||
|
||
`Pending` → `RequestedShellFailed`
|
||
when the fallback full reload updates some shells but the requested shell remains unchanged because its updated configuration could not be applied.
|
||
|
||
`Pending` → `Failed`
|
||
when the shell settings provider cannot supply usable configuration for the operation.
|