@nylorun/runtime 0.10.0-beta → 0.12.0-beta

package/dist/tenant/store-memory.d.ts

@@ -1,19 +1,16 @@
-import type { TenantEnvelope } from "@nylorun/core/contracts";
-import type { BootstrapPrincipal, Logger, OpenTenantRuntime, TenantConfig, TenantStore } from "./types.js";
+import type { SessionStore } from "../store/types.js";
+import { type Logger, type OpenTenantRuntime, type TenantConfig, type TenantStore } from "./types.js";
 export interface MemoryTenantStoreOptions {
+    /** When set, each Tenant's directory under this Host root lives as long as the Tenant. */
+    hostRoot?: string;
     openRuntime: OpenTenantRuntime;
     configFor: (tenantId: string) => TenantConfig;
     logger?: Logger;
-    /** Schema version recorded for new tenants (default TENANT_SCHEMA_VERSION). */
-    schemaVersion?: number;
 }
-/**
- * In-memory TenantStore for tests. No filesystem; openRuntime is still injected
- * so conformance can exercise the same module path as the FS adapter.
- */
-export declare function createMemoryTenantStore(options: MemoryTenantStoreOptions): TenantStore & {
-    /** Test helper: insert a raw record without opening. */
-    seed(envelope: TenantEnvelope, bootstrap: BootstrapPrincipal): void;
-    /** Test helper: current live ids. */
+export type MemoryTenantStore = TenantStore & {
+    /** Test helper: current Tenant ids. */
     ids(): string[];
+    /** Test helper: a Session Store on a Tenant's data, as another process would open it. */
+    sessionStore(id: string): SessionStore;
 };
+export declare function createMemoryTenantStore(options: MemoryTenantStoreOptions): MemoryTenantStore;

package/dist/tenant/store-memory.js

@@ -1,100 +1,111 @@
+/**
+ * An in-memory Tenant store for tests: each Tenant is a `MemoryStoreData` (its Session
+ * Store's data) and an envelope. It behaves like the Postgres store (`store-pg.ts`): the
+ * Tenant directory under the Host root, when one is given, is created with the Tenant and
+ * removed with it, and `open` hands the Tenant Runtime a fresh Session Store on the Tenant's
+ * data. Not a supported profile.
+ */
+import { mkdirSync, rmSync } from "node:fs";
 import { isTenantId } from "@nylorun/core/compatibility";
-import { TENANT_SCHEMA_VERSION } from "./schema.js";
+import { MEMORY_SCHEMA_VERSION, MemorySessionStore, MemoryStoreData, } from "../store/memory.js";
 import { quarantine } from "./quarantine.js";
 import { parseEnvelope } from "./envelope.js";
-/**
- * In-memory TenantStore for tests. No filesystem; openRuntime is still injected
- * so conformance can exercise the same module path as the FS adapter.
- */
+import { tenantPaths } from "./paths.js";
+import { bootstrapPrincipal, bootstrapPrincipalMatches } from "./principals.js";
+import { TenantNotFoundError, } from "./types.js";
 export function createMemoryTenantStore(options) {
     const records = new Map();
-    const schemaVersion = options.schemaVersion ?? TENANT_SCHEMA_VERSION;
-    const store = {
-        seed(envelope, bootstrap) {
-            const env = parseEnvelope(envelope, envelope.id);
-            records.set(env.id, {
-                envelope: env,
-                bootstrap: { ...bootstrap },
-                schemaVersion: env.schemaVersion,
+    function sessionStore(id, data) {
+        return new MemorySessionStore({
+            tenantId: id,
+            onError: (error) => options.logger?.error("post-commit step failed", {
+                message: error instanceof Error ? error.message : String(error),
+            }),
+        }, data);
+    }
+    function makeDirectory(id) {
+        if (!options.hostRoot)
+            return;
+        const p = tenantPaths(options.hostRoot, id);
+        mkdirSync(p.root, { recursive: true, mode: 0o700 });
+        for (const dir of [p.home, p.tmp, p.sandboxes, p.pluginData, p.logs])
+            mkdirSync(dir, { recursive: true });
+    }
+    function removeDirectory(id) {
+        if (options.hostRoot)
+            rmSync(tenantPaths(options.hostRoot, id).root, {
+                recursive: true,
+                force: true,
             });
-        },
+    }
+    async function withStore(id, data, fn) {
+        const store = sessionStore(id, data);
+        try {
+            return await fn(store);
+        }
+        finally {
+            await store.close();
+        }
+    }
+    return {
         ids() {
-            return [...records.keys()].filter((id) => !records.get(id)?.trashed);
+            return [...records.keys()];
+        },
+        sessionStore(id) {
+            const record = records.get(id);
+            if (!record)
+                throw new TenantNotFoundError(id);
+            return sessionStore(id, record.data);
         },
         async enumerate() {
-            return [...records.entries()]
-                .filter(([, r]) => !r.trashed)
-                .map(([id]) => id)
-                .filter(isTenantId);
+            return [...records.keys()].filter(isTenantId).sort();
         },
         async readEnvelope(id) {
             const record = records.get(id);
-            if (!record || record.trashed) {
-                throw quarantine("envelope-invalid", "tenant envelope not found", {
-                    tenantId: id,
-                });
-            }
+            if (!record)
+                throw new TenantNotFoundError(id);
             return parseEnvelope(record.envelope, id);
         },
         async create(envelope, bootstrap) {
-            const env = parseEnvelope(envelope, envelope.id);
-            const existing = records.get(env.id);
-            if (existing && !existing.trashed)
+            const parsed = parseEnvelope({ ...envelope, schemaVersion: MEMORY_SCHEMA_VERSION }, envelope.id);
+            if (records.has(parsed.id))
                 return "exists";
-            records.set(env.id, {
-                envelope: env,
-                bootstrap: { ...bootstrap },
-                schemaVersion: env.schemaVersion || schemaVersion,
-            });
+            makeDirectory(parsed.id);
+            const data = new MemoryStoreData();
+            await withStore(parsed.id, data, (store) => store.tx((t) => bootstrapPrincipal(t, bootstrap)));
+            records.set(parsed.id, { envelope: parsed, data });
             return "created";
         },
         async bootstrapMatches(id, bootstrap) {
             const record = records.get(id);
-            if (!record || record.trashed)
+            if (!record)
                 return false;
-            return (record.bootstrap.principalId === bootstrap.principalId &&
-                record.bootstrap.credentialHash === bootstrap.credentialHash &&
-                record.bootstrap.idempotencyKey === bootstrap.idempotencyKey);
+            return withStore(id, record.data, (store) => store.tx((t) => bootstrapPrincipalMatches(t, bootstrap)));
         },
         async open(id) {
             const record = records.get(id);
-            if (!record || record.trashed) {
-                throw quarantine("open-failed", `Tenant ${id} not found`, {
-                    tenantId: id,
-                });
+            if (!record)
+                throw new TenantNotFoundError(id);
+            if (record.envelope.schemaVersion > MEMORY_SCHEMA_VERSION)
+                throw quarantine("schema-too-new", `Tenant schema version ${record.envelope.schemaVersion} is newer than this Runtime's ${MEMORY_SCHEMA_VERSION}`, { tenantId: id });
+            makeDirectory(id);
+            const store = sessionStore(id, record.data);
+            try {
+                return await options.openRuntime({ ...options.configFor(id), tenantId: id }, { store, envelope: record.envelope });
             }
-            if (record.schemaVersion > TENANT_SCHEMA_VERSION) {
-                throw quarantine("schema-too-new", `Tenant schema version ${record.schemaVersion} is newer than Host ${TENANT_SCHEMA_VERSION}`, { tenantId: id });
+            catch (error) {
+                await store.close().catch(() => undefined);
+                throw error;
             }
-            const config = options.configFor(id);
-            const opened = await options.openRuntime({
-                ...config,
-                tenantId: id,
-            });
-            const handle = {
-                ...opened,
-                envelope: record.envelope,
-                handle: opened.handle.bind(opened),
-                summary: opened.summary.bind(opened),
-                drain: opened.drain.bind(opened),
-                close: opened.close.bind(opened),
-            };
-            record.handle = handle;
-            return handle;
         },
-        async trash(id, _now) {
-            const record = records.get(id);
-            if (!record)
-                return;
-            if (record.handle) {
-                await record.handle.close().catch(() => undefined);
-            }
-            record.trashed = true;
-            record.handle = undefined;
+        async trash(id) {
+            records.delete(id);
+            removeDirectory(id);
         },
         async removePartial(id) {
-            records.delete(id);
+            if (records.has(id))
+                return;
+            removeDirectory(id);
         },
     };
-    return store;
 }

package/dist/tenant/store-pg.d.ts

@@ -0,0 +1,15 @@
+import type { PostgresClient } from "../store/postgres/connect.js";
+import type { Migration } from "../store/postgres/migrations/index.js";
+import { type Logger, type OpenTenantRuntime, type TenantConfig, type TenantStore } from "./types.js";
+export interface PostgresTenantStoreOptions {
+    hostRoot: string;
+    /** The Host's pool. The store never ends it. */
+    sql: PostgresClient;
+    /** Opens the Tenant Runtime on a store the catalog opened; the Runtime then owns it. */
+    openRuntime: OpenTenantRuntime;
+    configFor: (tenantId: string) => TenantConfig;
+    logger?: Logger;
+    /** Tests only: the migrations this Runtime knows. */
+    migrations?: readonly Migration[];
+}
+export declare function createPostgresTenantStore(options: PostgresTenantStoreOptions): TenantStore;

package/dist/tenant/store-pg.js

@@ -0,0 +1,140 @@
+/**
+ * The Tenant store over the Postgres Tenant catalog (architecture §8.1, §8.2).
+ *
+ * A Tenant exists when its schema `tenant_<id>` exists (`store/postgres/tenants.ts`); the
+ * envelope is a row in it, so this store keeps no registry. What stays on the Host root is
+ * the Tenant directory `tenants/<id>/`: the vault key (`vault-kek`), `plugin-data/`, `logs/`,
+ * and the private `home/`, `tmp/` and `sandboxes/`. It is created with the Tenant and removed
+ * with it; nothing in it says whether the Tenant exists.
+ *
+ * - `create` makes the directory, then creates, migrates and bootstraps the schema in one
+ *   transaction. A schema that already exists is `exists`; the module compares its bootstrap.
+ * - `open` migrates an older schema forward and opens the Tenant Runtime on the schema's
+ *   Session Store. A missing schema is `TenantNotFoundError`; a schema newer than this
+ *   Runtime, a failed migration, an unreadable envelope or vault ciphertext without its key
+ *   throws that quarantine. A failure outside the Tenant (Postgres unreachable, its sweep
+ *   not armed) is `TenantUnavailableError`, which the module does not cache.
+ * - `trash` drops the schema and removes the directory. There is no `trash/` copy: the key
+ *   is useless without the schema.
+ */
+import { mkdirSync, rmSync } from "node:fs";
+import { tenantSchemaName } from "../store/postgres/names.js";
+import { createPostgresTenantCatalog } from "../store/postgres/tenants.js";
+import { tenantPaths } from "./paths.js";
+import { QuarantineError, TenantConflictError } from "./quarantine.js";
+import { TenantNotFoundError, TenantUnavailableError, } from "./types.js";
+/** Repair instructions for a Postgres Tenant, naming its schema. */
+function repairFor(code, tenantId) {
+    const status = `nylo tenant status ${tenantId}`;
+    const schema = tenantSchemaName(tenantId);
+    switch (code) {
+        case "schema-too-new":
+            return `${status} — schema ${schema} was migrated by a newer Runtime; run that version or newer`;
+        case "migration-failed":
+            return `${status} — inspect the Runtime log for the failed migration of ${schema}, fix it, then restart the Runtime`;
+        case "envelope-invalid":
+            return `${status} — the tenant table of schema ${schema} is missing or invalid; restore the schema from a Postgres backup`;
+        case "kek-missing":
+            return `${status} — restore vault-kek under the Tenant directory (ciphertext cannot be opened without it)`;
+        default:
+            return `${status} — inspect the Runtime log and Postgres, then restart the Runtime`;
+    }
+}
+function unavailable(tenantId, cause) {
+    return cause instanceof TenantUnavailableError
+        ? cause
+        : new TenantUnavailableError(tenantId, { cause });
+}
+function quarantined(reason, tenantId) {
+    return new QuarantineError({ ...reason, repair: repairFor(reason.code, tenantId) });
+}
+export function createPostgresTenantStore(options) {
+    const catalog = createPostgresTenantCatalog({
+        sql: options.sql,
+        ...(options.migrations ? { migrations: options.migrations } : {}),
+        onError: (error) => options.logger?.error("post-commit step failed", {
+            message: error instanceof Error ? error.message : String(error),
+        }),
+    });
+    const paths = (id) => tenantPaths(options.hostRoot, id);
+    function makeDirectory(id) {
+        const p = paths(id);
+        mkdirSync(p.root, { recursive: true, mode: 0o700 });
+        for (const dir of [p.home, p.tmp, p.sandboxes, p.pluginData, p.logs])
+            mkdirSync(dir, { recursive: true });
+    }
+    async function readEnvelope(id) {
+        try {
+            return await catalog.readEnvelope(id);
+        }
+        catch (error) {
+            if (!(error instanceof QuarantineError))
+                throw unavailable(id, error);
+            // Dropped since it was listed (deleted by another process).
+            if (!(await catalog.tenantExists(id).catch(() => true)))
+                throw new TenantNotFoundError(id);
+            throw quarantined(error.toQuarantine(), id);
+        }
+    }
+    return {
+        enumerate: () => catalog.listTenantIds(),
+        readEnvelope,
+        async create(envelope, bootstrap) {
+            makeDirectory(envelope.id);
+            try {
+                const result = await catalog.createTenant({ envelope, principals: bootstrap });
+                return result.status;
+            }
+            catch (error) {
+                // An existing Tenant with other bootstrap material; the module reports the conflict.
+                if (error instanceof TenantConflictError)
+                    return "exists";
+                throw error;
+            }
+        },
+        bootstrapMatches: (id, bootstrap) => catalog.bootstrapMatches(id, bootstrap),
+        async open(id) {
+            const result = await catalog
+                .openTenant(id)
+                .catch((error) => {
+                throw unavailable(id, error);
+            });
+            if (result.status === "not-found")
+                throw new TenantNotFoundError(id);
+            if (result.status === "quarantined")
+                throw quarantined(result.reason, id);
+            if (result.migrated.from !== result.migrated.to)
+                options.logger?.info("tenant schema migrated", {
+                    tenantId: id,
+                    from: result.migrated.from,
+                    to: result.migrated.to,
+                });
+            try {
+                makeDirectory(id);
+                const config = options.configFor(id);
+                return await options.openRuntime({ ...config, tenantId: id }, { store: result.store, envelope: result.envelope });
+            }
+            catch (error) {
+                await result.store.close().catch(() => undefined);
+                // The Runtime's own quarantines (`kek-missing`) get this store's repair wording.
+                const reason = error?.quarantine;
+                if (reason)
+                    throw quarantined(reason, id);
+                if (error instanceof QuarantineError)
+                    throw error;
+                // Anything else failed outside the Tenant (Postgres, arming its sweep in Restate):
+                // the next use tries again rather than quarantining it.
+                throw unavailable(id, error);
+            }
+        },
+        async trash(id) {
+            await catalog.deleteTenant(id);
+            rmSync(paths(id).root, { recursive: true, force: true });
+        },
+        async removePartial(id) {
+            if (await catalog.tenantExists(id))
+                return;
+            rmSync(paths(id).root, { recursive: true, force: true });
+        },
+    };
+}

package/dist/tenant/streams.d.ts

@@ -0,0 +1,126 @@
+import type { SessionStore } from "../store/types.js";
+import { type Relay } from "../streams/relay.js";
+import { type DurableStreams } from "../streams/types.js";
+import type { TenantContext } from "./context.js";
+export interface WireStreamsOptions {
+    tenantId: string;
+    store: SessionStore;
+    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 state of the Tenant's basin as this process last saw it. */
+export interface BasinStatus {
+    /** `ensureTenant` succeeded and no append has failed since. */
+    ready: boolean;
+    /** Failed `ensureTenant` attempts since the basin was last ready. */
+    failures: number;
+    /** 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`). */
+export interface StreamsWiring {
+    readonly streams: DurableStreams;
+    readonly relay: Relay;
+    /** The 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. */
+    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.
+ */
+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.
+ */
+export declare function requestStreamCollection(ctx: TenantContext): Promise<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.
+ */
+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>;
+/** 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 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`).
+ */
+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>;