@supalive/core 1.20.2 → 1.22.0

package/dist/types_server-hiwqDm4G.d.ts

@@ -0,0 +1,737 @@
+import { Ar as UpdateSubscriptionReadSetResult, Cr as UnregisterSubscriptionParams, Dr as UnregisterSubscriptionsResult, Er as UnregisterSubscriptionsParams, Ht as JobScheduler, Or as UpdateSubscriptionReadSetParams, Sr as RegisterSubscriptionResult, Tr as UnregisterSubscriptionResult, Wr as MutationResult, _r as InvalidateWritesetParams, _t as HandlerLogger, br as RegisterSubscriptionParams, dr as CacheLayer, fr as IORedisClient, gr as InvalidateEphemeralResult, mr as InvalidateEphemeralParams, nr as Database, pr as AffectedSubscription, qt as SupaliveDb, st as RegisteredProcedure, vt as HandlerObservability, yr as InvalidateWritesetResult } from "./index-CzW0TkpK.js";
+import { i as ObjectStorage } from "./object-storage-DTVmZq3l.js";
+import z from "zod";
+import { Context, Span } from "@opentelemetry/api";
+import { IncomingMessage, ServerResponse } from "http";
+import { WebSocket } from "ws";
+import { Level, Logger } from "pino";
+
+//#region src/observability.d.ts
+/** Replace the process-wide root logger. Call once at startup, before creating
+ * the server, to route Supalive's request/lifecycle logs through your own pino
+ * instance. */
+declare function configureRootLogger(logger: Logger): void;
+/** The current root logger (defaults to the env-configured singleton). */
+declare function getRootLogger(): Logger;
+type OperationTransport = "ws" | "http" | "internal";
+type OperationKind = "query" | "mutation" | "action" | "subscribe" | "unsubscribe" | "job" | "connection";
+type OperationOutcome = "ok" | "error";
+/**
+ * A single completed operation. Emitted once per WS call / subscribe / HTTP RPC
+ * request / job run, and handed to metrics, the log line, and the `onEvent`
+ * hook. High-cardinality fields (`reqId`, `userId`, `sessionId`) are logged/
+ * forwarded but NEVER used as metric attributes.
+ */
+interface OperationEvent {
+  /** Coarse operation family, e.g. "rpc" | "subscribe" | "unsubscribe" | "job" | "connection". */
+  op: string;
+  transport: OperationTransport;
+  procedure?: string;
+  kind?: OperationKind;
+  outcome: OperationOutcome;
+  /** Wall-clock duration in milliseconds. */
+  durationMs: number;
+  /** Error code for a failed op (e.g. NOT_FOUND, EXECUTION_ERROR, RATE_LIMITED). */
+  code?: string;
+  userId?: string | null;
+  sessionId?: string;
+  /** Per-request correlation id (WS request id, or a generated HTTP id). */
+  reqId?: string;
+  /** The thrown error, when the failure was an unexpected exception (→ error level). */
+  error?: unknown;
+  /** Extra structured fields to include on the log line only. */
+  extra?: Record<string, unknown>;
+  /** The operation's OTel span, when one was started. `record()` finalizes and
+   *  ends it (status + attributes + exception). */
+  span?: Span;
+}
+/** Whether to emit a log line per request. Metrics + `onEvent` fire regardless. */
+type RequestLogMode = "all" | "errors" | "off";
+interface ObservabilityOptions {
+  /** Base logger for request/lifecycle lines. Defaults to {@link getRootLogger}. */
+  logger?: Logger;
+  /** Level override applied to the derived request logger. */
+  level?: Level;
+  /** Per-request log policy. `"all"` logs successes at info + failures; `"errors"`
+   *  logs only failures; `"off"` logs neither (metrics/onEvent still fire).
+   *  Default `"all"`. */
+  requestLog?: RequestLogMode;
+  /** Callback fed every {@link OperationEvent}. Errors thrown by it are swallowed. */
+  onEvent?: (e: OperationEvent) => void;
+  /** OpenTelemetry meter name. Default `"@supalive/core"`. */
+  meterName?: string;
+  /** OpenTelemetry meter version. Defaults to the core package version. */
+  meterVersion?: string;
+}
+/**
+ * The bound observability surface for one server instance: an injectable logger,
+ * OTel metric instruments, and the `record()` seam every operation funnels
+ * through. Built once in the server constructor and shared with the HTTP RPC
+ * handler.
+ */
+declare class Observability {
+  readonly logger: Logger;
+  private readonly requestLog;
+  private readonly onEvent?;
+  private readonly requestCounter;
+  private readonly durationHistogram;
+  private readonly activeConnections;
+  private readonly activeSubscriptions;
+  private readonly tracer;
+  constructor(opts?: ObservabilityOptions);
+  /** Record one completed operation: metrics + optional onEvent + one log line,
+   *  and finalize the op's span (status/attributes/exception) when present. */
+  record(e: OperationEvent): void;
+  /**
+   * Start a SERVER span for an operation, as a child of `parent` (or the active
+   * context). No-op — returns a non-recording span — until a TracerProvider is
+   * registered by the app, so this costs nothing when tracing is disabled.
+   * Returns the span plus a context that has it active, for `context.with(...)`
+   * wrapping so nested handler work / `ctx.span` children attach correctly.
+   */
+  startSpan(name: string, opts?: {
+    transport?: OperationTransport;
+    procedure?: string;
+    kind?: OperationKind;
+    parent?: Context;
+  }): {
+    span: Span;
+    context: Context;
+  };
+  /**
+   * Continue a trace from an inbound carrier (HTTP headers, or a WS message's
+   * `trace` field). Returns a context to pass as `startSpan({ parent })`. When
+   * no propagator is registered / no trace context is present, returns the root
+   * context (a fresh trace).
+   */
+  extractContext(carrier: Record<string, string | string[] | undefined>): Context;
+  /** Set the span's final status/attributes from the event, then end it.
+   *  Returns the (valid) trace id for log correlation, or undefined. */
+  private finalizeSpan;
+  /** A request-scoped child logger for `ctx.log`, bound with the given fields
+   *  (reqId, procedure, and trace id when tracing is on). */
+  childLogger(fields: Record<string, unknown>): Logger;
+  /**
+   * A LAZY request-scoped `ctx.log`. Most handlers never log, and pino's
+   * `.child()` (bindings merge + serialization) isn't free — so this defers the
+   * child creation until the first `debug/info/warn/error` call and reuses it
+   * after. When a handler logs nothing, no child logger is ever allocated; the
+   * only per-request cost is this small delegator object. Returns the narrow
+   * {@link HandlerLogger} surface the handler context exposes.
+   */
+  lazyChildLogger(fields: Record<string, unknown>): HandlerLogger;
+  /** The span's trace id, or undefined when tracing is off / the span is
+   *  non-recording. For binding onto `ctx.log`. */
+  traceIdOf(span: Span | undefined): string | undefined;
+  connectionOpened(): void;
+  connectionClosed(): void;
+  subscriptionAdded(n?: number): void;
+  subscriptionRemoved(n?: number): void;
+}
+/** Start marker for an operation; pass to {@link elapsedMs} to get its duration. */
+declare function startTimer(): number;
+declare function elapsedMs(startedAt: number): number;
+/** What triggered a query execution — a client request/subscribe, or a background
+ *  reactive recompute (live-query invalidation / sub-manager recovery). */
+type QueryTrigger = "request" | "subscribe" | "recompute" | "recovery";
+/**
+ * Run a query handler inside a `query <procedureName>` span, nested under
+ * `parentContext` (the operation span) or the active context. The span is handed
+ * to `run` so it becomes the query handler's `ctx.span` and the parent of any DB
+ * spans. Cache HITs never call this (no execution), so a span appearing means a
+ * real recompute — including the otherwise-invisible background reactive path,
+ * where `parentContext` is omitted and the span is a root.
+ *
+ * No-op-cheap when tracing is off: the started span is non-recording, so we skip
+ * the `context.with` and just run.
+ */
+declare function traceQueryExecution<T>(procedureName: string, trigger: QueryTrigger, parentContext: Context | undefined, run: (span: Span) => Promise<T>): Promise<T>;
+//#endregion
+//#region src/server/sub-manager-client.d.ts
+/**
+ * Callback the app server registers to process invalidations that were
+ * deferred during a sub-manager outage. When the sub-manager reconnects and
+ * the buffered writeSets are flushed in one batched RPC, the resulting
+ * `affected[]` is handed to this callback — which is expected to do the
+ * same work as the normal per-mutation `reexecuteAffectedQuery` path.
+ */
+type AffectedHandler = (affected: AffectedSubscription[]) => Promise<void>;
+/**
+ * Callback the app server registers to drive recovery on sub-manager
+ * reconnect. Iterates `serverSubscriptions`, reads `sl:reg:<subId>` from
+ * Redis, and re-registers each known sub. Resolves when complete; only then
+ * does the client's buffer flush and gated calls release.
+ */
+type RecoveryDriver = () => Promise<void>;
+/**
+ * The transport-agnostic contract the app server uses to talk to the
+ * subscription manager. Implemented by:
+ *
+ *   • {@link SubManagerClient} — the WebSocket RPC client, for a sub-manager
+ *     running in its own process (`subManagerUrl`); and
+ *   • the object returned by `SubscriptionManager.localLink()` — a direct
+ *     in-process link when the manager is embedded in the app server (no
+ *     socket, no port, no serialization).
+ *
+ * Injecting this into `SupaliveServerConfig.subManager` lets a deployment run
+ * combined (one process) now and split the sub-manager out later by switching
+ * back to `subManagerUrl`, with no other code changes.
+ */
+interface SubManagerLink {
+  registerSubscription(params: RegisterSubscriptionParams): Promise<RegisterSubscriptionResult>;
+  registerSubscriptionBatch(params: RegisterSubscriptionParams[]): Promise<RegisterSubscriptionResult[]>;
+  updateSubscriptionReadSet(params: UpdateSubscriptionReadSetParams): Promise<UpdateSubscriptionReadSetResult>;
+  unregisterSubscription(params: UnregisterSubscriptionParams): Promise<UnregisterSubscriptionResult>;
+  unregisterSubscriptions(params: UnregisterSubscriptionsParams): Promise<UnregisterSubscriptionsResult>;
+  invalidateWriteset(params: InvalidateWritesetParams): Promise<InvalidateWritesetResult>;
+  invalidateEphemeral(params: InvalidateEphemeralParams): Promise<InvalidateEphemeralResult>;
+  /**
+   * Register recovery for the reconnect path. A no-op for the in-process link,
+   * which never disconnects.
+   */
+  setRecoveryDriver(driver: RecoveryDriver): void;
+  /**
+   * Register the post-recovery batched-invalidate handler. A no-op for the
+   * in-process link.
+   */
+  setAffectedHandler(handler: AffectedHandler): void;
+}
+interface SubManagerClientOptions {
+  url: string;
+  /**
+   * Maximum number of buffered WriteEntry records held during an outage.
+   * If exceeded, the buffer is dropped — the commit-log replay path during
+   * the next register call will catch up any missed invalidations, at the
+   * cost of a brief recompute spike. Default 50_000 entries.
+   */
+  invalidateBufferLimit?: number;
+}
+/**
+ * RPC client for the (single) sub-manager process.
+ *
+ * Design (Convex-inspired):
+ *   • The sub-manager is in-memory and ephemeral. There is no version
+ *     protocol, no client-side registration registry, no OUT_OF_SYNC
+ *     replay logic. All recovery is driven from the app server using
+ *     state it already has (`serverSubscriptions`) plus registration
+ *     records persisted to Redis at `sl:reg:<subId>`.
+ *
+ *   • Out-of-order `updateSubscriptionReadSet` calls are filtered server
+ *     side using `lastSnapshotTs` (monotonic DB commit timestamp).
+ *
+ *   • On rpc-websockets reconnect, the client:
+ *       1. Transitions to `busy` (any in-flight `invalidateWriteset`
+ *          buffers its writeSet).
+ *       2. Invokes the app server's `recoveryDriver` to re-register all
+ *          known subs.
+ *       3. Flushes the buffer as one batched `invalidateWriteset` RPC and
+ *          hands the resulting `affected[]` to `affectedHandler`.
+ *       4. Transitions to `ready`.
+ *
+ *   • During an extended outage, the buffer is bounded; if exceeded, it
+ *     is dropped and we rely on the commit-log replay built into
+ *     `SubscriptionWorker.register()` to catch each sub up on the next
+ *     re-register.
+ */
+declare class SubManagerClient implements SubManagerLink {
+  private client;
+  private state;
+  private hasConnectedOnce;
+  /** Resolves whenever state transitions to 'ready'. Replaced on each busy→ready cycle. */
+  private readyPromise;
+  private resolveReady;
+  /** Writeset entries accumulated while state === 'busy'. Flushed as one RPC after recovery. */
+  private bufferedWriteSets;
+  private readonly bufferLimit;
+  private bufferDroppedDuringOutage;
+  /**
+   * Ephemeral keys written while state === 'busy', mapped to the latest version
+   * seen for each. A MAP, not a queue like `bufferedWriteSets`: an ephemeral
+   * recompute re-reads the current value from Redis, so N writes to one key
+   * during an outage collapse into a single post-recovery invalidation with no
+   * loss of information. That makes the buffer self-bounding at the number of
+   * DISTINCT keys — which is what lets a 60ms position stream survive a long
+   * reconnect without a size limit or a drop path.
+   */
+  private bufferedEphemeralKeys;
+  private recoveryDriver?;
+  private affectedHandler?;
+  constructor(urlOrOptions: string | SubManagerClientOptions);
+  /**
+   * Wire up the app-server-driven recovery. Must be called before any
+   * disconnect/reconnect cycle for buffered writeSets to be flushed and
+   * subscriptions re-registered.
+   */
+  setRecoveryDriver(driver: RecoveryDriver): void;
+  /**
+   * Wire up the handler invoked when batched invalidate results land
+   * after recovery. The handler is expected to drive
+   * `reexecuteAffectedQuery` for each entry.
+   */
+  setAffectedHandler(handler: AffectedHandler): void;
+  registerSubscription(params: RegisterSubscriptionParams): Promise<RegisterSubscriptionResult>;
+  registerSubscriptionBatch(params: RegisterSubscriptionParams[]): Promise<RegisterSubscriptionResult[]>;
+  updateSubscriptionReadSet(params: UpdateSubscriptionReadSetParams): Promise<UpdateSubscriptionReadSetResult>;
+  unregisterSubscription(params: UnregisterSubscriptionParams): Promise<UnregisterSubscriptionResult>;
+  unregisterSubscriptions(params: UnregisterSubscriptionsParams): Promise<UnregisterSubscriptionsResult>;
+  /**
+   * Sends the writeSet to the sub-manager for invalidation, OR buffers it
+   * if the client is currently disconnected / recovering. Returns
+   * `{ affected: [] }` while buffering — the actual `affected` from the
+   * buffered batch is delivered via the registered `affectedHandler`
+   * after recovery completes.
+   */
+  invalidateWriteset(params: InvalidateWritesetParams): Promise<InvalidateWritesetResult>;
+  /**
+   * Ephemeral-key counterpart of {@link invalidateWriteset}. Buffers the same
+   * way during an outage, but into {@link bufferedEphemeralKeys} — see there for
+   * why a map rather than a queue.
+   *
+   * Unlike the write-set buffer there is no drop path: ephemeral state has no
+   * commit log for `register` to replay, so a dropped key would leave its
+   * subscribers stale until something else happened to invalidate them.
+   * Collapsing per key keeps the buffer small enough that dropping is never
+   * needed.
+   */
+  invalidateEphemeral(params: InvalidateEphemeralParams): Promise<InvalidateEphemeralResult>;
+  /**
+   * Single point through which RPCs go. Throws on transport / server error.
+   * `registerSubscription`, `updateSubscriptionReadSet`, and
+   * `unregisterSubscription` are NOT gated on the ready state: during a
+   * disconnect they will fail at the socket layer, and during recovery
+   * (which itself uses these methods) gating would deadlock.
+   */
+  private call;
+  private appendToBuffer;
+  private flushBuffer;
+  private flushWriteSetBuffer;
+  /**
+   * Replay the outage's ephemeral writes as ONE invalidation. The version sent
+   * is the highest buffered — every collapsed write is subsumed by the single
+   * recompute this triggers, which reads whatever Redis holds now, so using the
+   * newest version keeps the recompute lock keyed to the most recent write
+   * rather than an already-superseded one.
+   */
+  private flushEphemeralBuffer;
+  private markBusy;
+  private markReady;
+  private handleClose;
+  private handleOpen;
+  private runRecovery;
+  /**
+   * Test/inspection helpers.
+   */
+  /** @internal */
+  isReady(): boolean;
+  /** @internal */
+  bufferSize(): number;
+  /** @internal */
+  ephemeralBufferSize(): number;
+}
+//#endregion
+//#region src/config.d.ts
+/** CORS policy for the HTTP RPC endpoint. */
+interface RpcCorsConfig {
+  /**
+   * Allowed origins. `"*"` sends `Access-Control-Allow-Origin: *`; a list
+   * echoes back a request's `Origin` only when it matches (and sets `Vary`).
+   * Omit `cors` entirely to send no CORS headers (same-origin only).
+   */
+  origins: string[] | "*";
+}
+/** Rate-limit policy for the HTTP RPC endpoint (fixed window, per instance). */
+interface RpcRateLimitConfig {
+  /** Window length in ms. Default 60000. */
+  windowMs?: number;
+  /** Max requests per window per key. Default 120. */
+  max?: number;
+  /**
+   * Derive the limiter key from the request. Default: client IP
+   * (`X-Forwarded-For` first hop, else socket address). Return a stable string.
+   */
+  keyBy?: (req: IncomingMessage) => string;
+}
+/**
+ * Enables a one-shot HTTP RPC transport for `query`/`mutation`/`action`
+ * (no subscriptions — those stay WebSocket-only). Lets clients that don't need
+ * live queries call procedures without holding a socket open. Omit to disable
+ * the endpoint entirely.
+ */
+interface RpcConfig<TContext = unknown> {
+  /**
+   * The single endpoint path. Default `/_rpc`. Every procedure is called as
+   * `POST {path}` with `{ name, input }` in the body — the name is never in the
+   * URL. Keep this distinct from `jobPath`.
+   */
+  path?: string;
+  /**
+   * Map an HTTP request to the auth `data` handed to `verifyAuth` (the same
+   * callback the WebSocket path uses). Default: `Authorization: Bearer <token>`
+   * → `{ token }`. Return `undefined` for an anonymous request.
+   */
+  auth?: (req: IncomingMessage) => Record<string, unknown> | undefined;
+  /** CORS policy. Omit for same-origin only (no CORS headers). */
+  cors?: RpcCorsConfig;
+  /** Rate limiting. Omit for defaults (120/min per IP); set `false` to disable. */
+  rateLimit?: RpcRateLimitConfig | false;
+}
+interface UpstashConfig {
+  url: string;
+  token: string;
+  redisUrl: string;
+}
+/** Database configuration for PostgreSQL */
+interface PostgresConfig {
+  type: "postgres";
+  connectionString: string;
+  /** Optional max connections for the Postgres connection pool. Defaults to 10.*/
+  maxConnections?: number;
+  /** Optional min connections for the Postgres connection pool. Defaults to 1.*/
+  minConnections?: number;
+  /** Optional idle timeout for Postgres connections in milliseconds. Defaults to 30000 (30 seconds). */
+  idleTimeoutMillis?: number;
+  /** Optional connection timeout for acquiring Postgres connections in milliseconds. Defaults to 7000 (7 seconds). */
+  connectionTimeoutMillis?: number;
+}
+/** Database configuration for MySQL */
+interface MySQLConfig {
+  type: "mysql";
+  connectionString: string;
+  /** Optional max connections for the MySQL connection pool. Defaults to 20.*/
+  maxConnections?: number;
+  /** Optional min connections for the MySQL connection pool. Defaults to 1.*/
+  minConnections?: number;
+  /** Optional idle timeout for MySQL connections in milliseconds. Defaults to 30000 (30 seconds). */
+  idleTimeoutMillis?: number;
+  /** Optional connection timeout for acquiring MySQL connections in milliseconds. Defaults to 7000 (7 seconds). */
+  connectionTimeoutMillis?: number;
+  /** Optional flag to queue connection requests when pool is exhausted. Defaults to true (queue requests). */
+  queueLimit?: number;
+}
+type DatabaseConfig = PostgresConfig | MySQLConfig;
+/**
+ * Configuration for the Supalive WebSocket server.
+ */
+interface SupaliveServerConfig<TContext = Record<string, unknown>> {
+  /** Server port (default: 3000) */
+  port?: number;
+  /** Server host (default: "0.0.0.0") */
+  host?: string;
+  cacheLayer: CacheLayer;
+  redisSubClient: IORedisClient;
+  /**
+   * Subscription Manager WebSocket URL for RPC communication.
+   * A single sub-manager process owns all subscription state for this
+   * deployment. Internally it spawns N logical workers (configured on the
+   * sub-manager side) and routes by hash(subId) to spread CPU across them.
+   *
+   * Provide EITHER this OR {@link subManager} (an in-process link). Exactly
+   * one is required.
+   */
+  subManagerUrl?: string;
+  /**
+   * In-process subscription-manager link, as an alternative to
+   * {@link subManagerUrl}. Use this to embed the sub-manager in the same
+   * process as the app server (obtain it from
+   * `new SubscriptionManager({ listen: false, inline: true, ... }).localLink()`).
+   * The server then talks to the manager via direct method calls — no socket,
+   * no port, no serialization. Split the sub-manager into its own process
+   * later by switching back to `subManagerUrl` with no other changes.
+   */
+  subManager?: SubManagerLink;
+  /** Database instance */
+  database: SupaliveDb;
+  /**
+   * Optional authentication callback.
+   * Called when client sends auth message.
+   * Return null to reject authentication.
+   */
+  verifyAuth?: (data: Record<string, unknown>, sessionId: string) => Promise<TContext | null>;
+  /**
+   * Server context name for procedure routing.
+   * Must match the router's contextName.
+   */
+  contextName?: string;
+  /**
+   * App build/version number this server was deployed with. When set, it is
+   * stamped on EVERY outbound WebSocket message (the `build` field on
+   * {@link ServerMessage}) so a connected client can detect a newer server on
+   * the WS transport — the counterpart to advertising it on HTTP RPC responses
+   * (e.g. via `rpc.responseHeaders`). Omit (dev) to send no build tag.
+   */
+  buildNumber?: number;
+  /**
+   * Session TTL in seconds (default: 3600 = 1 hour).
+   * Sessions are kept alive while connected and expire after disconnect.
+   */
+  sessionTtlSeconds?: number;
+  /**
+   * Observability: structured request logging, OpenTelemetry metrics, and an
+   * optional per-operation `onEvent` hook (the seam for app-owned metrics /
+   * distributed tracing). The OTel API is a no-op until the host app registers
+   * an SDK, so leaving this unset costs nothing. See {@link ObservabilityOptions}.
+   */
+  observability?: ObservabilityOptions;
+  /**
+   * Extract user ID from context for cache key generation.
+   * If not provided, caching is disabled (each sub recomputes independently).
+   */
+  getUserId?: (ctx: TContext | undefined) => string | null;
+  /**
+   * Cache TTL in seconds (default: 3600).
+   * How long query results are cached in Redis.
+   */
+  cacheTtlSeconds?: number;
+  /**
+   * Scheduler backing the job system. When provided, the server exposes an
+   * HTTP endpoint (`{jobPath}/<jobName>`) that the scheduler POSTs to, and
+   * syncs every registered recurring (cron) job at startup. Omit to disable
+   * jobs entirely. Use `DevScheduler` locally and `QStashScheduler` in prod.
+   */
+  scheduler: JobScheduler;
+  /**
+   * Builds the system server context handed to a job handler's `serverCtx`.
+   * Jobs run without a client, so this is where a deployment injects its
+   * "system"/service identity. Called per job invocation.
+   */
+  jobContext?: () => TContext | Promise<TContext>;
+  /**
+   * Absolute, externally-reachable base URL of this server (no trailing
+   * slash), e.g. `https://api.example.com` in prod or `http://127.0.0.1:3000`
+   * in dev. Used to build the job endpoint the scheduler calls.
+   */
+  publicUrl: string;
+  /**
+   * URL path prefix for the job webhook endpoint. Default `/_jobs`. The full
+   * endpoint for a job is `{publicUrl}{jobPath}/<jobName>`.
+   */
+  jobPath?: string;
+  /**
+   * Enable the one-shot HTTP RPC transport (query/mutation/action over a
+   * single `POST {rpc.path}` endpoint, with `{ name, input }` in the body).
+   * Uses the same `verifyAuth` as the WebSocket path. Omit to disable. See
+   * {@link RpcConfig}.
+   */
+  rpc?: RpcConfig<TContext>;
+  /**
+   * App-supplied HTTP handler mounted on the SAME server/port as the WebSocket
+   * upgrade, the RPC endpoint, and the job webhook. Checked AFTER the built-in
+   * routes (`/_health`, the RPC path, `{jobPath}/…`) and BEFORE the 404, so it
+   * can add routes without shadowing them.
+   *
+   * Return `true` (or a promise of it) when the handler has written the
+   * response — the server then stops. Return `false`/`undefined` to fall
+   * through to the 404. The primary use is exposing an app-owned scrape/health
+   * endpoint (e.g. a Prometheus `/metrics`) on this port instead of standing up
+   * a second HTTP server — the handler wires the exporter's request handler.
+   */
+  onHttpRequest?: (req: IncomingMessage, res: ServerResponse) => boolean | void | Promise<boolean | void>;
+  /**
+   * When set, the built-in `/_health` liveness probe returns a 404 instead of
+   * a 200 for requests carrying the given header (matched by `name`, case-
+   * insensitive; when `value` is set, only an exact value match is blocked).
+   * Use to keep the probe off the public edge — e.g. block requests that came
+   * through a proxy which always adds `fly-client-ip` — while internal health
+   * checks (which don't include the header) still get a 200.
+   */
+  guardHealthByHeader?: {
+    name: string;
+    value?: string;
+  };
+  /**
+   * Object storage, exposed to every procedure as `ctx.storage`. When set,
+   * query/mutation/action/job handlers can presign uploads/downloads and
+   * resolve public URLs without reaching for a module-level singleton. Omit
+   * to leave `ctx.storage` undefined (handlers should treat uploads as
+   * unconfigured). Build one with `S3CompatibleStorage` from
+   * `@supalive/core/storage`.
+   */
+  storage: ObjectStorage;
+  /**
+   * Optional application-level Redis pub/sub for cross-instance app messages
+   * that are NOT part of the subscription/cache machinery — e.g. auth-token
+   * revocations, feature-flag flips, targeted cache busts.
+   *
+   * The server subscribes to `channels` on its EXISTING Redis subscribe
+   * connection (no extra connection) and hands each received message to
+   * `onMessage`. Publish from anywhere with
+   * `server.publishAppMessage(channel, message)`, which rides the shared
+   * command connection. Messages are opaque strings — the app owns encoding.
+   */
+  appPubSub?: AppPubSubConfig;
+}
+/**
+ * App-level pub/sub wiring (see {@link SupaliveServerConfig.appPubSub}). A thin,
+ * generic cross-instance message bus layered on the server's Redis connections.
+ */
+interface AppPubSubConfig {
+  /** Channels this instance subscribes to. */
+  channels: string[];
+  /**
+   * Handler for a message received on one of `channels`. Errors are caught and
+   * logged by the server, so a throwing handler can't crash the subscriber.
+   */
+  onMessage: (channel: string, message: string) => void | Promise<void>;
+}
+interface SubscriptionManagerConfig {
+  /**
+   * Port for the rpc-websockets listener. Required unless {@link listen} is
+   * `false` (embedded/in-process mode, where no socket is opened).
+   */
+  port?: number;
+  /**
+   * Upstash/Redis connection for the worker's own cache layer. Required in
+   * the default (own-pool) mode; omit when reusing an existing {@link cache}
+   * via {@link inline}.
+   */
+  upstash?: {
+    url: string;
+    token: string;
+    redisUrl: string;
+  };
+  /**
+   * Database connection the worker builds its own pool from. Required in the
+   * default mode; omit when reusing an existing {@link db} via {@link inline}.
+   */
+  database?: DatabaseConfig;
+  cacheTTLSeconds: number;
+  /**
+   * Open the rpc-websockets listener (default `true`). Set to `false` to
+   * embed the manager in another process and drive it via
+   * {@link SubscriptionManager.localLink}.
+   */
+  listen?: boolean;
+  /**
+   * Run the subscription worker inline on the main event loop instead of a
+   * `worker_threads` Worker (default `false`). Eliminates the postMessage /
+   * structured-clone hop, at the cost of no cross-core parallelism — always a
+   * single worker. Intended for embedded (`listen: false`) deployments with
+   * light realtime load. Provide {@link db} + {@link cache} to reuse the host
+   * server's pool/cache rather than opening new ones.
+   */
+  inline?: boolean;
+  /** In-process `Database` to reuse in {@link inline} mode (borrowed; not closed on stop). */
+  db?: Database;
+  /** In-process `CacheLayer` to reuse in {@link inline} mode. */
+  cache?: CacheLayer;
+  /**
+   * Number of logical workers inside the sub-manager process.
+   *
+   * Subscriptions are routed by FNV-1a(subId) % workers so that all operations
+   * for a given subId always land on the same worker (preserving the existing
+   * `instances: Set<string>` dedup). Each worker owns an independent
+   * subscriptions Map; on invalidate, all workers scan their own slice in
+   * parallel (logically — JS still runs one at a time inside one event loop,
+   * but per-worker scans are smaller so total work is split N ways).
+   *
+   * Defaults to `SUPALIVE_SUB_MANAGER_WORKERS` env var if set, else 1.
+   */
+  workers?: number;
+  /**
+   * Connection pool size *per worker*. If omitted, falls back to
+   * `floor(database.maxConnections / workers)` (min 1) so the total pool
+   * size stays close to the legacy single-worker configuration.
+   */
+  maxConnectionsPerWorker?: number;
+}
+//#endregion
+//#region src/server/types_server.d.ts
+type InstanceId = string;
+type SubId = string;
+/** Local tracking of an active subscription (per-session) */
+interface SubscriptionEntry {
+  subId: SubId;
+  cacheKey: string;
+  subscribedTimes: number;
+}
+/**
+ * A mutation that has been validated and parked on the per-session FIFO
+ * queue, waiting for the in-flight mutation on this socket to finish. Each
+ * `handleCall` for a mutation owns one of these and awaits its own
+ * resolve/reject so it can send the response.
+ */
+interface PendingMutation<TContext = Record<string, unknown>> {
+  procedure: RegisteredProcedure<TContext>;
+  validatedInput: unknown;
+  resolve: (result: MutationResult<unknown>) => void;
+  reject: (err: unknown) => void;
+  /** Request-scoped `ctx.log`/`ctx.span`, carried from `handleCall` so the
+   *  mutation handler (which runs later on the drain loop) still sees them. */
+  handlerObs?: HandlerObservability;
+}
+/** WebSocket session (runtime, with WebSocket) */
+interface Session<TContext = Record<string, unknown>> {
+  id: string;
+  ws: WebSocket;
+  /** Auth context from verifyAuth callback */
+  serverCtx?: TContext;
+  subIds: Set<string>;
+  /**
+   * Per-socket FIFO mutation queue. at most one mutation
+   * drains at a time so a single client cannot saturate the OCC retry
+   * loop or fan out concurrent commits that race the same rows.
+   */
+  mutationQueue: PendingMutation<TContext>[];
+  mutationInFlight: boolean;
+  /** Per-socket count of currently executing actions. */
+  actionInFlight: number;
+  /**
+   * Wall-clock of the last inbound frame (text message, ws-ping, or ws-pong).
+   * Used by the per-session heartbeat to terminate sockets that have gone
+   * silent past `CLIENT_TIMEOUT_MS`.
+   */
+  lastReceivedAt: number;
+  /**
+   * Wall-clock of the last outbound frame. Gates the idle-only app-level
+   * ping so a busy session (frequent sub:updates etc.) doesn't emit a
+   * redundant `{type:"ping"}` on every heartbeat tick.
+   */
+  lastSentAt: number;
+  /**
+   * Per-session combined heartbeat. Single `setInterval` that handles
+   * both dead-TCP detection (ws-ping or terminate) and client-watchdog
+   * refresh (idle-only app-level ping) on each tick.
+   */
+  heartbeatTimer: ReturnType<typeof setInterval> | null;
+}
+declare const RemoteSubscriptionUpdateSchema: z.ZodObject<{
+  type: z.ZodLiteral<"update">;
+  subId: z.ZodString;
+  data: z.ZodUnknown;
+  dataHash: z.ZodString;
+  originInstance: z.ZodString;
+  ts: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type RemoteSubscriptionUpdate = z.infer<typeof RemoteSubscriptionUpdateSchema>;
+declare const RemoteRecomputeRaceSchema: z.ZodObject<{
+  type: z.ZodLiteral<"recompute-race">;
+  subId: z.ZodString;
+  cacheKey: z.ZodString;
+  queryName: z.ZodString;
+  args: z.ZodUnknown;
+  notifyInstances: z.ZodArray<z.ZodString>;
+  commitTs: z.ZodString;
+  originInstance: z.ZodString;
+}, z.core.$strip>;
+type RemoteRecomputeRace = z.infer<typeof RemoteRecomputeRaceSchema>;
+declare const RemoteSubscriptionMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  type: z.ZodLiteral<"update">;
+  subId: z.ZodString;
+  data: z.ZodUnknown;
+  dataHash: z.ZodString;
+  originInstance: z.ZodString;
+  ts: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+  type: z.ZodLiteral<"recompute-race">;
+  subId: z.ZodString;
+  cacheKey: z.ZodString;
+  queryName: z.ZodString;
+  args: z.ZodUnknown;
+  notifyInstances: z.ZodArray<z.ZodString>;
+  commitTs: z.ZodString;
+  originInstance: z.ZodString;
+}, z.core.$strip>], "type">;
+type RemoteSubscriptionMessage = z.infer<typeof RemoteSubscriptionMessageSchema>;
+//#endregion
+export { QueryTrigger as A, SubManagerLink as C, OperationKind as D, OperationEvent as E, startTimer as F, traceQueryExecution as I, configureRootLogger as M, elapsedMs as N, OperationOutcome as O, getRootLogger as P, SubManagerClient as S, ObservabilityOptions as T, RpcCorsConfig as _, RemoteSubscriptionMessage as a, SupaliveServerConfig as b, RemoteSubscriptionUpdateSchema as c, SubscriptionEntry as d, AppPubSubConfig as f, RpcConfig as g, PostgresConfig as h, RemoteRecomputeRaceSchema as i, RequestLogMode as j, OperationTransport as k, Session as l, MySQLConfig as m, PendingMutation as n, RemoteSubscriptionMessageSchema as o, DatabaseConfig as p, RemoteRecomputeRace as r, RemoteSubscriptionUpdate as s, InstanceId as t, SubId as u, RpcRateLimitConfig as v, Observability as w, UpstashConfig as x, SubscriptionManagerConfig as y };
+//# sourceMappingURL=types_server-hiwqDm4G.d.ts.map