@nylorun/runtime 0.13.0-beta → 0.15.0-beta

package/dist/tenant/streams.d.ts

@@ -1,5 +1,30 @@
+/**
+ * The Durable Streams seam of an open Tenant (Durable Streams §7–§9), wired by one
+ * `wireStreams(ctx, …)` call in the composition root:
+ *
+ * - **Record.** Every event is written to the record in its transaction (`Tx.event`). The
+ *   stream relay (`streams/relay/`) feeds the Tenant's basin from it. On a Host with S2, one
+ *   process-wide relay reads the record over logical replication (`host/main.ts`);
+ *   otherwise (tests, a Host without S2) this module runs a relay of the Tenant's own commits,
+ *   which reconciles the record with the streams when it starts.
+ * - **Basin generations.** The Tenant's session streams live in its current basin generation
+ *   (`streams/basin.ts`). A reset moves it to the next one (`tenantReset`): the old basin gets
+ *   a `sessions.reset` signal, every process moves its readers, and the old basin is deleted
+ *   after a grace period (again when the Tenant opens, until it is gone).
+ * - **Basin.** The current basin is created when the Tenant opens. A missing basin (S2 down
+ *   then, or deleted since) is repaired on first use: a failed `ensureTenant` retries in the background with backoff,
+ *   and `streamsStatus` reports the basin's state.
+ * - **Readers.** History and session SSE read the session's stream
+ *   (`tenant/session-streams.ts`). This module runs one `tenant/control` reader per Tenant per
+ *   process, on the current basin, which calls `ctx.abortLocal` for each `session.cancel`,
+ *   checks the session streams for each `sessions.reset`, and ends a subject's streams for
+ *   each `subject.revoked`.
+ *
+ * The caller passes the streams: the Host's S2 streams, or `MemoryStreams` for tests and a
+ * local development Host (not durable).
+ */
 import type { SessionStore } from "../store/types.js";
-import { type Relay } from "../streams/relay.js";
+import { type StreamRelay, type StreamRelayStatus } from "../streams/relay/core.js";
 import { type DurableStreams } from "../streams/types.js";
 import type { TenantContext } from "./context.js";
 export interface WireStreamsOptions {
@@ -8,10 +33,15 @@ export interface WireStreamsOptions {
     streams: DurableStreams;
     /** Close `streams` with the wiring (streams created for this Tenant alone). */
     ownsStreams?: boolean;
-    /** An existing relay to use instead of creating one; the caller closes it. */
-    relay?: Relay;
+    /**
+     * The Host runs the stream relay for the Tenant (logical replication). Otherwise the
+     * Tenant relays its own commits.
+     */
+    hostRelay?: boolean;
+    /** How long a retired basin is kept for readers still on it. Default 60 s. */
+    retireGraceMs?: number;
 }
-/** The state of the Tenant's basin as this process last saw it. */
+/** The state of the Tenant's current basin as this process last saw it. */
 export interface BasinStatus {
     /** `ensureTenant` succeeded and no append has failed since. */
     ready: boolean;
@@ -20,107 +50,54 @@ export interface BasinStatus {
     /** The last failure's message, cleared once the basin is ready. */
     lastError: string | null;
 }
-/** What one `collectSessionStreams` pass did. */
-export interface CollectResult {
-    /** Abandoned session streams deleted. */
-    deleted: number;
-    /** Session streams of existing sessions, kept. */
-    kept: number;
-    /** Deletions that failed; the collection stays pending. */
-    failed: number;
-}
-/** The handles `wireStreams` returns (also kept on `ctx.live.wiring`). */
+/** The handles `wireStreams` returns (also kept on `ctx.sessionStreams.wiring`). */
 export interface StreamsWiring {
     readonly streams: DurableStreams;
-    readonly relay: Relay;
-    /** The basin's state (`streamsStatus`). */
+    /** The Tenant's own relay; undefined when the Host relays. */
+    readonly relay: StreamRelay | undefined;
+    /** The current basin's state (`streamsStatus`). */
     basin(): BasinStatus;
-    /** Appends leftover outbox rows, at most `limit`; resolves with the number relayed. */
-    drain(limit?: number): Promise<number>;
-    /**
-     * Deletes abandoned session streams when a collection is pending; undefined when none was.
-     * One pass at a time.
-     */
-    collect(): Promise<CollectResult | undefined>;
-    /** Stops the readers, waits for in-flight relays, and closes what `wireStreams` created. */
+    /** Moves this process's readers and control reader to basin generation `generation`. */
+    moveTo(generation: number): void;
+    /** Deletes the basins of retired generations after the grace period. */
+    retire(generations: readonly number[]): void;
+    /** Stops the readers and the relay, and closes what `wireStreams` created. */
     close(): Promise<void>;
 }
-/** The Tenant setting that holds a pending collection's token ("" when none is pending). */
-export declare const COLLECT_SETTING = "streams.collect";
 /**
- * Wires the Tenant to Durable Streams: checks the basin, creates the relay (unless given),
- * starts the work and control readers, and records the handles on `ctx.live.wiring`. Call it
- * once, after `ctx` is built and before the Tenant serves requests.
+ * Wires the Tenant to Durable Streams: reads its basin generation, checks the basin, starts
+ * the Tenant's relay (unless the Host relays), the control reader and the retired basins'
+ * deletion, and records the handles on `ctx.sessionStreams.wiring`. Call it once, after
+ * `ctx` is built and before the Tenant serves requests.
  */
 export declare function wireStreams(ctx: TenantContext, options: WireStreamsOptions): Promise<StreamsWiring>;
-/** The Tenant sweep's outbox recovery: appends leftover rows, at most `limit`. */
-export declare function drainOutbox(ctx: TenantContext, limit?: number): Promise<number>;
-/**
- * Appends `session.cancel` for `sessionId` to `tenant/control`, so the process running its
- * advance aborts it. Call it from `t.afterCommit` after a cancel commits. A lost signal costs
- * latency only (the advance checks the Session Store before every effect), so failures are
- * logged, never thrown.
- */
-export declare function signalSessionCancel(ctx: TenantContext, sessionId: string): void;
 /**
- * Before a reset that deletes sessions: records a pending collection of their streams in the
- * Tenant settings, so it is retried by the sweep even if this process stops before it runs.
+ * Appends `session.cancel` for `sessionId` and its cancelled turn to `tenant/control`, so the
+ * process running that turn's advance aborts it. Call it from `t.afterCommit` after a cancel
+ * commits. A lost signal costs latency only (the advance checks the Session Store before every
+ * effect), so failures are logged, never thrown.
  */
-export declare function requestStreamCollection(ctx: TenantContext): Promise<void>;
+export declare function signalSessionCancel(ctx: TenantContext, sessionId: string, turnId: string | null): void;
 /**
- * After a reset deleted sessions: tells every process with the Tenant open to check its
- * session feeds (`sessions.reset`), and deletes the abandoned streams now, best effort.
- * Failures are logged; the sweep retries the collection.
+ * After a reset deleted the Tenant's sessions and moved it to a new basin generation: tells
+ * every process with the Tenant open (`sessions.reset` on the old basin's control stream),
+ * moves this process's readers, and deletes the old basin after the grace period. Failures
+ * are logged; the periodic check and the next open finish the job.
  */
-export declare function sessionStreamsAbandoned(ctx: TenantContext): void;
-/**
- * Deletes the Tenant's session streams that no session uses any more: streams of deleted
- * sessions and of earlier incarnations. Runs only while a collection is pending
- * (`requestStreamCollection`), and clears it once every deletion succeeded, unless another
- * reset requested a new one meanwhile.
- *
- * Streams are listed before their sessions are read, so a session created meanwhile keeps
- * its stream: its row committed before the relay created the stream.
- */
-export declare function collectSessionStreams(ctx: TenantContext, streams: DurableStreams): Promise<CollectResult | undefined>;
+export declare function tenantReset(ctx: TenantContext): Promise<void>;
 /** Tenant status of the streams seam (for `GET /v1/tenant` and the Admin API). */
 export interface StreamsStatus {
     /** The streams' service answered a probe (`probeStreams`) within the timeout. */
     reachable: boolean;
     basin: BasinStatus;
-    outbox: {
-        /** Events committed but not yet in their streams. */
-        depth: number;
-        /** Age of the oldest of them, or null when the outbox is empty. */
-        oldestAgeMs: number | null;
-    };
-    /** How far the relay is behind: the oldest unrelayed event's age, 0 when none is waiting. */
-    relayLagMs: number;
-    /** Abandoned session streams are waiting to be deleted. */
-    collectionPending: boolean;
+    /** The basin generation session streams are in. */
+    generation: number;
+    /** The Tenant's own relay; null when the Host's relay serves it. */
+    relay: StreamRelayStatus | null;
 }
-/**
- * The streams seam's status for an open Tenant: S2 reachability, the basin, outbox depth and
- * relay lag. Reads the Session Store and probes the streams (at most `probeTimeoutMs`).
- */
+/** The streams seam's status for an open Tenant: S2 reachability, the basin and the relay. */
 export declare function streamsStatus(ctx: TenantContext, options?: {
     probeTimeoutMs?: number;
-    now?: () => number;
 }): Promise<StreamsStatus>;
-/**
- * Creates a new Tenant's basin. Call it when the Tenant is created, after its schema commits;
- * retries transient failures, then throws. A failure need not fail the creation: opening the
- * Tenant repairs a missing basin.
- */
-export declare function createTenantStreams(streams: DurableStreams, tenantId: string, options?: {
-    attempts?: number;
-}): Promise<void>;
-/**
- * Deletes a Tenant's basin and every stream in it. Call it when the Tenant is deleted (never
- * on reset). Idempotent; retries transient failures, then throws.
- */
-export declare function deleteTenantStreams(streams: DurableStreams, tenantId: string, options?: {
-    attempts?: number;
-}): Promise<void>;
 /** Close: stops the readers and relay; the observers were ended by `endAllStreams`. */
 export declare function closeStreams(ctx: TenantContext): Promise<void>;