@spine-event-engine/server 2.0.0-snapshot.2

package/dist/server/server.d.ts

@@ -0,0 +1,389 @@
+import type { AuthorizationPolicy, Clock, ContextResolver, OpaqueSessionCookies, SessionResolver, SubscriptionBindings } from "@spine-event-engine/auth";
+import type { TypeRegistryLookup } from "@spine-event-engine/core";
+import type { NodeDiscovery } from "@spine-event-engine/deployment";
+import { BoundedContext, BoundedContextBuilder } from "../context/bounded-context.js";
+import type { StandSubscriptionRegistry } from "../stand/subscription-registry.js";
+import { type SpineServicesOptions } from "../services/spine-services.js";
+/**
+ * Performs work coupled to listener readiness and network shutdown.
+ */
+export interface ListenerLifecycle {
+    /**
+     * Starts after the native listener accepts connections.
+     *
+     * @returns A value or promise that settles after readiness work.
+     */
+    start(): unknown;
+    /**
+     * Completes before the native listener stops accepting connections.
+     *
+     * @returns A value or promise that settles after shutdown work.
+     */
+    close(): unknown;
+}
+/**
+ * Configures and starts local Spine Connect/gRPC-compatible services.
+ *
+ * A server assembles its bounded contexts, completes finite environment
+ * delivery recovery, and opens its generated services before accepting network
+ * requests. It also owns the ordered cleanup of contexts and resources added
+ * to this assembly.
+ */
+export declare class Server {
+    #private;
+    /**
+     * Creates a server builder.
+     *
+     * @param options Configures local network, contexts, resources, and services.
+     */
+    constructor(options?: ServerOptions);
+    /**
+     * Creates a local-only server builder for one port.
+     *
+     * @param port Selects the listener port, or zero for an ephemeral port.
+     * @param options Supplies all server options except the port.
+     * @returns A configured server builder.
+     */
+    static atPort(port: number, options?: Omit<ServerOptions, "port">): Server;
+    /**
+     * Adds one bounded context or builder to the assembly.
+     *
+     * Builders assemble during {@link start} before recovery and listener open.
+     * They use {@link ServerEnvironment.storageFactory} unless a more specific
+     * `withStorageFactory(...)` factory is selected. The running server owns and
+     * closes added contexts only after services, sessions, and active work stop.
+     *
+     * @param context Supplies the context or builder to expose.
+     * @returns This server builder.
+     */
+    add(context: BoundedContext | BoundedContextBuilder): this;
+    /**
+     * Adds a framework closeable owned by this server assembly.
+     *
+     * @param resource Supplies the resource to close after contexts.
+     * @returns This server builder.
+     */
+    addResource(resource: {
+        close(): unknown;
+    }): this;
+    /**
+     * Adds work that starts after listener readiness and closes before network intake stops.
+     *
+     * Failed starts roll back admitted lifecycles in reverse admission order. A
+     * failed close remains retryable and prevents network shutdown until it settles.
+     *
+     * @param lifecycle Supplies listener-coupled lifecycle work, such as GCE registration.
+     * @returns This server builder.
+     */
+    addListenerLifecycle(lifecycle: ListenerLifecycle): this;
+    /**
+     * Starts the server after completing assembly and delivery recovery.
+     *
+     * Built contexts attach to delivery in deterministic input order before the
+     * generated services and listener open. A failed assembly or listener open
+     * leaves no listener and closes acquired resources. Network cleanup is a hard
+     * gate before delivery or dependencies close.
+     * It shares only a caller-managed active environment generation, rejects
+     * while run-managed ownership is active, installs no signal handlers, and
+     * never closes the environment.
+     * A later call after incomplete cleanup retries only that cleanup and leaves
+     * this server terminal. A fresh server may reuse the singleton environment.
+     * Concurrent callers share one start or cleanup attempt.
+     *
+     * @returns The running server once its listener accepts requests.
+     */
+    start(): Promise<RunningServer>;
+    /**
+     * Starts this server with process-owned `SIGINT` and `SIGTERM` shutdown.
+     *
+     * This is the normal application entry point. Embedded applications should
+     * use {@link start} and keep ownership of process signals themselves.
+     * Concurrent calls on one builder return one managed handle. Run-managed
+     * siblings share an active generation but reject while caller-managed
+     * ownership is active. The final local environment-owning run retirement
+     * permanently closes its environment; a standalone browser Gateway remains
+     * signal-managed but never owns or closes that environment. A failed final
+     * close stays retryable through `close()` or a later process signal.
+     * Caller-managed servers never close their environment.
+     *
+     * @returns The running server after its listener accepts requests.
+     */
+    run(): Promise<RunningServer>;
+}
+/**
+ * Options for building a local Spine HTTP/2 service host.
+ */
+export interface ServerOptions {
+    /**
+     * Listener host. Defaults to local-only `127.0.0.1`.
+     *
+     * Use a broader host such as `0.0.0.0` only when callers should reach this
+     * process from outside the local machine.
+     */
+    readonly host?: string;
+    /**
+     * Listener port. Defaults to `0`, asking the OS for a free port.
+     */
+    readonly port?: number;
+    /**
+     * Maximum uncompressed bytes accepted for one RPC request message.
+     * Defaults to 4,194,304 bytes. Must be an integer from 1 through
+     * 4,294,967,295.
+     */
+    readonly readMaxBytes?: number;
+    /**
+     * Maximum uncompressed bytes emitted for one RPC or auth-callback response.
+     * Defaults to 4,194,304 bytes. Must be an integer from 1 through
+     * 4,294,967,295. An auth callback exceeding this bound receives 413.
+     */
+    readonly writeMaxBytes?: number;
+    /**
+     * Built bounded contexts or builders owned by this server assembly.
+     *
+     * Builders in this list are assembled during {@link Server.start} before
+     * listener open. They use {@link ServerEnvironment.storageFactory} unless
+     * `withStorageFactory(...)` already selected a more specific local factory.
+     */
+    readonly contexts?: readonly (BoundedContext | BoundedContextBuilder)[];
+    /**
+     * Service-level options for Command, Query, and Subscription routes.
+     */
+    readonly services?: Omit<SpineServicesOptions, "contexts">;
+    /**
+     * Extra framework-owned closeables to close after contexts become safe to close.
+     */
+    readonly resources?: readonly {
+        close(): unknown;
+    }[];
+    /**
+     * Browser admission and listener configuration. When present, the native
+     * HTTP/2 listener remains private on loopback and this public listener
+     * becomes the returned server URL.
+     */
+    readonly browser?: BrowserServerOptions;
+}
+/**
+ * Selects exactly one browser admission mode and its binding ownership.
+ *
+ * An authenticated listener supplies `sessions` and may supply named durable
+ * `bindings`. A public listener supplies `publicAccess: true`; it owns
+ * process-local bindings itself and therefore cannot accept `bindings`.
+ */
+export type BrowserAdmission = {
+    /**
+     * Resolves authenticated application sessions from incoming credentials.
+     */
+    readonly sessions: SessionResolver;
+    /**
+     * Excludes non-session public admission from authenticated mode.
+     */
+    readonly publicAccess?: never;
+    /**
+     * Supplies named subscription bindings owned by the authenticated application.
+     */
+    readonly bindings?: SubscriptionBindings;
+} | {
+    /**
+     * Excludes session resolution from public mode.
+     */
+    readonly sessions?: never;
+    /**
+     * Admits requests under the framework-owned non-session public principal.
+     */
+    readonly publicAccess: true;
+    /**
+     * Prevents callers from supplying bindings that public mode does not own.
+     */
+    readonly bindings?: never;
+};
+/**
+ * Selects one separately hosted Spine backend or a non-empty fixed node set.
+ */
+export type BrowserBackend = {
+    /**
+     * Supplies one canonical backend HTTP(S) origin.
+     */
+    readonly baseUrl: string;
+    /**
+     * Excludes a multi-node backend list when one backend is supplied.
+     */
+    readonly baseUrls?: never;
+} | {
+    /**
+     * Excludes a single backend origin when a fixed node set is supplied.
+     */
+    readonly baseUrl?: never;
+    /**
+     * Supplies a non-empty fixed set of canonical backend HTTP(S) origins.
+     */
+    readonly baseUrls: readonly string[];
+};
+/**
+ * Common collaborators for every browser Server admission mode.
+ *
+ * Pair these with exactly one {@link BrowserAdmission} to form
+ * {@link BrowserServerOptions}.
+ */
+export interface BrowserServerCollaborators {
+    /**
+     * Public browser listener host. Defaults to the server host.
+     */
+    readonly host?: string;
+    /**
+     * Public browser listener port. Defaults to the server port.
+     */
+    readonly port?: number;
+    /**
+     * Selects one separately hosted Spine backend or a non-empty fixed node set.
+     *
+     * Each URL must be one canonical HTTP(S) origin without credentials, query,
+     * fragment, or a path beyond `/`. `baseUrl` and `baseUrls` are exclusive;
+     * fan-in is best effort, so clients re-query authoritative state after a
+     * duplicate update or generic loss notice.
+     */
+    readonly backend?: BrowserBackend;
+    /**
+     * Supplies changing complete membership for unary routing and native streams.
+     * Supplying discovery makes this a standalone Gateway, so the server does
+     * not assemble or own local contexts, services, resources, or listener
+     * lifecycles. When both backend and discovery are supplied, discovery is the
+     * active membership source and fixed backend values are not reconciled.
+     */
+    readonly discovery?: NodeDiscovery;
+    /**
+     * Application-owned, exact authentication endpoints exposed beside the fixed
+     * Spine RPC paths. These endpoints are not a general-purpose router.
+     */
+    readonly authRoutes?: readonly BrowserAuthRoute[];
+    /**
+     * Limits concurrently admitted application authentication requests across
+     * this listener. Defaults to 64 and must be a positive safe integer. Excess
+     * requests receive 503 before handler invocation; capacity recovers when an
+     * admitted request settles.
+     */
+    readonly maxActiveAuthRequests?: number;
+    /**
+     * Exact browser origins permitted to make RPC calls.
+     */
+    readonly origins: readonly string[];
+    /**
+     * Decodes application request content for authorization and actor resolution.
+     */
+    readonly registry?: TypeRegistryLookup;
+    /**
+     * Allows or rejects an admitted principal for each decoded request.
+     */
+    readonly authorize: AuthorizationPolicy["authorize"];
+    /**
+     * Independently resolves trusted actor and tenant context after authorization.
+     */
+    readonly contexts: ContextResolver;
+    /**
+     * Supplies trusted timestamps for gateway decisions.
+     */
+    readonly clock: Clock;
+    /**
+     * Enables strict opaque-cookie extraction alongside bearer credentials.
+     */
+    readonly cookies?: OpaqueSessionCookies;
+}
+/**
+ * Browser collaborators with exactly one admission and binding-ownership mode.
+ */
+export type BrowserServerOptions = BrowserServerCollaborators & BrowserAdmission;
+/**
+ * Configures one bounded application authentication request.
+ */
+export interface BrowserAuthRoute {
+    /**
+     * Selects the accepted HTTP method.
+     */
+    readonly method: "GET" | "POST";
+    /**
+     * Selects the exact canonical request path.
+     */
+    readonly path: string;
+    /**
+     * Lists exact browser origins allowed for this route.
+     */
+    readonly origins: readonly string[];
+    /**
+     * Allows an OAuth callback without an Origin header.
+     */
+    readonly allowMissingOrigin?: boolean;
+    /**
+     * Limits accepted request-body bytes.
+     */
+    readonly maxRequestBytes: number;
+    /**
+     * Limits request processing time in milliseconds.
+     */
+    readonly timeoutMs: number;
+    /**
+     * Handles one admitted authentication request.
+     *
+     * @param request Supplies the bounded Fetch request.
+     * @param signal Signals timeout, disconnect, or gateway close.
+     * @returns Returns the application response.
+     */
+    readonly onRequest: (request: Request, signal: AbortSignal) => Response | Promise<Response>;
+}
+/**
+ * Running local Spine service host.
+ */
+export interface RunningServer {
+    /**
+     * Host accepted by the listener.
+     */
+    readonly host: string;
+    /**
+     * Bound listener port.
+     */
+    readonly port: number;
+    /**
+     * Base URL for Connect gRPC-compatible clients.
+     */
+    readonly baseUrl: string;
+    /**
+     * Closes intake, delivery, contexts, and owned resources.
+     *
+     * It stops network intake and sessions, then drains
+     * accepted work before detaching delivery. A failed intake close blocks later
+     * phases until a retry. Sibling servers remain available. Caller-managed
+     * servers leave process-wide facilities available; closing the final
+     * run-managed server closes its environment. Concurrent calls share one
+     * attempt; later calls retry only unfinished cleanup, preserving stable
+     * flattened failure order.
+     *
+     * @returns A promise that settles after server-owned cleanup completes.
+     */
+    close(): Promise<void>;
+}
+/**
+ * Exposes framework-only facts about a local running server.
+ *
+ * @internal
+ */
+export interface RunningServerAccess {
+    /**
+     * Returns registry persistence facts for a framework-owned running server.
+     *
+     * @param server Supplies the local running server.
+     * @returns The context registry facts, or undefined for an opaque server.
+     */
+    subscriptionRegistries(server: RunningServer): readonly StandSubscriptionRegistry[] | undefined;
+    /**
+     * Returns completion after draining Delivery before managed network close.
+     *
+     * @param server Supplies the local running server.
+     * @returns Completion after its Delivery attachment drains.
+     */
+    drainDelivery(server: RunningServer): Promise<void>;
+}
+/**
+ * Provides framework-only `RunningServer` context facts.
+ *
+ * @internal
+ */
+export declare const runningServerAccess: RunningServerAccess;
+//# sourceMappingURL=server.d.ts.map

package/dist/server/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/server/server.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EACV,mBAAmB,EACnB,KAAK,EACL,eAAe,EACf,oBAAoB,EACpB,eAAe,EACf,oBAAoB,EACrB,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAEpE,OAAO,EACL,cAAc,EACd,qBAAqB,EAEtB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AACnF,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,+BAA+B,CAAC;AAmBvC;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAGhC;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC;IAEjB;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,qBAAa,MAAM;;IAkBjB;;;;OAIG;gBACS,OAAO,GAAE,aAAkB;IAkBvC;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,aAAa,EAAE,MAAM,CAAM,GAAG,MAAM;IAI9E;;;;;;;;;;OAUG;IACH,GAAG,CAAC,OAAO,EAAE,cAAc,GAAG,qBAAqB,GAAG,IAAI;IAK1D;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE;QAAE,KAAK,IAAI,OAAO,CAAA;KAAE,GAAG,IAAI;IAKjD;;;;;;;;OAQG;IACH,oBAAoB,CAAC,SAAS,EAAE,iBAAiB,GAAG,IAAI;IAKxD;;;;;;;;;;;;;;;OAeG;IACH,KAAK,IAAI,OAAO,CAAC,aAAa,CAAC;IAwC/B;;;;;;;;;;;;;;OAcG;IACH,GAAG,IAAI,OAAO,CAAC,aAAa,CAAC;CA4S9B;AAkBD;;GAEG;AACH,MAAM,WAAW,aAAa;IAG5B;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAEhC;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,cAAc,GAAG,qBAAqB,CAAC,EAAE,CAAC;IAExE;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,oBAAoB,EAAE,UAAU,CAAC,CAAC;IAE3D;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS;QAAE,KAAK,IAAI,OAAO,CAAA;KAAE,EAAE,CAAC;IAErD;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,oBAAoB,CAAC;CACzC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GACxB;IAGE;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IAEnC;;OAEG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,KAAK,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,oBAAoB,CAAC;CAC1C,GACD;IAGE;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;CAC3B,CAAC;AAEN;;GAEG;AACH,MAAM,MAAM,cAAc,GACtB;IAGE;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC;CAC3B,GACD;IAGE;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,KAAK,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC,CAAC;AAEN;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IAGzC;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAElC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;IAEnC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAElD;;;;;OAKG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAExC;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,CAAC;IAEvC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAC,WAAW,CAAC,CAAC;IAErD;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IAEnC;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,oBAAoB,CAAC;CACzC;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,0BAA0B,GAAG,gBAAgB,CAAC;AAEjF;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAG/B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IAEhC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAEtC;;OAEG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC7F;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAG5B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;;;;;;;;;OAYG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAGlC;;;;;OAKG;IACH,sBAAsB,CACpB,MAAM,EAAE,aAAa,GACpB,SAAS,yBAAyB,EAAE,GAAG,SAAS,CAAC;IAEpD;;;;;OAKG;IACH,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AAED;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,mBAShC,CAAC"}