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.
|