Skip to content

ADR-036-orleans-foundation.md

Latest commit

 

History

History
42 lines (29 loc) · 3.79 KB

ADR-036-orleans-foundation.md

File metadata and controls

42 lines (29 loc) · 3.79 KB
Raw

ADR-036: Orleans foundation

Status: Accepted; rewritten 2026-10-18 under the owner's "Orleans is the whole cluster" direction. Implementation and delivered-source qualification in progress. Owner: KeyLoad lead. Related: ADR-136 (cluster and storage concept), ADR-125 (connection grain), ADR-143 (silo and replica counts), ADR-110 (execution primitives), ADR-082 (CQRS streams), ADR-116 (current format). Features: OrleansExecution, StorageReplication, TestInfrastructure.

Decision

Orleans is KeyLoad's runtime and its whole cluster. One server process hosts one Orleans silo inside the ASP.NET Core host. KeyLoad does not add a second clustering stack, does not make any silo a required primary and does not implement membership, discovery, placement, movement or consensus of its own.

Silo configuration uses only Orleans calls:

  • clustering provider: the published ManagedCode.Orleans.RapidMembership 10.4.0 provider for local and multi-host deployments; in-memory membership, automatic discovery and independent shared-secret authentication;
  • AddDistributedGrainDirectory() and AddActivationRepartitioner() — the owner-authorized experimental opt-ins ORLEANSEXP003 and ORLEANSEXP001 are suppressed only around these two calls;
  • AddGrainService<...>() for the silo-local ZoneTree owner and other per-silo services;
  • Durable Jobs and Journaling under ADR-110 (ORLEANSEXP005 confined to that provider, its registration and tests);
  • generated Orleans serialization with stable [GenerateSerializer], [Id] and [Alias] contracts for every internal payload;
  • OpenTelemetry through ServiceDefaults and the Orleans/ASP.NET Core integrations.

No global analyzer suppression is allowed.

flowchart TD
    Host[ASP.NET Core host] --> Silo[Orleans silo]
    Silo --> Membership[clustering provider]
    Silo --> Directory[Distributed grain directory]
    Silo --> Repartitioner[Activation repartitioner]
    Silo --> Service[Silo-local ZoneTree Grain Service]
    Silo --> Grains[Connection and partition grains]
    Grains -->|Orleans calls| Service
    Service --> Files[(Local ZoneTree files)]
Loading

Security and errors

Persisted database identity and authorization stay authoritative; clients cannot supply trusted roles. The verified subject travels between grains in execution RequestContext through ManagedCode.Orleans.Identity; it never replaces the fresh persisted permission check of each operation. Error translation preserves caller cancellation, safe domain errors and possibly-dispatched write uncertainty without retrying an operation. Diagnostics contain no credentials or payloads.

Lifecycle

Startup registers options, serialization and telemetry, opens the local ZoneTree files in the storage Grain Service initialization, lets the silo become Active, then admits public traffic once fresh persisted identity is readable. Shutdown stops admission, drains accepted operations and background work, then closes the ZoneTree files. A failed or canceled silo start is not reused in-process.

Verification

Development builds and Aspire-owned TUnit tests may run locally as development evidence. Qualification requires the exact delivered source on Linux GitHub Actions: Release build with warnings as errors, format, analyzers, TUnit unit and scalar suites, real process recovery and Aspire cluster tests through the real .NET SDK and official MCP client. Process-kill tests do not prove power-loss durability. This ADR stays Accepted until that evidence exists.