opinionated-machine 10.5.0 → 11.2.0

package/dist/lib/DIContext.d.ts

@@ -50,7 +50,11 @@ export declare class DIContext<Dependencies extends object, Config extends objec
      * like `@opinionated-machine/gateway-envoy` or
      * `@opinionated-machine/gateway-krakend` to produce a config.
      *
-     * SSE and dual-mode controllers are not included in v1.
+     * SSE and dual-mode routes declared through `AbstractApiController` are
+     * always included and carry a `streaming: 'sse' | 'dual'` marker. Routes
+     * from legacy `AbstractSSEController` / `AbstractDualModeController`
+     * controllers are included only when `includeStreamingControllers: true`
+     * is passed (off by default so existing manifests don't silently grow).
      *
      * @example
      * ```ts
@@ -116,6 +120,14 @@ export declare class DIContext<Dependencies extends object, Config extends objec
     registerDualModeRoutes(app: FastifyInstance<any, any, any, any>, options?: RegisterDualModeRoutesOptions): void;
     private applyDualModeRouteOptions;
     private applySSERouteOptions;
+    /**
+     * Apply registration-time options to an SSE/dual-mode route before app.route().
+     *
+     * Shared by the SSE-only and dual-mode registration paths: both apply the same
+     * pre-handlers, rate limit and `sse` field defaults. Route-level options
+     * (buildHandler / buildApiRoute) take precedence over these.
+     */
+    private applyStreamRouteOptions;
     private applyPreHandlers;
     private applyRateLimit;
     destroy(): Promise<void>;

package/dist/lib/DIContext.js

@@ -159,7 +159,11 @@ export class DIContext {
      * like `@opinionated-machine/gateway-envoy` or
      * `@opinionated-machine/gateway-krakend` to produce a config.
      *
-     * SSE and dual-mode controllers are not included in v1.
+     * SSE and dual-mode routes declared through `AbstractApiController` are
+     * always included and carry a `streaming: 'sse' | 'dual'` marker. Routes
+     * from legacy `AbstractSSEController` / `AbstractDualModeController`
+     * controllers are included only when `includeStreamingControllers: true`
+     * is passed (off by default so existing manifests don't silently grow).
      *
      * @example
      * ```ts
@@ -183,6 +187,18 @@ export class DIContext {
             const controller = this.diContainer.resolve(name);
             collected.push({ name, kind: 'api', controller });
         }
+        if (options.includeStreamingControllers) {
+            for (const name of this.sseControllerNames) {
+                // biome-ignore lint/suspicious/noExplicitAny: any SSE controller works here
+                const controller = this.diContainer.resolve(name);
+                collected.push({ name, kind: 'sse-legacy', controller });
+            }
+            for (const name of this.dualModeControllerNames) {
+                // biome-ignore lint/suspicious/noExplicitAny: any dual-mode controller works here
+                const controller = this.diContainer.resolve(name);
+                collected.push({ name, kind: 'dualmode-legacy', controller });
+            }
+        }
         return buildGatewayManifestFrom(collected, options);
     }
     /**
@@ -273,15 +289,19 @@ export class DIContext {
         }
     }
     applyDualModeRouteOptions(route, options) {
-        if (options?.preHandler) {
-            this.applyPreHandlers(route, options.preHandler);
-        }
-        if (options?.rateLimit) {
-            this.applyRateLimit(route, options.rateLimit);
-        }
-        applyGlobalSSEOptions(route, options);
+        this.applyStreamRouteOptions(route, options);
     }
     applySSERouteOptions(route, options) {
+        this.applyStreamRouteOptions(route, options);
+    }
+    /**
+     * Apply registration-time options to an SSE/dual-mode route before app.route().
+     *
+     * Shared by the SSE-only and dual-mode registration paths: both apply the same
+     * pre-handlers, rate limit and `sse` field defaults. Route-level options
+     * (buildHandler / buildApiRoute) take precedence over these.
+     */
+    applyStreamRouteOptions(route, options) {
         if (options?.preHandler) {
             this.applyPreHandlers(route, options.preHandler);
         }

package/dist/lib/DIContext.js.map

@@ -1 +1 @@
-{"version":3,"file":"DIContext.js","sourceRoot":"","sources":["../../lib/DIContext.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"DIContext.js","sourceRoot":"","sources":["../../lib/DIContext.ts"],"names":[],"mappings":"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"}

package/dist/lib/api-contracts/apiRouteBuilder.d.ts

@@ -1,7 +1,9 @@
-import { type ApiContract } from '@lokalise/api-contracts';
+import type { ApiContract } from '@lokalise/api-contracts';
 import { type ApiRouteOptions as FastifyApiRouteOptions, type InferApiHandler } from '@lokalise/fastify-api-contracts';
 import type { RouteOptions } from 'fastify';
 import type { GatewayMetadata } from '../gateway/gatewayTypes.ts';
+import type { SSERoomBroadcaster } from '../sse/rooms/SSERoomBroadcaster.ts';
+import { type SSERoomsOptions } from './apiSseConnectionRegistry.ts';
 /**
  * Options for configuring an ApiContract route.
  *
@@ -46,6 +48,42 @@ export type ApiRouteOptions<Contract extends ApiContract> = FastifyApiRouteOptio
      * ```
      */
     gatewayMetadata?: GatewayMetadata<Contract>;
+    /**
+     * Enable SSE rooms for this route by passing the shared `SSERoomBroadcaster`
+     * from the DI container. Sessions opened by the route's SSE handler are
+     * registered with the broadcaster (so `broadcastToRoom`/`broadcastMessage`
+     * reach them), get room operations via {@link getSessionRooms}, and are
+     * cleaned up (rooms left, dedup cache cleared) when the connection closes.
+     *
+     * Without this option `getSessionRooms()` returns no-ops and the session
+     * receives no room broadcasts.
+     *
+     * Pass an {@link SSERoomsOptions} object instead of the bare broadcaster to
+     * declare an `authorizeJoin` scope check (so a room name built from a path
+     * param cannot leak across tenants) and a `maxSessionLifetimeMs` bound (so
+     * authorization checked at connect cannot stay in force forever).
+     *
+     * @example
+     * ```ts
+     * buildApiRoute(contracts.watchProject, this.watch, { sseRooms: this.roomBroadcaster })
+     * // inside the handler:
+     * const session = sse.start('keepAlive')
+     * getSessionRooms(session).join(`project:${request.params.projectId}`)
+     * ```
+     *
+     * @example
+     * ```ts
+     * buildApiRoute(contracts.watchProject, this.watch, {
+     *   sseRooms: {
+     *     broadcaster: this.roomBroadcaster,
+     *     authorizeJoin: (session, room) =>
+     *       this.membership.canRead(session.request.user, room),
+     *     maxSessionLifetimeMs: 30 * 60 * 1000,
+     *   },
+     * })
+     * ```
+     */
+    sseRooms?: SSERoomBroadcaster | SSERoomsOptions;
 };
 /**
  * Build a Fastify `RouteOptions` object from an `ApiContract` + handler.
@@ -56,10 +94,14 @@ export type ApiRouteOptions<Contract extends ApiContract> = FastifyApiRouteOptio
  * See its docs for the `(request, reply, context) => { status, body }`
  * handler model and `context.sse` streaming.
  *
- * On top of the package builder this adds one option: `gatewayMetadata` —
- * per-route gateway policy with header / query keys narrowed to the
- * contract; equivalent to wrapping the result with `withGatewayMetadata`.
- * See `ApiRouteOptions` for full details.
+ * On top of the package builder this adds:
+ * - `gatewayMetadata` — per-route gateway policy with header / query keys
+ *   narrowed to the contract; equivalent to wrapping the result with
+ *   `withGatewayMetadata`. See `ApiRouteOptions` for full details.
+ * - `sseRooms` — wires SSE rooms for the route (see `ApiRouteOptions`).
+ * - a `streaming: 'sse' | 'dual'` marker on SSE-capable routes, read back by
+ *   the gateway manifest builder so generators can apply streaming-appropriate
+ *   timeouts and buffering.
  *
  * @returns Fastify `RouteOptions` ready to pass to `app.route()`
  */

package/dist/lib/api-contracts/apiRouteBuilder.js

@@ -1,7 +1,41 @@
-import { getSseSchemaByEventName, } from '@lokalise/api-contracts';
+import { getSseSchemaByEventName, hasAnySuccessSseResponse, isContentResponseEntry, isSseBody, SUCCESSFUL_HTTP_STATUS_CODES, } from '@lokalise/api-contracts';
 import { buildFastifyApiRoute, } from '@lokalise/fastify-api-contracts';
+import { attachRouteStreamingMode } from "../gateway/routeStreaming.js";
 import { attachGatewayMetadata } from "../gateway/withGatewayMetadata.js";
 import { attachSSESendDiagnostics, reportSSEHandlerOutcome } from "../sse/sseSendDiagnostics.js";
+import { withSessionRooms } from "./apiSseConnectionRegistry.js";
+/**
+ * True when the contract's success response for a status code has a non-SSE
+ * representation as well — i.e. the route can answer a plain HTTP request.
+ */
+function isSuccessResponseDual(value) {
+    if (isContentResponseEntry(value)) {
+        // A content-map entry offers a non-SSE representation when it allows an empty
+        // body or declares any non-SSE media type descriptor.
+        if (value.allowNoBody || !value.content)
+            return true;
+        return Object.values(value.content).some((descriptor) => !isSseBody(descriptor));
+    }
+    // A bare Zod schema is a JSON response, which always has a non-SSE representation.
+    return true;
+}
+/**
+ * Derive how a contract streams, for the gateway streaming marker.
+ *
+ * Mirrors `ContractResponseMode` from `@lokalise/api-contracts` at runtime:
+ * a contract with no SSE success response is plain, one whose SSE statuses all
+ * lack a non-SSE representation is `'sse'`, and one that offers both is `'dual'`.
+ */
+function getContractStreamingMode(contract) {
+    if (!hasAnySuccessSseResponse(contract))
+        return undefined;
+    for (const code of SUCCESSFUL_HTTP_STATUS_CODES) {
+        const value = contract.responsesByStatusCode[code];
+        if (value && isSuccessResponseDual(value))
+            return 'dual';
+    }
+    return 'sse';
+}
 /**
  * Build a Fastify `RouteOptions` object from an `ApiContract` + handler.
  *
@@ -11,24 +45,39 @@ import { attachSSESendDiagnostics, reportSSEHandlerOutcome } from "../sse/sseSen
  * See its docs for the `(request, reply, context) => { status, body }`
  * handler model and `context.sse` streaming.
  *
- * On top of the package builder this adds one option: `gatewayMetadata` —
- * per-route gateway policy with header / query keys narrowed to the
- * contract; equivalent to wrapping the result with `withGatewayMetadata`.
- * See `ApiRouteOptions` for full details.
+ * On top of the package builder this adds:
+ * - `gatewayMetadata` — per-route gateway policy with header / query keys
+ *   narrowed to the contract; equivalent to wrapping the result with
+ *   `withGatewayMetadata`. See `ApiRouteOptions` for full details.
+ * - `sseRooms` — wires SSE rooms for the route (see `ApiRouteOptions`).
+ * - a `streaming: 'sse' | 'dual'` marker on SSE-capable routes, read back by
+ *   the gateway manifest builder so generators can apply streaming-appropriate
+ *   timeouts and buffering.
  *
  * @returns Fastify `RouteOptions` ready to pass to `app.route()`
  */
 export function buildApiRoute(contract, handler, options) {
-    // Gateway metadata is stamped via Symbol, not spread into Fastify options.
-    const { gatewayMetadata, ...fastifyOptions } = options ?? {};
+    // Gateway metadata is stamped via Symbol, not spread into Fastify options;
+    // `sseRooms` is framework-level and composed into the SSE lifecycle hooks.
+    const { gatewayMetadata, sseRooms, ...passthroughOptions } = options ?? {};
+    const fastifyOptions = sseRooms
+        ? withSessionRooms(sseRooms, passthroughOptions)
+        : passthroughOptions;
     const schemaByEventName = getSseSchemaByEventName(contract);
     const built = buildFastifyApiRoute(contract, handler, schemaByEventName ? withSendDiagnostics(fastifyOptions, schemaByEventName) : fastifyOptions);
     // Recording a failed send is only half of the diagnostic: whether the route recovered from
     // it decides whether a test reading the stream should fail on it. That is what the handler's
-    // own outcome says, so it is observed here — for scoped requests only.
+    // own outcome says, so it is observed here, for scoped requests only.
     const route = schemaByEventName
         ? { ...built, handler: reportSSEHandlerOutcome(built.handler) }
         : built;
+    // Mark streaming routes (derived from the contract's response mode) so
+    // gateway generators can apply streaming-appropriate timeouts/buffering.
+    // After the spread above: it drops the non-enumerable symbol the stamp sets.
+    const streamingMode = getContractStreamingMode(contract);
+    if (streamingMode) {
+        attachRouteStreamingMode(route, streamingMode);
+    }
     return gatewayMetadata !== undefined ? attachGatewayMetadata(route, gatewayMetadata) : route;
 }
 /**

package/dist/lib/api-contracts/apiRouteBuilder.js.map

@@ -1 +1 @@
-{"version":3,"file":"apiRouteBuilder.js","sourceRoot":"","sources":["../../../lib/api-contracts/apiRouteBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,uBAAuB,GAExB,MAAM,yBAAyB,CAAA;AAChC,OAAO,EACL,oBAAoB,GAGrB,MAAM,iCAAiC,CAAA;AAGxC,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAA;AACzE,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAA;AAgDhG;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,aAAa,CAC3B,QAAkB,EAClB,OAAkC,EAClC,OAAmC;IAEnC,2EAA2E;IAC3E,MAAM,EAAE,eAAe,EAAE,GAAG,cAAc,EAAE,GAAG,OAAO,IAAI,EAAE,CAAA;IAC5D,MAAM,iBAAiB,GAAG,uBAAuB,CAAC,QAAQ,CAAC,CAAA;IAC3D,MAAM,KAAK,GAAG,oBAAoB,CAChC,QAAQ,EACR,OAAO,EACP,iBAAiB,CAAC,CAAC,CAAC,mBAAmB,CAAC,cAAc,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC,cAAc,CAC5F,CAAA;IACD,2FAA2F;IAC3F,6FAA6F;IAC7F,uEAAuE;IACvE,MAAM,KAAK,GAAG,iBAAiB;QAC7B,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,uBAAuB,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE;QAC/D,CAAC,CAAC,KAAK,CAAA;IACT,OAAO,eAAe,KAAK,SAAS,CAAC,CAAC,CAAC,qBAAqB,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;AAC9F,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,SAAS,mBAAmB,CAC1B,OAA+B,EAC/B,iBAAkC;IAElC,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CAAA;IAC7B,OAAO;QACL,GAAG,OAAO;QACV,uFAAuF;QACvF,+DAA+D;QAC/D,SAAS,EAAE,CAAC,OAAO,EAAE,EAAE;YACrB,wBAAwB,CAAC,OAAO,EAAE,iBAAiB,CAAC,CAAA;YACpD,OAAO,SAAS,EAAE,CAAC,OAAO,CAAC,CAAA;QAC7B,CAAC;KACF,CAAA;AACH,CAAC"}
+{"version":3,"file":"apiRouteBuilder.js","sourceRoot":"","sources":["../../../lib/api-contracts/apiRouteBuilder.ts"],"names":[],"mappings":"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"}

package/dist/lib/api-contracts/apiSseConnectionRegistry.d.ts

@@ -0,0 +1,182 @@
+import type { SSEEventSchemas } from '@lokalise/api-contracts';
+import type { ApiRouteOptions as FastifyApiRouteOptions, SSESession } from '@lokalise/fastify-api-contracts';
+import type { SSERoomBroadcaster } from '../sse/rooms/SSERoomBroadcaster.ts';
+import type { SSERoomOperations } from '../sse/rooms/types.ts';
+import type { SSEMessage } from '../sse/sseTypes.ts';
+/**
+ * A join whose `authorizeJoin` verdict has not resolved yet.
+ *
+ * An async verdict lands after `join()` has already returned, so anything that
+ * revokes access in between (a `leave`, an `evictFromRoom`, an eviction, a
+ * closed room, the session closing) has to be able to cancel it. Without that
+ * the resolved verdict re-adds the connection to a room it was just removed
+ * from, and the revocation silently does not stick.
+ */
+export type PendingJoin = {
+    readonly room: string;
+    cancelled: boolean;
+};
+export declare class ApiSseConnectionRegistry {
+    private readonly connections;
+    /** In-flight async joins per connection id. Empty for a synchronous verdict. */
+    private readonly pendingJoins;
+    private readonly broadcaster;
+    constructor(broadcaster: SSERoomBroadcaster);
+    /**
+     * Register an active SSE connection with its send function.
+     * The send function must return `false` (not throw) on delivery failure so
+     * room broadcasts keep fanning out to the remaining connections.
+     *
+     * Pass `close` to make the connection evictable — without it {@link evict}
+     * can stop delivery but cannot terminate the stream.
+     */
+    register(connectionId: string, send: (message: SSEMessage) => Promise<boolean>, close?: () => void): void;
+    /**
+     * Remove a connection: drops the sender, leaves all rooms, and clears the
+     * broadcaster's dedup cache for the connection.
+     */
+    unregister(connectionId: string): void;
+    /**
+     * Record an async `authorizeJoin` verdict that is still in flight, so a
+     * revocation arriving before it resolves can cancel it.
+     *
+     * Pair every call with {@link settlePendingJoin}; the room wiring in
+     * {@link withSessionRooms} does this for routes.
+     */
+    beginPendingJoin(connectionId: string, room: string): PendingJoin;
+    /**
+     * Retire an in-flight join.
+     *
+     * @returns `true` when the join is still valid and may be applied, `false`
+     *   when it was cancelled while the verdict was pending.
+     */
+    settlePendingJoin(connectionId: string, pending: PendingJoin): boolean;
+    /**
+     * Cancel in-flight joins for a connection — all of them, or only those for
+     * one room. A cancelled join is dropped when its verdict resolves.
+     *
+     * @returns How many joins were cancelled.
+     */
+    cancelPendingJoins(connectionId: string, room?: string): number;
+    /**
+     * Terminate one connection: leave its rooms, stop delivering to it, and
+     * close its stream.
+     *
+     * This is the revocation path. Authorization is checked when a stream opens
+     * and then goes stale, so removing a principal's access has to be able to
+     * end the streams that access already opened; without a call like this, a
+     * revoked user keeps receiving broadcasts until they close the tab.
+     *
+     * A client that reconnects (as `@opinionated-machine/sse-fallback` does)
+     * comes back through the route's own authorization, so an eviction of a
+     * still-authorized principal costs a reconnect, not a broken surface.
+     *
+     * @returns `true` when a connection was registered under that id.
+     */
+    evict(connectionId: string): boolean;
+    /**
+     * Remove one connection from one room, leaving its other rooms and its
+     * stream intact. For revoking access to a single scope.
+     *
+     * A join whose async `authorizeJoin` verdict is still pending counts as
+     * membership here: the connection is not in the room yet, but it is about to
+     * be, and letting that land after a revocation would undo it.
+     *
+     * @returns `true` when the connection was in the room, or was on its way in.
+     */
+    evictFromRoom(room: string, connectionId: string): boolean;
+    /**
+     * Evict every connection currently in a room, terminating their streams.
+     * For revoking a whole scope (a deleted project, a disbanded team).
+     *
+     * Only connections on THIS node are closed — room membership elsewhere in
+     * the cluster is another node's registry to evict, so a revocation event
+     * has to reach every node.
+     *
+     * Joins still awaiting an async `authorizeJoin` verdict are cancelled rather
+     * than evicted: they hold no membership yet, so the revocation just denies
+     * them the room and leaves their other rooms and their stream alone. They
+     * are not counted in the return value for the same reason.
+     *
+     * @returns How many connections were evicted here.
+     */
+    closeRoom(room: string): number;
+}
+/**
+ * Get (or lazily create) the shared registry for a broadcaster.
+ * Ensures `registerSender` is called exactly once per broadcaster no matter
+ * how many routes opt into rooms.
+ */
+export declare function getApiSseConnectionRegistry(broadcaster: SSERoomBroadcaster): ApiSseConnectionRegistry;
+/**
+ * Room operations for an SSE session opened by a `buildApiRoute` route.
+ *
+ * Returns no-ops when the route did not pass `sseRooms` — mirroring the legacy
+ * `session.rooms` accessor, which is inert on controllers without a broadcaster.
+ *
+ * @example
+ * ```ts
+ * const session = sse.start('keepAlive')
+ * getSessionRooms(session).join(`project:${request.params.projectId}`)
+ * ```
+ */
+export declare function getSessionRooms<Events extends SSEEventSchemas, Context>(session: SSESession<Events, Context>): SSERoomOperations;
+/**
+ * Room wiring for a route, when the bare broadcaster is not enough.
+ *
+ * Pass an `SSERoomBroadcaster` directly for the default behaviour; pass this
+ * object to add a scope check on joins and a bounded session lifetime.
+ */
+export type SSERoomsOptions = {
+    /** The broadcaster whose rooms this route's sessions join. */
+    broadcaster: SSERoomBroadcaster;
+    /**
+     * Decide whether a session may join a room. Declared once per route, so the
+     * scope check is not left to every handler body.
+     *
+     * Without it, `getSessionRooms(session).join(room)` joins whatever room
+     * string the handler names, and nothing checks that the authenticated
+     * principal belongs to that room's scope — a path param read straight into
+     * a room name is a cross-tenant leak.
+     *
+     * Return `false` (or reject) to refuse; the refusal is logged on the
+     * request logger and the join is dropped. A synchronous verdict is applied
+     * before `join()` returns; an async one is applied when it resolves, so the
+     * session joins a moment later — the client's reconciliation poll covers
+     * anything broadcast in between. A `leave`, an `evictFromRoom`, an `evict`,
+     * a `closeRoom` or the session closing while the verdict is pending cancels
+     * it, so a revocation cannot be undone by a join that was already in flight.
+     */
+    authorizeJoin?: (session: SSESession, room: string) => boolean | Promise<boolean>;
+    /**
+     * Close the session gracefully after this many milliseconds.
+     *
+     * Authorization is checked when the stream opens and then goes stale: a
+     * principal removed from a scope keeps receiving events for as long as the
+     * connection lives. A bounded lifetime forces a reconnect, and the reconnect
+     * re-runs authentication and authorization — making this both the
+     * token-refresh mechanism and the backstop for a revocation that never
+     * reached {@link ApiSseConnectionRegistry.evict}.
+     *
+     * A client that treats a server close as a routine reconnect (with
+     * `Last-Event-ID` and a reconciliation poll, as
+     * `@opinionated-machine/sse-fallback` does) makes this invisible to users.
+     */
+    maxSessionLifetimeMs?: number;
+};
+/**
+ * Compose room wiring into a route's SSE lifecycle hooks.
+ *
+ * On connect the session is registered with the broadcaster's registry and its
+ * room operations are published for {@link getSessionRooms}; on close the
+ * connection is unregistered (rooms left, dedup cache cleared). The route's own
+ * `onConnect` / `onClose` hooks still run — room wiring is applied first on
+ * connect (so a hook can already join rooms) and last on close.
+ *
+ * `onConnect` is invoked synchronously by the package's `sse.start()`, so the
+ * registration is in place before `start()` returns to the handler.
+ *
+ * Pass {@link SSERoomsOptions} instead of a bare broadcaster to add an
+ * `authorizeJoin` scope check or a `maxSessionLifetimeMs` bound.
+ */
+export declare function withSessionRooms<Options extends FastifyApiRouteOptions>(config: SSERoomBroadcaster | SSERoomsOptions, options: Options): Options;