@crvouga/mockingbird-service-hermes 1.2.0 → 1.3.0

package/dist/index.d.ts

@@ -374,7 +374,7 @@ type ClockState = {
     now: number;
     /** True while time does not advance on its own. */
     frozen: boolean;
-    /** Milliseconds this clock adds to its underlying source. */
+    /** Milliseconds a running clock adds to its underlying source. `0` while frozen. */
     offsetMs: number;
 };
 type Clock = {
@@ -410,7 +410,10 @@ type Rng = {
     state(): number;
     /** Restore a state previously returned by {@link state}. */
     setState(state: number): void;
-    seed: number;
+    /** Restart the stream from a new seed. `reset` then returns to this seed. */
+    reseed(seed: number | string): void;
+    /** The seed the stream currently starts from. */
+    readonly seed: number;
 };
 
 /**
@@ -419,44 +422,83 @@ type Rng = {
  * This is how a suite reaches the vendor's failure modes without the vendor: the
  * quota error that only appears when a shared sandbox is full, the 429 that only
  * appears under load, the 5xx that proves a retry path works.
+ *
+ * A rule has three parts. What it **matches** (`operationId`, `method`, `path`, …), **when**
+ * it fires among the matching requests (`after`, `every`, `count`, `rate`, `from`, `until`),
+ * and what it **does** (`status`, `delay`, `timeout`, `drop`, `truncate`, `effect`).
  */
 type FaultRule = {
-    /** Stable id, so a suite can retire exactly the rule it added. */
+    /** Stable id, so a suite can retire exactly the rule it added. Unique within a namespace. */
     id: string;
     /** Fault only this operation. Omit to match every operation. */
     operationId?: string;
     /** Fault only this HTTP method, case-insensitive. Omit to match every method. */
     method?: string;
+    /** Fault only this exact path. */
+    path?: string;
     /** Fault only paths starting with this prefix. Omit to match every path. */
     pathPrefix?: string;
+    /** Fault only paths matching this regular expression (JavaScript syntax, unanchored). */
+    pathPattern?: string;
+    /** Fault only requests carrying these headers. `"*"` matches any value. */
+    requestHeaders?: Record<string, string>;
+    /** Fault only requests carrying these query parameters. `"*"` matches any value. */
+    query?: Record<string, string>;
     /**
      * Fault only this namespace. Omit (or `"*"`) to fault every namespace — which is what
      * an in-process caller usually wants, and what a parallel worker usually does not:
      * rules added through `POST /__admin/faults` default to the calling namespace.
      */
     namespace?: string;
+    /** Let this many matching requests through first. */
+    after?: number;
+    /** Then fault only every nth matching request: `3` faults the 3rd, 6th, 9th. */
+    every?: number;
+    /** Retire the rule after this many faults. Omit to keep it until removed. */
+    count?: number;
+    /** Fault this fraction of the remaining requests, `0`–`1`, drawn from the seed. Default `1`. */
+    rate?: number;
+    /**
+     * Fault only from this instant on the namespace clock. A duration (`"5m"`) counts from the
+     * clock when the rule was added. Listed as epoch ms.
+     */
+    from?: Instant | Duration;
+    /** Stop faulting at this instant on the namespace clock. A duration counts from when added. */
+    until?: Instant | Duration;
     /**
-     * Status of the injected response. Omit for a rule that only delays (`delayMs` /
-     * `latencyMs`), only drops the connection (`drop`), or only switches on an `effect`:
-     * the request then still reaches the service.
+     * Status of the injected response. Omit for a rule that only delays, times out, drops,
+     * truncates, or switches on an `effect`: the request then still reaches the service.
      */
     status?: number;
     /** Response body, serialized as JSON. A string is sent as-is. */
     body?: unknown;
+    /** Response headers. */
     headers?: Record<string, string>;
-    /** Retire the rule after this many faults. Omit to keep it until removed. */
-    count?: number;
-    /** Fault this fraction of matching requests, `0`–`1`. Default `1`. */
-    rate?: number;
-    /** Hold the response back this long, to exercise timeouts. */
+    /** Hold the response back this long. Listed as `delayMs`. */
+    delay?: Duration;
+    /** `delay`, in milliseconds. */
     delayMs?: number;
     /** Alias of `delayMs`. */
     latencyMs?: number;
+    /** Extra seeded delay in `[0, jitter]`. Listed as `jitterMs`. */
+    jitter?: Duration;
+    jitterMs?: number;
+    /**
+     * Never answer: hold the request this long, then drop the connection. Listed as
+     * `timeoutMs`. With virtual time the wait is spent on the mock clock.
+     */
+    timeout?: Duration;
+    timeoutMs?: number;
     /**
      * Drop the connection instead of answering: an in-process `fetch` rejects with a
      * `TypeError`, and a served mock destroys the socket. Models "unknown outcome" failures.
      */
     drop?: boolean;
+    /**
+     * Cut the response body off after this many bytes: the status and headers arrive, then
+     * the connection dies mid-body.
+     */
+    truncate?: number;
     /**
      * A named service behaviour to switch on for the matching request instead of (or
      * before) a canned response, e.g. `created_but_500` or `numeric_tracking_id`. Services
@@ -465,8 +507,8 @@ type FaultRule = {
     effect?: string;
     /** Parameters for `effect`. */
     params?: Record<string, unknown>;
-    /** From the preset this rule was expanded from, if any. */
-    preset?: string;
+    /** The preset this rule was expanded from, if any. */
+    fromPreset?: string;
 };
 /** A fault that fired for one request. */
 type FaultHit = {
@@ -474,6 +516,10 @@ type FaultHit = {
     /** The injected response; absent when the rule only delays, drops, or sets an effect. */
     response?: Response;
     drop?: boolean;
+    /** Set with `drop` when the rule held the request for its `timeout` first. */
+    timeout?: boolean;
+    /** Bytes of response body to let through before the connection dies. */
+    truncate?: number;
     effect?: {
         name: string;
         params: Record<string, unknown>;
@@ -498,38 +544,200 @@ type FaultCandidate = {
     method: string;
     path: string;
     namespace: string;
+    /** Request headers and query, for rules that match on them. */
+    headers?: Headers;
+    query?: URLSearchParams;
+    /** The namespace clock, for `from` / `until`. Rules with a window are skipped without it. */
+    now?: number;
+    /** How to spend a delay for this request. Default: the registry's own sleep. */
+    wait?: (ms: number) => Promise<void>;
+};
+/** A stored rule and how often it was consulted. */
+type FaultListing = FaultRule & {
+    /** Faults left before the rule retires. `null` when it has no `count`. */
+    remaining: number | null;
+    /** Times the rule faulted a request. */
+    hits: number;
+    /** Requests that matched the rule, faulted or not. */
+    seen: number;
+};
+/** A namespace's own rules, with their counters, in the order they are tried. */
+type FaultSnapshot = {
+    /**
+     * `position` is how many `"*"` rules are tried before the rule, which is what its place
+     * in the order means to a request and holds in any process.
+     */
+    rules: (FaultListing & {
+        position?: number;
+    })[];
+    /** How many `fault_<n>` ids the namespace has handed out. */
+    nextId?: number;
 };
 type FaultRegistry = {
-    isolateNamespaces(): void;
-    snapshot(namespace: string): {
-        rules: (FaultRule & {
-            remaining: number | null;
-            hits: number;
-            position: number;
-        })[];
-        rngState: number;
-    };
+    snapshot(namespace: string): FaultSnapshot;
+    /** Add a rule, or replace the rule with the same id in the same namespace. */
     add(rule: FaultRule): FaultRule;
-    list(): (FaultRule & {
-        remaining: number | null;
-        hits: number;
-    })[];
-    remove(id: string): boolean;
-    clear(): void;
-    restore(namespace: string, state: {
-        rules: (FaultRule & {
-            remaining: number | null;
-            hits: number;
-            position: number;
-        })[];
-        rngState: number;
-    }): void;
+    /** The next unused `fault_<n>` id in `namespace`. */
+    nextId(namespace: string): string;
+    /** Every rule, or the rules a namespace's requests can hit: its own and the global ones. */
+    list(namespace?: string): FaultListing[];
+    get(id: string, namespace?: string): FaultListing | undefined;
+    /** Remove a rule by id: from `namespace` (its own, then a global one), or wherever it is. */
+    remove(id: string, namespace?: string): boolean;
+    /** Remove every rule, or one namespace's own rules. */
+    clear(namespace?: string): void;
+    /** Replace a namespace's own rules with a snapshot's, wherever the snapshot was taken. */
+    restore(namespace: string, state: FaultSnapshot): void;
     /**
      * Every fault this request should get, in rule order, stopping at the first that answers
      * or drops (effect-only and delay-only rules let later rules match too). Consumes one of
      * each matching rule's remaining uses.
      */
     take(candidate: FaultCandidate): Promise<FaultHit[]>;
+    /**
+     * Fire these rules at one request without storing them: no matching, no schedule, in order,
+     * stopping at the first that answers or drops. Jitter draws from the namespace's stream.
+     */
+    fire(rules: readonly FaultRule[], candidate: FaultCandidate): Promise<FaultHit[]>;
+};
+
+/**
+ * The admin controls every mock shares, as one document.
+ *
+ * The same shape is accepted in three places, and means the same thing in each:
+ *
+ * - at boot: `createRuntime({ adminControls })`, `serve --admin-controls`,
+ *   `MOCKINGBIRD_ADMIN_CONTROLS`
+ * - over HTTP: `PUT /__admin/controls`
+ * - per request: the `x-mockingbird-*` headers in {@link CONTROL_HEADERS}
+ *
+ * Every control is deterministic: given the same seed, clock and requests, a mock answers
+ * the same bytes. Nothing here reads the wall clock or `Math.random`.
+ */
+/** Milliseconds, or a string like `"250ms"`, `"2s"`, `"15m"`, `"1h"`, `"3d"`. */
+type Duration = number | string;
+/** Epoch milliseconds, or an ISO-8601 string. */
+type Instant = number | string;
+type ClockControls = {
+    /** Move the clock to this instant. */
+    now?: Instant;
+    /** Stop time. A frozen clock moves only when told to, so timestamps replay exactly. */
+    frozen?: boolean;
+    /**
+     * Step the clock forward by this much before every vendor request. With a frozen clock
+     * each request still gets its own, reproducible timestamp.
+     */
+    autoAdvance?: Duration;
+};
+/** How long a response takes: a fixed delay plus seeded jitter in `[0, jitter]`. */
+type LatencyRuleInput = {
+    delay?: Duration;
+    jitter?: Duration;
+};
+type LatencyControls = LatencyRuleInput & {
+    /** Per-operation overrides, keyed by operationId. A bare duration is its `delay`. */
+    operations?: Record<string, Duration | LatencyRuleInput>;
+};
+/** A fault to add: a rule (the id is assigned when omitted), or a named preset with overrides. */
+type FaultInput = (Omit<FaultRule, "id"> & {
+    id?: string;
+}) | ({
+    preset: string;
+} & Partial<FaultRule>);
+/** Identifies a {@link SnapshotDocument}. */
+declare const SNAPSHOT_FORMAT = "mockingbird.snapshot/v1";
+/**
+ * A namespace, as portable JSON: what `GET /__admin/snapshots/:id` returns and what
+ * `PUT /__admin/snapshots/:id` and the boot `snapshot` control accept. Only `format` and
+ * `records` are required, so a hand-written seed file is a valid snapshot.
+ */
+type SnapshotDocument = {
+    format: typeof SNAPSHOT_FORMAT;
+    /** The service that wrote it. A snapshot is rejected by any other service. */
+    service?: string;
+    /**
+     * Stored rows. `seq` orders a collection; omitted, rows keep their listed order. `raw` is
+     * the stored text of a row that is not a plain record, and replaces `value` when present.
+     */
+    records: {
+        collection: string;
+        id: string;
+        seq?: number;
+        value?: unknown;
+        raw?: string;
+    }[];
+    /** Id counters, so the next generated id continues where the snapshot left off. */
+    sequences?: {
+        name: string;
+        kind: string;
+        value: number;
+    }[];
+    clock?: {
+        now: number;
+        frozen: boolean;
+        autoAdvanceMs?: number;
+    };
+    seed?: number | string;
+    /** Positions of the seeded random streams. */
+    rng?: {
+        state: number;
+        faults?: number;
+        latency?: number;
+    };
+    faults?: unknown;
+    latency?: unknown;
+    virtualTime?: boolean;
+};
+/** Controls for one namespace. */
+type NamespaceControls = {
+    /** Seeds every random choice: fault rates, jitter, and whatever the service invents. */
+    seed?: number | string;
+    clock?: ClockControls;
+    /**
+     * Spend injected waits (latency, fault delays, timeouts) on the mock clock instead of the
+     * wall clock: the request returns at once, the clock has moved, and the journal records
+     * the wait exactly. Default `false`: waits are real, so a client's own timeout can fire.
+     */
+    virtualTime?: boolean;
+    /** Baseline response time for every vendor request. A bare duration is its `delay`. */
+    latency?: Duration | LatencyControls;
+    faults?: readonly FaultInput[];
+    /** Start from this state instead of the service's own seed data. */
+    snapshot?: SnapshotDocument;
+};
+/** {@link NamespaceControls} for every namespace, with per-namespace overrides. */
+type MockControls = NamespaceControls & {
+    /** Vendor credential → namespace, for SDKs that cannot send a namespace header. */
+    credentials?: Record<string, string>;
+    /** Overrides for named namespaces. A key given here replaces the shared value. */
+    namespaces?: Record<string, NamespaceControls>;
+};
+/** A latency rule in milliseconds. */
+type LatencyRule = {
+    delayMs: number;
+    jitterMs: number;
+};
+/** Baseline latency for a namespace, normalized. */
+type LatencyState = LatencyRule & {
+    operations: Record<string, LatencyRule>;
+};
+/** What {@link controlHeaders} turns into request headers. */
+type ControlHeaderInput = {
+    namespace?: string;
+    adminKey?: string;
+    branch?: string;
+    at?: string;
+    reset?: boolean;
+    restore?: string;
+    seed?: number | string;
+    time?: Instant | Date;
+    advance?: Duration;
+    virtualTime?: boolean;
+    delay?: Duration;
+    timeout?: Duration;
+    /** A status, `"drop"`, a preset name, or a fault rule. */
+    fault?: number | string | Record<string, unknown>;
+    snapshot?: string;
 };
 
 /**
@@ -569,6 +777,8 @@ type RequestLog = {
     unmatched: boolean;
     /** Set when a fault rule produced the response. */
     faultId?: string;
+    /** Milliseconds of injected wait: latency, fault delays and timeouts. Absent when none. */
+    delayMs?: number;
     /** Resource ids the handler touched (`userId`, `orderId`, …), when the service reports them. */
     ids?: Record<string, string>;
     /** Set when the service created a resource the request referred to but that did not exist. */
@@ -614,6 +824,12 @@ type JournalQuery = {
     /** Only this namespace. Omit for every namespace, oldest first across all of them. */
     namespace?: string;
     operationId?: string;
+    /** Only this HTTP method, case-insensitive. */
+    method?: string;
+    /** Only this exact path. */
+    path?: string;
+    /** Only requests this fault rule answered or shaped. */
+    faultId?: string;
     status?: number;
     /** Only entries at or after this instant (epoch ms). */
     since?: number;
@@ -628,6 +844,38 @@ type Journal = {
     clear(namespace?: string): void;
 };
 
+/**
+ * Baseline response time, per namespace: how long every vendor request takes before any
+ * fault is considered. Jitter draws from a stream the caller owns, one per namespace and
+ * separate from the fault stream, so adding latency never shifts which requests a `rate`
+ * fault hits.
+ */
+type LatencyRegistry = {
+    get(namespace: string): LatencyState;
+    set(namespace: string, state: LatencyState): LatencyState;
+    /** Remove one namespace's latency, or every namespace's. */
+    clear(namespace?: string): void;
+    /** Milliseconds this request waits. Draws jitter, so call it once per request. */
+    take(namespace: string, operationId: string | undefined): number;
+};
+
+/** Clock state as the admin API reports it. */
+type ControlClock = ClockState & {
+    /** `now`, as ISO-8601. */
+    iso: string;
+    /** Milliseconds the clock steps before every vendor request. */
+    autoAdvanceMs: number;
+};
+/** One namespace's controls: the body of `GET /__admin/controls`. */
+type ControlState = {
+    namespace: string;
+    seed: number | string;
+    clock: ControlClock;
+    virtualTime: boolean;
+    latency: LatencyState;
+    faults: FaultListing[];
+};
+
 type AdminRequest = {
     request: Request;
     url: URL;
@@ -644,6 +892,17 @@ type AdminRoute = (request: AdminRequest) => Response | Promise<Response>;
  * `:param` segments — e.g. `"POST /orders/:id/transition"`.
  */
 type AdminRoutes = Record<string, AdminRoute>;
+/** What `GET /__admin/snapshots` lists for each snapshot. */
+type SnapshotInfo = {
+    id: string;
+    namespace: string;
+    /** Stored rows in the snapshot. */
+    records: number;
+    /** The namespace clock when it was taken, epoch ms. */
+    at: number;
+    /** Whether `GET /snapshots/:id` can return it as a {@link SnapshotDocument}. */
+    portable: boolean;
+};
 
 /** Credential → namespace mapping behind `PUT /__admin/credentials`. */
 type CredentialRegistry = {
@@ -888,14 +1147,26 @@ type RuntimeOptions<T extends ServiceInstance> = {
     sqlite?: SqliteClient$1;
     /** Defaults to a live clock over `Date.now`. */
     clock?: Clock;
-    /** Seeds every random choice the runtime makes (fault rates). Default `0`. */
+    /** Seeds every random choice the runtime makes (fault rates, jitter). Default `0`. */
     seed?: number | string;
+    /**
+     * Admin controls to boot with: clock, latency, faults, a starting snapshot, credential
+     * mappings and per-namespace overrides. `reset` returns a namespace to exactly this.
+     */
+    adminControls?: MockControls;
     /** Extra `GET /__admin/health` fields, such as the loaded corpus version. */
     describe?: () => Record<string, unknown>;
     /** Service-specific admin routes, given the runtime so they can reach any namespace. */
     admin?: (runtime: ServiceRuntime<T>) => AdminRoutes;
     /** Reserved tree for every internal HTTP endpoint, UI and namespace carrier. Default /__admin. */
     adminPrefix?: string;
+    /**
+     * A namespace's clock was moved — by `/__admin/clock`, a header, a restore, a reset, or a
+     * wait spent in virtual time. Run whatever the service schedules by that clock, so what
+     * came due is seen at once and not on the next request. Moving the base clock in process
+     * (`runtime.clock`) is the caller's own doing and is not reported here.
+     */
+    onClockChange?: (namespace: string) => void;
     /** Invalidate transient handles before replacing an existing instance's stored state. */
     beforeRestore?: (instance: T) => void;
     /** Require this value in `x-mockingbird-admin-key` on admin data routes. */
@@ -913,7 +1184,10 @@ type RuntimeOptions<T extends ServiceInstance> = {
      * `sigV4AccessKeyId`.
      */
     credential?: (request: Request) => string | undefined;
-    /** Named faults, switched on with `POST /__admin/faults {"preset": "<name>"}`. */
+    /**
+     * Named faults, switched on with `POST /__admin/faults {"preset": "<name>"}`. They join the
+     * standard presets every mock has; one with a standard name replaces it.
+     */
     presets?: Record<string, FaultPreset>;
     /** Outbound webhooks; adds the `/__admin/webhooks*` routes and clears on reset. */
     webhooks?: WebhookHub;
@@ -936,11 +1210,15 @@ type RuntimeOptions<T extends ServiceInstance> = {
 type RuntimeIO = {
     wallNow(): number;
     monotonicNow(): number;
-    sleep(ms: number): Promise<void>;
+    /** Wait on the wall clock. Rejects with the signal's reason when it aborts first. */
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
 };
 type ServiceTimelineState = Readonly<{
     snapshot: NamespaceSnapshot;
-    clock: Readonly<ReturnType<Clock["state"]>>;
+    /** `pinned`: the namespace's clock was frozen itself, not just following a frozen base. */
+    clock: Readonly<ClockState & {
+        pinned?: boolean;
+    }>;
     rngState: number;
 }>;
 type ServiceCheckpoint = Checkpoint<ServiceTimelineState>;
@@ -953,14 +1231,18 @@ type ServiceRuntime<T extends ServiceInstance> = FetchAPI & {
     readonly sqlite: SqliteClient$1;
     readonly clock: Clock;
     readonly faults: FaultRegistry;
+    /** Baseline response time per namespace. */
+    readonly latency: LatencyRegistry;
     readonly metrics: Metrics;
     readonly journal: Journal;
     readonly rng: Rng;
     readonly credentials: CredentialRegistry;
     /** The webhook hub, when the service has outbound webhooks. */
     readonly webhooks: WebhookHub | undefined;
-    /** Enable independent namespace clocks and PRNGs before serving a fleet. */
-    isolateNamespaces(): void;
+    /**
+     * A namespace's clock. Each follows the base clock, {@link ServiceRuntime.clock}, with an
+     * offset and a freeze of its own, so moving one never moves another.
+     */
     namespaceClock(namespace?: string): Clock;
     namespaceOf(request: Request): string;
     /** Opaque in-process checkpoint including records, controls and webhook history. */
@@ -972,8 +1254,38 @@ type ServiceRuntime<T extends ServiceInstance> = FetchAPI & {
     instance(namespace?: string): T;
     /** Public names of every namespace created so far. */
     namespaces(): string[];
-    /** Reset one namespace, or every namespace with `"*"`. */
+    /** Return one namespace to its boot state, or every namespace with `"*"`. */
     reset(namespace?: string): Promise<void>;
+    /** Reset a namespace and forget it, releasing everything it held. */
+    dropNamespace(namespace: string): Promise<void>;
+    /** A namespace's controls: seed, clock, virtual time, latency, faults and snapshots. */
+    controls(namespace?: string): ControlState & {
+        snapshots: SnapshotInfo[];
+    };
+    /** Apply a control document to a namespace. A given key replaces that control. */
+    configure(controls: NamespaceControls, namespace?: string): ControlState & {
+        snapshots: SnapshotInfo[];
+    };
+    /** Named snapshots of a namespace: records, clock, random streams, faults and latency. */
+    readonly snapshots: {
+        /** Capture the namespace now. Reusing a name replaces that snapshot. */
+        create(options?: {
+            name?: string;
+            namespace?: string;
+        }): SnapshotInfo;
+        list(namespace?: string): SnapshotInfo[];
+        /** The snapshot as portable JSON, to commit beside a suite or boot another mock from. */
+        export(id: string, namespace?: string): SnapshotDocument;
+        /** Store a document as a snapshot without restoring it. */
+        import(document: SnapshotDocument, options?: {
+            name?: string;
+            namespace?: string;
+        }): SnapshotInfo;
+        restore(id: string, namespace?: string): void;
+        delete(id: string, namespace?: string): boolean;
+    };
+    /** Request headers that carry controls, checked: spread them into a `fetch` or an SDK's defaults. */
+    headers(input: ControlHeaderInput): Record<string, string>;
     snapshot(namespace?: string): NamespaceSnapshot;
     restore(snapshot: NamespaceSnapshot, namespace?: string): void;
     /** Capture the current branch. Mutating HTTP calls do this automatically. */
@@ -1277,7 +1589,7 @@ type SupportedOperationId = "RunCreate" | "RunGet" | "RunStop";
 declare const operationIds: readonly ["RunCreate", "RunGet", "RunStop", "RunEvents", "RunApproval", "RunSteer"];
 declare const supportedOperationIds: readonly ["RunCreate", "RunGet", "RunStop"];
 
-type HermesRuntimeOptions = Pick<RuntimeOptions<HermesAPI>, "sqlite" | "clock" | "seed" | "adminKey" | "onLog" | "journalSize" | "maxCheckpoints">;
+type HermesRuntimeOptions = Pick<RuntimeOptions<HermesAPI>, "sqlite" | "clock" | "seed" | "adminKey" | "adminControls" | "onLog" | "journalSize" | "maxCheckpoints">;
 type HermesRuntime = ServiceRuntime<HermesAPI>;
 /** Standard controls and Timeline coordination; no provider-local history. */
 declare const createRuntime: (options?: HermesRuntimeOptions) => HermesRuntime;

package/dist/index.js

@@ -5,7 +5,7 @@ import {
   document,
   operationIds,
   supportedOperationIds
-} from "./chunk-OPQVERJU.js";
+} from "./chunk-AMUIT2BU.js";
 export {
   HERMES_NAMESPACE,
   HermesAPI,