Roles & config

Which shape a process takes is inferred from the options you give it. The topology preset on DurableModule.forRoot lets you name the role instead, and validates the two axes that otherwise read as synonyms — namespace (the operator's poll scope) versus partition (a worker's queue suffix). topology is entirely additive: omit it and inference behaves exactly as before.

The configsCopy Anchor Link

DurableModule.forRoot({
  store,
  transport: new EventEmitterTransport(),  // or BullMQ for cross-process
})

What topology validatesCopy Anchor Link

Each check is named after the axis it protects, and runs at forRoot/forRootAsync resolution time:

The preset exists for the case plain inference can't catch: an app that sets both namespace (meant for the operator) and partition (meant for a worker) on one instance because the two options read as near-synonyms. topology forces you to pick one role and rejects the other role's axis outright, with an error message that explains why. What each axis actually partitions is Tenancy.

The shared surface: RunGatewayCopy Anchor Link

Every shape binds exactly one RunGateway, and the role picks the implementation. An operator with a store reads its store directly (StoreRunGateway). A store-less pod binds a ProxyRunGateway that round-trips every call over the transport to the control plane, which reads its store and answers.

This is what makes application code portable across shapes. Your controllers and the dashboard call the same interface either way, so a pod moving from single-process to store-less changes only its forRoot — no controller code, and the identical DurableDashboardModule mounts on both.

@Controller('runs')
export class RunsController {
  constructor(private readonly gateway: RunGateway) {}   // inject by type — the class is its own token

  @Get(':id')
  async show(@Param('id') id: string) {
    return (await this.gateway.getRunDetail(id)) ?? {};
  }
}

Tune the proxy round-trip with runGatewayTimeoutMs (default 10_000). It is ignored on an operator, which is bound to the store-backed gateway.

Wide fans over the gatewayCopy Anchor Link

The dashboard asks getRunDetail(id, { summarizeFansOver: 50 }) and pages a fan with getFanMembers (see Wide fans). StoreRunGateway implements both, plus getRun. On a store-less pod, ProxyRunGateway forwards the detail options in its getRunDetail request and sends a getFanMembers request kind. The control plane's responder checks that the requesting tenant owns the run before it pages the fan, as it does before every run-scoped verb, so a tenant cannot page another tenant's fan.

If you implement RunGateway yourself:

• summarizeFansOver is a hint. A gateway that ignores it returns the full detail, and the console renders every member as before.
• getFanMembers is optional. Without it, the dashboard's GET runs/:id/fans/:group answers 404, so a summarized fan can be drawn but not expanded. Core exports summarizeTimeline, summarizeFan, pageFan and childIdsOf, so a gateway that already loads the checkpoints can implement both in a few lines, the way StoreRunGateway does.
• getRun is optional. The ownership check uses it to read only the run row; without it, the check falls back to getRunDetail, which reads every checkpoint of the run.

Layered tenant authenticationCopy Anchor Link

The tenant on a wire request is a claim. Without authentication the isolation boundary is meaningless — any pod could ask for any tenant's runs. Durable stacks two layers:

The control plane is the trust boundary for these proxied requests: it forces listRuns to the requester's own tenant (no cross-tenant enumeration), validates run.namespace === tenant on every runId-bearing verb (anti-IDOR), and rejects unknown verbs and tampered tokens.

Next stepsCopy Anchor Link

• Tenancy — what namespace and partition partition, and the rules that keep a tenant's runs on the tenant's own pool.
• Handshake & capability negotiation — keep a mixed fleet version-safe.
• Cross-ecosystem interop — add Python and Adonis workers.