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

package/dist/server/server.d.ts

@@ -0,0 +1,221 @@
+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 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>;
+}
+/**
+ * Checks whether browser composition may start a private native listener.
+ *
+ * @internal
+ */
+export declare const serverBuilderAccess: Readonly<{
+    isLoopback(server: Server): boolean;
+}>;
+/**
+ * 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;
+    }[];
+}
+/**
+ * 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":"AAoBA,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;AAkBvC;;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;;IAiBjB;;;;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;;;;;;;;;;;;;OAaG;IACH,GAAG,IAAI,OAAO,CAAC,aAAa,CAAC;CAkP9B;AAkBD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,QAAQ,CAAC;IACzC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;CACrC,CAKC,CAAC;AAQH;;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;CACtD;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"}