elsa-core/specs/001-shell-reload-api/research.md

Phase 0 Research: Shell Reload API Endpoints

Decision 1: Keep the feature in the existing API and client modules

• Decision: Implement the endpoints in Elsa.Workflows.Api and add the typed client surface in Elsa.Api.Client.
• Rationale: The repository already places administrative REST endpoints in Elsa.Workflows.Api, and component tests exercise those endpoints through the hosted API fixture. A matching client resource keeps first-party consumers aligned with the new API surface.
• Alternatives considered:
  • Add the endpoints to Elsa.Tenants: rejected because the capability is broader than tenant CRUD and the requested change is centered on the existing API surface used by Elsa clients.
  • Create a new shell-administration module: rejected as unnecessary module growth for a two-endpoint feature.

Decision 2: Introduce a shell reload orchestration service in the API module

• Decision: Add a dedicated orchestration contract and service in Elsa.Workflows.Api that the endpoints call instead of embedding reload logic directly inside endpoint classes.
• Rationale: The spec requires busy-state rejection, unknown-shell validation, per-shell result reporting, and a future upgrade path from full-reload fallback to selective reload. Encapsulating that logic in one service keeps endpoints conventionally thin and localizes future upstream changes.
• Alternatives considered:
  • Inject IShellManager directly into each endpoint: rejected because the same branching, validation, and result-mapping logic would be duplicated.
  • Put the orchestration service in src/common/: rejected because the behavior is API-facing, request-oriented, and not shared elsewhere yet.

Decision 3: Use IShellSettingsProvider and IShellSettingsCache as the shell identity inputs

• Decision: Validate shell IDs and derive per-shell reload scope from the authoritative shell settings provider plus the current shell settings cache.
• Rationale: Upstream CShells uses IShellSettingsProvider.GetShellSettingsAsync as the source for ReloadAllShellsAsync, and IShellSettingsCache provides the current in-memory view of known shells. Using both lets Elsa compare requested/current/latest state without guessing.
• Alternatives considered:
  • Validate only against the current cache: rejected because removed or newly added shells would be misclassified relative to the latest configuration source.
  • Validate against shell host instances only: rejected because shell host state is runtime-focused and not the authoritative source for latest configuration.

Decision 4: Implement the current fallback as a full reconciliation flow, not a blind call to ReloadAllShellsAsync

• Decision: Plan the current implementation around a full shell reconciliation flow that can still represent the current full-reload fallback semantics while producing detailed outcomes and partial application.
• Rationale: Upstream DefaultShellManager.ReloadAllShellsAsync updates the shell settings cache and publishes ShellsReloaded, and the ASP.NET Core notification handler re-registers endpoints for all shells. That path does not expose per-shell success/failure details, requested-shell strictness, or partial application behavior required by the clarified spec. A reconciliation-oriented orchestration can compose existing manager operations (AddShellAsync, UpdateShellAsync, RemoveShellAsync) and preserve the current full-reload fallback for targeted requests.
• Alternatives considered:
  • Call ReloadAllShellsAsync directly for both endpoints: rejected because it cannot distinguish requested-shell failure from overall success and does not support the spec’s partial-success response model.
  • Implement a targeted one-shell update now: rejected because the user explicitly wants the targeted endpoint to remain on full-reload fallback behavior until upstream support exists.

Decision 5: Use a shared response model with top-level status plus per-shell outcomes

• Decision: Both endpoints will return the same logical result shape: a top-level reload status, optional requested shell ID, and a collection of per-shell outcome records.
• Rationale: The spec now requires detailed shell-level reporting for both full and targeted requests. A shared response model keeps the API and client simpler and makes targeted fallback behavior transparent when other shells are also affected.
• Alternatives considered:
  • Minimal boolean success responses: rejected because they cannot represent partial success or requested-shell strict failures.
  • Different response schemas per endpoint: rejected because both endpoints expose the same operational data with different scopes.

Decision 6: Keep endpoint request/response models collocated and move shared orchestration types into contracts

• Decision: Keep endpoint request/response models collocated with each endpoint and place only shared orchestration result types in Elsa.Workflows.Api/Contracts.
• Rationale: This preserves the repository’s single-endpoint-per-class convention while still avoiding duplication for shared internal result types consumed by both endpoints.
• Alternatives considered:
  • Put all reload models in a shared Endpoints/Shells/Models.cs: rejected because it weakens endpoint colocation and drifts from existing API conventions.
  • Duplicate all result types per endpoint: rejected because both endpoints share the same outcome model and would diverge unnecessarily.

Decision 7: Cover the feature with component tests, not a new unit-test project

• Decision: Add component tests under Elsa.Workflows.ComponentTests for the new endpoints and their observable runtime behavior.
• Rationale: There is no existing dedicated Elsa.Workflows.Api unit-test project, and the repository already validates REST endpoint behavior through the hosted WorkflowServer fixture with authenticated HTTP clients. Component tests can verify routes, permissions, status handling, and the effect on active shell-backed behavior in one place.
• Alternatives considered:
  • Create a brand-new Elsa.Workflows.Api.UnitTests project: rejected as out of scope for this feature and unnecessary for the first increment.
  • Rely only on integration tests against lower-level services: rejected because the feature’s primary value is the external API behavior.