@voltro/runtime 0.22.1 → 0.24.0

package/dist/index.d.ts

@@ -1117,7 +1117,7 @@ export declare interface BeginOAuthResult {
  */
 export declare const bindConnectionSubject: (clientId: number, subject: Subject) => void;
 
-export declare const bindMutation: <Input, Output, E = never>(execute: (input: Input, context: RuntimeContext) => Output | Promise<Output> | Effect.Effect<Output, E, never>, input: Input, spanName?: string) => Effect.Effect<Output, E, SubjectService | ConnectionInfo>;
+export declare const bindMutation: <Input, Output, E = never>(execute: (input: Input, context: RuntimeContext) => Output | Promise<Output> | Effect.Effect<Output, E, never>, input: Input, spanName?: string, codec?: MutationOutputCodec<unknown>, idempotency?: IdempotencyBinding) => Effect.Effect<Output, E, SubjectService | ConnectionInfo>;
 
 /**
  * Bind a non-reactive server→client stream (A3). The executor builds a
@@ -2170,6 +2170,13 @@ export declare const drainForShutdown: (options: {
     readonly hooks: ReadonlyArray<() => void | Promise<void>>;
     readonly deadlineMs: number;
     readonly exit: () => void;
+    /** How the drain ended, for the caller to report. A completed drain and one
+     *  CUT at the deadline are different incidents and were indistinguishable in
+     *  the log — asked for by a consumer who could see neither. */
+    readonly onOutcome?: (outcome: {
+        readonly reason: "drained" | "deadline";
+        readonly ms: number;
+    }) => void;
 }) => void;
 
 /**
@@ -2504,6 +2511,9 @@ export declare interface GroupState {
     readonly extreme?: number;
 }
 
+/** What a user handler may return. */
+export declare type HandlerBody = void | Promise<unknown> | Effect.Effect<unknown, unknown, never>;
+
 /** Define a histogram. `boundaries` default to the framework duration buckets. */
 export declare const histogramMetric: (name: string, boundaries?: MetricBoundaries.MetricBoundaries, description?: string) => Metric.Metric.Histogram<number>;
 
@@ -2530,6 +2540,21 @@ export declare interface HttpSecretsOptions {
     readonly ttlMs?: number;
 }
 
+/**
+ * WS-rpc idempotency store + TTL, passed to `bindMutation` as a closure param by
+ * the boot path (`serveApi`/`dev`) — NOT a service. @effect/rpc runs a handler in
+ * a NARROWED context (only the middleware `provides` + declared deps), so a plain
+ * merged service is invisible to `Effect.serviceOption` inside the handler; the
+ * store+ttl are boot-time constants the bind site already holds, so a closure is
+ * both correct and simpler. Omitted → WS mutation dedup is off (the default).
+ * Reuses the SAME `dataStoreIdempotencyStore` + `_voltro_idempotency` table as
+ * the REST path — enable once, protect both.
+ */
+export declare interface IdempotencyBinding {
+    readonly store: IdempotencyStore;
+    readonly ttlMs: number;
+}
+
 export declare interface IdleCheckOptions {
     readonly store: DataStore;
     readonly signals: ActivitySignals;
@@ -2775,6 +2800,15 @@ export declare const isOrglessUserSubject: (subject: {
     readonly tenantId?: string | null;
 } | null | undefined) => boolean;
 
+/** A query cancelled for exceeding the `statementTimeoutMs` deadline, across
+ *  dialects: pg `57014` (query_canceled — what `statement_timeout` raises),
+ *  MySQL `3024` (ER_QUERY_TIMEOUT), MariaDB `1969` (ER_STATEMENT_TIMEOUT), mssql
+ *  `ETIMEOUT` (tedious request timeout), sqlite `SQLITE_INTERRUPT`. NOT a
+ *  transient error — a re-run just repeats the runaway, so it must not retry
+ *  (`servePipeline`'s transient set deliberately excludes it). Lets a consumer /
+ *  observability layer name the failure instead of reading an opaque SqlError. */
+export declare const isQueryTimeout: (dbCause: Record<string, unknown>) => boolean;
+
 /**
  * Optimistic-concurrency guard: an undo is safe only when the row still looks
  * like what the forward mutation left (`next`). If another writer changed it
@@ -3143,6 +3177,14 @@ export declare const makeLazyWorkflowFacade: (resolve: () => WorkflowsAppContext
 /** `__voltro.connections.list` — every declared connection, for the caller. */
 export declare const makeListConnectionsExecutor: (deps: ConnectionBuiltinDeps) => (_input: Record<string, never>, ctx: ConnectionExecutorCtx) => Promise<ReadonlyArray<ConnectionState>>;
 
+/**
+ * Build the replay codec from a mutation's `descriptor.output` Schema (call it at
+ * the bind site). Both directions fall back to the raw value if the Schema can't
+ * round-trip it — a guard for exotic schemas; for a value the handler actually
+ * produced, `encodeUnknownSync` never throws. `undefined` schema → no codec.
+ */
+export declare const makeMutationOutputCodec: (outputSchema: Schema.Schema.AnyNoContext | undefined) => MutationOutputCodec<unknown> | undefined;
+
 /**
  * Build the shared mutation runner. Used by BOTH the rpc WS handler and
  * the `/_voltro/inspect/invoke` endpoint (and the prod entrypoint) so they
@@ -3438,6 +3480,20 @@ export declare interface MutationLike {
     executor(input: unknown, ctx: unknown): unknown;
 }
 
+/**
+ * Encode/decode a mutation's output for idempotent replay. On a FRESH call the
+ * WIRE form (`encode`) is stored, so a later replay `decode`s it back to the exact
+ * Output the handler would have returned and the rpc layer re-encodes it
+ * identically. Storing the DECODED Output directly would corrupt `Date`/etc.
+ * fields through the store's JSON round-trip (encode there expects a `Date`, not
+ * the ISO string a round-trip produced). Built from `descriptor.output` at the
+ * call site; both fns fall back to the raw value if the Schema can't round-trip.
+ */
+export declare interface MutationOutputCodec<Output> {
+    readonly encode: (output: Output) => unknown;
+    readonly decode: (stored: unknown) => Output;
+}
+
 export declare interface MutationRunnerDeps {
     readonly store: TransactionalStore;
     /** Build the per-call `AppContext` bound to the transactional `tx`. */
@@ -4928,6 +4984,27 @@ export declare interface RpcServerOptions<Rpcs extends Rpc.Any> {
      *  stream. Absent → falls back to `handlersLayer`. */
     readonly httpHandlersLayer?: Layer.Layer<Rpc.ToHandler<Rpcs>>;
     readonly port?: number;
+    /**
+     * Interface to bind. Absent → the wildcard, which is what a container needs
+     * and stays the production default.
+     *
+     * Pass `127.0.0.1` when a caller in the SAME PROCESS will connect over IPv4,
+     * which is every test that boots a server and fetches it. A wildcard bind
+     * lands on `:::<port>` (IPv6), and IPv4 and IPv6 are separate binds of the
+     * same number — so a lingering IPv4 socket on that port from an earlier
+     * server accepts the connection instead. The kernel completes the handshake
+     * into ITS backlog, `lsof` reports ESTABLISHED, and the new server never sees
+     * a `connection` event. The request then waits forever against a peer that
+     * will never answer.
+     *
+     * That is not hypothetical: it is the mechanism behind this repo's
+     * long-running "flaky integration test" — measured by instrumenting
+     * `net.Server` and catching a hung run with
+     * `listener#3 bound :::53011 … closed after 0 connection(s)` while its client
+     * sat in `fetch`. Binding the family the client will use turns a silent hang
+     * into an ordinary `EADDRINUSE`.
+     */
+    readonly host?: string;
     readonly path?: `/${string}`;
     /** Optional tracer layer (`buildTracingLayer().layer`). Merged into the
      *  server's layer scope so every `Effect.withSpan` on the handler path
@@ -5319,7 +5396,20 @@ export declare interface ScheduleFireContext {
  */
 export declare type ScheduleFireInterceptor = (next: () => Promise<void>, ctx: ScheduleFireContext) => Promise<void>;
 
-export declare type ScheduleHandler = (ctx: ScheduleContext) => void | Promise<void>;
+/**
+ * A schedule body. Promise-form or Effect-form; both run.
+ *
+ * The Effect arm is not sugar. Before it existed the call site was
+ * `await def.handler(ctx)`, and an Effect is not a thenable — so `await`
+ * returned it unchanged, the body never executed, and the firing was recorded
+ * as a success. In an Effect-first framework the natural thing to write was the
+ * thing that silently did nothing. Same bridge a file-based migration's `up`
+ * has carried since it shipped.
+ *
+ * `R = never`: the effect must carry its own requirements. Everything a
+ * schedule needs is on `ctx.app`.
+ */
+export declare type ScheduleHandler = (ctx: ScheduleContext) => void | Promise<void> | Effect.Effect<unknown, unknown, never>;
 
 /** What happens when a firing arrives while the previous run of the
  *  same schedule is still in flight. */
@@ -5677,6 +5767,14 @@ export declare const setSystemStoreHandle: (handle: SystemStoreHandle) => void;
 /** Test seam — swap (or reset with `undefined`) the process recorder. */
 export declare const setTimelineRecorderForTest: (recorder: TimelineRecorder | undefined) => void;
 
+/**
+ * Normalise a handler's return value to "a promise, or nothing to wait for".
+ *
+ * `undefined` means the body was synchronous and has already run. Anything else
+ * is a promise the caller disposes of as its context requires.
+ */
+export declare const settleHandlerBody: (body: HandlerBody) => Promise<unknown> | undefined;
+
 /**
  * Register (or clear) the process-global tuple source. Last write wins.
  *
@@ -5695,6 +5793,18 @@ export declare type ShapeClassification = {
     readonly reason: string;
 };
 
+/**
+ * The teardown deadline, from `VOLTRO_SHUTDOWN_GRACE_MS` (milliseconds), clamped
+ * to `[1s, 5min]`. Operators set it to sit JUST UNDER their orchestrator's hard
+ * kill — k8s `terminationGracePeriodSeconds`, ECS `stopTimeout` — so the process
+ * drains in-flight work and exits cleanly on its own BEFORE SIGKILL truncates it
+ * mid-drain (which would strand exactly the finalizers this path exists to run:
+ * connection-pool close, plugin `onDeactivate`, analytics flush, trace persist).
+ * A non-numeric / non-positive value falls back to the 10s default rather than
+ * producing a `setTimeout(…, NaN)` that fires immediately and defeats the drain.
+ */
+export declare const shutdownGraceMsFromEnv: () => number;
+
 /** No-coordination gate for single-instance deployments (PM2,
  *  single pod, dev). */
 export declare const singleCoordinator: Coordinator;
@@ -5952,7 +6062,18 @@ export declare interface SubscribeContext {
  *  framework's CDC `ChangeEvent` re-exported for ergonomics. */
 export declare type SubscribeEvent = ChangeEvent;
 
-export declare type SubscribeHandler = (event: SubscribeEvent, ctx: SubscribeContext) => void | Promise<void>;
+/**
+ * A subscriber body. Promise-form or Effect-form; both run.
+ *
+ * The Effect arm is not sugar — see `ScheduleHandler`. The runner tested
+ * `result instanceof Promise`, an Effect is not one, so the branch was skipped
+ * and the body never executed. No error, no log line, the change event handled
+ * "successfully".
+ *
+ * `R = never`: the effect must carry its own requirements. Everything a
+ * subscriber needs is on `ctx`.
+ */
+export declare type SubscribeHandler = (event: SubscribeEvent, ctx: SubscribeContext) => void | Promise<void> | Effect.Effect<unknown, unknown, never>;
 
 /** Which row op(s) the subscriber listens on. `'any'` matches every
  *  op; an array enumerates the concrete ops. */