@crvouga/mockingbird-service-bedrock 3.1.0 → 3.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/server.d.ts CHANGED
@@ -1,34 +1,16 @@
1
1
  import { Server } from 'node:http';
2
2
  import { Hono } from 'hono';
3
3
 
4
- /** Bind values accepted by Mockingbird's SQLite port (matches sqlite-mem / better-sqlite3). */
5
- type SqliteValue$2 = null | number | bigint | string | Uint8Array | boolean;
6
- /** Mutation counters returned by {@link SqliteStatement.run}. */
7
- type SqliteRunResult$2 = {
8
- changes: number;
9
- lastInsertRowid: number | bigint;
4
+ type MountedAPI$1 = FetchAPI$2 & {
5
+ readonly prefix: string;
6
+ GET: FetchHandler$1;
7
+ POST: FetchHandler$1;
8
+ PUT: FetchHandler$1;
9
+ PATCH: FetchHandler$1;
10
+ DELETE: FetchHandler$1;
11
+ HEAD: FetchHandler$1;
12
+ OPTIONS: FetchHandler$1;
10
13
  };
11
- /**
12
- * Prepared statement bound to a {@link SqliteClient}.
13
- *
14
- * Pass bind values as rest arguments on each call (no sticky `bind()`).
15
- */
16
- interface SqliteStatement$2 {
17
- run(...params: SqliteValue$2[]): SqliteRunResult$2;
18
- all<T = Record<string, unknown>>(...params: SqliteValue$2[]): T[];
19
- get<T = Record<string, unknown>>(...params: SqliteValue$2[]): T | undefined;
20
- }
21
- /**
22
- * Sync SQLite client port owned by Mockingbird.
23
- *
24
- * Duck-typed so `@crvouga/mockingbird-service-sqlite` `Database`, better-sqlite3, and wrapped
25
- * `bun:sqlite` instances all work when they expose this surface.
26
- */
27
- interface SqliteClient$2 {
28
- exec(sql: string): void;
29
- prepare(sql: string): SqliteStatement$2;
30
- transaction<T>(fn: () => T): T;
31
- }
32
14
 
33
15
  /** A stable identifier for a point in a {@link Timeline}. */
34
16
  type CheckpointId$1 = string;
@@ -119,6 +101,37 @@ declare class Timeline$1<T> {
119
101
  interface FetchAPI$2 {
120
102
  fetch(request: Request): Promise<Response>;
121
103
  }
104
+ /** A bare function form of {@link FetchAPI}, compatible with `Bun.serve`, workerd, and Deno. */
105
+ type FetchHandler$1 = (request: Request) => Promise<Response>;
106
+
107
+ /** Bind values accepted by Mockingbird's SQLite port (matches sqlite-mem / better-sqlite3). */
108
+ type SqliteValue$2 = null | number | bigint | string | Uint8Array | boolean;
109
+ /** Mutation counters returned by {@link SqliteStatement.run}. */
110
+ type SqliteRunResult$2 = {
111
+ changes: number;
112
+ lastInsertRowid: number | bigint;
113
+ };
114
+ /**
115
+ * Prepared statement bound to a {@link SqliteClient}.
116
+ *
117
+ * Pass bind values as rest arguments on each call (no sticky `bind()`).
118
+ */
119
+ interface SqliteStatement$2 {
120
+ run(...params: SqliteValue$2[]): SqliteRunResult$2;
121
+ all<T = Record<string, unknown>>(...params: SqliteValue$2[]): T[];
122
+ get<T = Record<string, unknown>>(...params: SqliteValue$2[]): T | undefined;
123
+ }
124
+ /**
125
+ * Sync SQLite client port owned by Mockingbird.
126
+ *
127
+ * Duck-typed so `@crvouga/mockingbird-service-sqlite` `Database`, better-sqlite3, and wrapped
128
+ * `bun:sqlite` instances all work when they expose this surface.
129
+ */
130
+ interface SqliteClient$2 {
131
+ exec(sql: string): void;
132
+ prepare(sql: string): SqliteStatement$2;
133
+ transaction<T>(fn: () => T): T;
134
+ }
122
135
 
123
136
  /**
124
137
  * The single source of time for a service.
@@ -132,7 +145,7 @@ type ClockState$1 = {
132
145
  now: number;
133
146
  /** True while time does not advance on its own. */
134
147
  frozen: boolean;
135
- /** Milliseconds this clock adds to its underlying source. */
148
+ /** Milliseconds a running clock adds to its underlying source. `0` while frozen. */
136
149
  offsetMs: number;
137
150
  };
138
151
  type Clock$1 = {
@@ -168,7 +181,10 @@ type Rng$1 = {
168
181
  state(): number;
169
182
  /** Restore a state previously returned by {@link state}. */
170
183
  setState(state: number): void;
171
- seed: number;
184
+ /** Restart the stream from a new seed. `reset` then returns to this seed. */
185
+ reseed(seed: number | string): void;
186
+ /** The seed the stream currently starts from. */
187
+ readonly seed: number;
172
188
  };
173
189
 
174
190
  /**
@@ -177,44 +193,83 @@ type Rng$1 = {
177
193
  * This is how a suite reaches the vendor's failure modes without the vendor: the
178
194
  * quota error that only appears when a shared sandbox is full, the 429 that only
179
195
  * appears under load, the 5xx that proves a retry path works.
196
+ *
197
+ * A rule has three parts. What it **matches** (`operationId`, `method`, `path`, …), **when**
198
+ * it fires among the matching requests (`after`, `every`, `count`, `rate`, `from`, `until`),
199
+ * and what it **does** (`status`, `delay`, `timeout`, `drop`, `truncate`, `effect`).
180
200
  */
181
201
  type FaultRule$1 = {
182
- /** Stable id, so a suite can retire exactly the rule it added. */
202
+ /** Stable id, so a suite can retire exactly the rule it added. Unique within a namespace. */
183
203
  id: string;
184
204
  /** Fault only this operation. Omit to match every operation. */
185
205
  operationId?: string;
186
206
  /** Fault only this HTTP method, case-insensitive. Omit to match every method. */
187
207
  method?: string;
208
+ /** Fault only this exact path. */
209
+ path?: string;
188
210
  /** Fault only paths starting with this prefix. Omit to match every path. */
189
211
  pathPrefix?: string;
212
+ /** Fault only paths matching this regular expression (JavaScript syntax, unanchored). */
213
+ pathPattern?: string;
214
+ /** Fault only requests carrying these headers. `"*"` matches any value. */
215
+ requestHeaders?: Record<string, string>;
216
+ /** Fault only requests carrying these query parameters. `"*"` matches any value. */
217
+ query?: Record<string, string>;
190
218
  /**
191
219
  * Fault only this namespace. Omit (or `"*"`) to fault every namespace — which is what
192
220
  * an in-process caller usually wants, and what a parallel worker usually does not:
193
221
  * rules added through `POST /__admin/faults` default to the calling namespace.
194
222
  */
195
223
  namespace?: string;
224
+ /** Let this many matching requests through first. */
225
+ after?: number;
226
+ /** Then fault only every nth matching request: `3` faults the 3rd, 6th, 9th. */
227
+ every?: number;
228
+ /** Retire the rule after this many faults. Omit to keep it until removed. */
229
+ count?: number;
230
+ /** Fault this fraction of the remaining requests, `0`–`1`, drawn from the seed. Default `1`. */
231
+ rate?: number;
196
232
  /**
197
- * Status of the injected response. Omit for a rule that only delays (`delayMs` /
198
- * `latencyMs`), only drops the connection (`drop`), or only switches on an `effect`:
199
- * the request then still reaches the service.
233
+ * Fault only from this instant on the namespace clock. A duration (`"5m"`) counts from the
234
+ * clock when the rule was added. Listed as epoch ms.
235
+ */
236
+ from?: Instant$1 | Duration$1;
237
+ /** Stop faulting at this instant on the namespace clock. A duration counts from when added. */
238
+ until?: Instant$1 | Duration$1;
239
+ /**
240
+ * Status of the injected response. Omit for a rule that only delays, times out, drops,
241
+ * truncates, or switches on an `effect`: the request then still reaches the service.
200
242
  */
201
243
  status?: number;
202
244
  /** Response body, serialized as JSON. A string is sent as-is. */
203
245
  body?: unknown;
246
+ /** Response headers. */
204
247
  headers?: Record<string, string>;
205
- /** Retire the rule after this many faults. Omit to keep it until removed. */
206
- count?: number;
207
- /** Fault this fraction of matching requests, `0`–`1`. Default `1`. */
208
- rate?: number;
209
- /** Hold the response back this long, to exercise timeouts. */
248
+ /** Hold the response back this long. Listed as `delayMs`. */
249
+ delay?: Duration$1;
250
+ /** `delay`, in milliseconds. */
210
251
  delayMs?: number;
211
252
  /** Alias of `delayMs`. */
212
253
  latencyMs?: number;
254
+ /** Extra seeded delay in `[0, jitter]`. Listed as `jitterMs`. */
255
+ jitter?: Duration$1;
256
+ jitterMs?: number;
257
+ /**
258
+ * Never answer: hold the request this long, then drop the connection. Listed as
259
+ * `timeoutMs`. With virtual time the wait is spent on the mock clock.
260
+ */
261
+ timeout?: Duration$1;
262
+ timeoutMs?: number;
213
263
  /**
214
264
  * Drop the connection instead of answering: an in-process `fetch` rejects with a
215
265
  * `TypeError`, and a served mock destroys the socket. Models "unknown outcome" failures.
216
266
  */
217
267
  drop?: boolean;
268
+ /**
269
+ * Cut the response body off after this many bytes: the status and headers arrive, then
270
+ * the connection dies mid-body.
271
+ */
272
+ truncate?: number;
218
273
  /**
219
274
  * A named service behaviour to switch on for the matching request instead of (or
220
275
  * before) a canned response, e.g. `created_but_500` or `numeric_tracking_id`. Services
@@ -223,8 +278,8 @@ type FaultRule$1 = {
223
278
  effect?: string;
224
279
  /** Parameters for `effect`. */
225
280
  params?: Record<string, unknown>;
226
- /** From the preset this rule was expanded from, if any. */
227
- preset?: string;
281
+ /** The preset this rule was expanded from, if any. */
282
+ fromPreset?: string;
228
283
  };
229
284
  /** A fault that fired for one request. */
230
285
  type FaultHit$1 = {
@@ -232,6 +287,10 @@ type FaultHit$1 = {
232
287
  /** The injected response; absent when the rule only delays, drops, or sets an effect. */
233
288
  response?: Response;
234
289
  drop?: boolean;
290
+ /** Set with `drop` when the rule held the request for its `timeout` first. */
291
+ timeout?: boolean;
292
+ /** Bytes of response body to let through before the connection dies. */
293
+ truncate?: number;
235
294
  effect?: {
236
295
  name: string;
237
296
  params: Record<string, unknown>;
@@ -243,38 +302,200 @@ type FaultCandidate$1 = {
243
302
  method: string;
244
303
  path: string;
245
304
  namespace: string;
305
+ /** Request headers and query, for rules that match on them. */
306
+ headers?: Headers;
307
+ query?: URLSearchParams;
308
+ /** The namespace clock, for `from` / `until`. Rules with a window are skipped without it. */
309
+ now?: number;
310
+ /** How to spend a delay for this request. Default: the registry's own sleep. */
311
+ wait?: (ms: number) => Promise<void>;
312
+ };
313
+ /** A stored rule and how often it was consulted. */
314
+ type FaultListing$1 = FaultRule$1 & {
315
+ /** Faults left before the rule retires. `null` when it has no `count`. */
316
+ remaining: number | null;
317
+ /** Times the rule faulted a request. */
318
+ hits: number;
319
+ /** Requests that matched the rule, faulted or not. */
320
+ seen: number;
321
+ };
322
+ /** A namespace's own rules, with their counters, in the order they are tried. */
323
+ type FaultSnapshot$1 = {
324
+ /**
325
+ * `position` is how many `"*"` rules are tried before the rule, which is what its place
326
+ * in the order means to a request and holds in any process.
327
+ */
328
+ rules: (FaultListing$1 & {
329
+ position?: number;
330
+ })[];
331
+ /** How many `fault_<n>` ids the namespace has handed out. */
332
+ nextId?: number;
246
333
  };
247
334
  type FaultRegistry$1 = {
248
- isolateNamespaces(): void;
249
- snapshot(namespace: string): {
250
- rules: (FaultRule$1 & {
251
- remaining: number | null;
252
- hits: number;
253
- position: number;
254
- })[];
255
- rngState: number;
256
- };
335
+ snapshot(namespace: string): FaultSnapshot$1;
336
+ /** Add a rule, or replace the rule with the same id in the same namespace. */
257
337
  add(rule: FaultRule$1): FaultRule$1;
258
- list(): (FaultRule$1 & {
259
- remaining: number | null;
260
- hits: number;
261
- })[];
262
- remove(id: string): boolean;
263
- clear(): void;
264
- restore(namespace: string, state: {
265
- rules: (FaultRule$1 & {
266
- remaining: number | null;
267
- hits: number;
268
- position: number;
269
- })[];
270
- rngState: number;
271
- }): void;
338
+ /** The next unused `fault_<n>` id in `namespace`. */
339
+ nextId(namespace: string): string;
340
+ /** Every rule, or the rules a namespace's requests can hit: its own and the global ones. */
341
+ list(namespace?: string): FaultListing$1[];
342
+ get(id: string, namespace?: string): FaultListing$1 | undefined;
343
+ /** Remove a rule by id: from `namespace` (its own, then a global one), or wherever it is. */
344
+ remove(id: string, namespace?: string): boolean;
345
+ /** Remove every rule, or one namespace's own rules. */
346
+ clear(namespace?: string): void;
347
+ /** Replace a namespace's own rules with a snapshot's, wherever the snapshot was taken. */
348
+ restore(namespace: string, state: FaultSnapshot$1): void;
272
349
  /**
273
350
  * Every fault this request should get, in rule order, stopping at the first that answers
274
351
  * or drops (effect-only and delay-only rules let later rules match too). Consumes one of
275
352
  * each matching rule's remaining uses.
276
353
  */
277
354
  take(candidate: FaultCandidate$1): Promise<FaultHit$1[]>;
355
+ /**
356
+ * Fire these rules at one request without storing them: no matching, no schedule, in order,
357
+ * stopping at the first that answers or drops. Jitter draws from the namespace's stream.
358
+ */
359
+ fire(rules: readonly FaultRule$1[], candidate: FaultCandidate$1): Promise<FaultHit$1[]>;
360
+ };
361
+
362
+ /**
363
+ * The admin controls every mock shares, as one document.
364
+ *
365
+ * The same shape is accepted in three places, and means the same thing in each:
366
+ *
367
+ * - at boot: `createRuntime({ adminControls })`, `serve --admin-controls`,
368
+ * `MOCKINGBIRD_ADMIN_CONTROLS`
369
+ * - over HTTP: `PUT /__admin/controls`
370
+ * - per request: the `x-mockingbird-*` headers in {@link CONTROL_HEADERS}
371
+ *
372
+ * Every control is deterministic: given the same seed, clock and requests, a mock answers
373
+ * the same bytes. Nothing here reads the wall clock or `Math.random`.
374
+ */
375
+ /** Milliseconds, or a string like `"250ms"`, `"2s"`, `"15m"`, `"1h"`, `"3d"`. */
376
+ type Duration$1 = number | string;
377
+ /** Epoch milliseconds, or an ISO-8601 string. */
378
+ type Instant$1 = number | string;
379
+ type ClockControls$1 = {
380
+ /** Move the clock to this instant. */
381
+ now?: Instant$1;
382
+ /** Stop time. A frozen clock moves only when told to, so timestamps replay exactly. */
383
+ frozen?: boolean;
384
+ /**
385
+ * Step the clock forward by this much before every vendor request. With a frozen clock
386
+ * each request still gets its own, reproducible timestamp.
387
+ */
388
+ autoAdvance?: Duration$1;
389
+ };
390
+ /** How long a response takes: a fixed delay plus seeded jitter in `[0, jitter]`. */
391
+ type LatencyRuleInput$1 = {
392
+ delay?: Duration$1;
393
+ jitter?: Duration$1;
394
+ };
395
+ type LatencyControls$1 = LatencyRuleInput$1 & {
396
+ /** Per-operation overrides, keyed by operationId. A bare duration is its `delay`. */
397
+ operations?: Record<string, Duration$1 | LatencyRuleInput$1>;
398
+ };
399
+ /** A fault to add: a rule (the id is assigned when omitted), or a named preset with overrides. */
400
+ type FaultInput$1 = (Omit<FaultRule$1, "id"> & {
401
+ id?: string;
402
+ }) | ({
403
+ preset: string;
404
+ } & Partial<FaultRule$1>);
405
+ /** Identifies a {@link SnapshotDocument}. */
406
+ declare const SNAPSHOT_FORMAT$1 = "mockingbird.snapshot/v1";
407
+ /**
408
+ * A namespace, as portable JSON: what `GET /__admin/snapshots/:id` returns and what
409
+ * `PUT /__admin/snapshots/:id` and the boot `snapshot` control accept. Only `format` and
410
+ * `records` are required, so a hand-written seed file is a valid snapshot.
411
+ */
412
+ type SnapshotDocument$1 = {
413
+ format: typeof SNAPSHOT_FORMAT$1;
414
+ /** The service that wrote it. A snapshot is rejected by any other service. */
415
+ service?: string;
416
+ /**
417
+ * Stored rows. `seq` orders a collection; omitted, rows keep their listed order. `raw` is
418
+ * the stored text of a row that is not a plain record, and replaces `value` when present.
419
+ */
420
+ records: {
421
+ collection: string;
422
+ id: string;
423
+ seq?: number;
424
+ value?: unknown;
425
+ raw?: string;
426
+ }[];
427
+ /** Id counters, so the next generated id continues where the snapshot left off. */
428
+ sequences?: {
429
+ name: string;
430
+ kind: string;
431
+ value: number;
432
+ }[];
433
+ clock?: {
434
+ now: number;
435
+ frozen: boolean;
436
+ autoAdvanceMs?: number;
437
+ };
438
+ seed?: number | string;
439
+ /** Positions of the seeded random streams. */
440
+ rng?: {
441
+ state: number;
442
+ faults?: number;
443
+ latency?: number;
444
+ };
445
+ faults?: unknown;
446
+ latency?: unknown;
447
+ virtualTime?: boolean;
448
+ };
449
+ /** Controls for one namespace. */
450
+ type NamespaceControls$1 = {
451
+ /** Seeds every random choice: fault rates, jitter, and whatever the service invents. */
452
+ seed?: number | string;
453
+ clock?: ClockControls$1;
454
+ /**
455
+ * Spend injected waits (latency, fault delays, timeouts) on the mock clock instead of the
456
+ * wall clock: the request returns at once, the clock has moved, and the journal records
457
+ * the wait exactly. Default `false`: waits are real, so a client's own timeout can fire.
458
+ */
459
+ virtualTime?: boolean;
460
+ /** Baseline response time for every vendor request. A bare duration is its `delay`. */
461
+ latency?: Duration$1 | LatencyControls$1;
462
+ faults?: readonly FaultInput$1[];
463
+ /** Start from this state instead of the service's own seed data. */
464
+ snapshot?: SnapshotDocument$1;
465
+ };
466
+ /** {@link NamespaceControls} for every namespace, with per-namespace overrides. */
467
+ type MockControls$1 = NamespaceControls$1 & {
468
+ /** Vendor credential → namespace, for SDKs that cannot send a namespace header. */
469
+ credentials?: Record<string, string>;
470
+ /** Overrides for named namespaces. A key given here replaces the shared value. */
471
+ namespaces?: Record<string, NamespaceControls$1>;
472
+ };
473
+ /** A latency rule in milliseconds. */
474
+ type LatencyRule$1 = {
475
+ delayMs: number;
476
+ jitterMs: number;
477
+ };
478
+ /** Baseline latency for a namespace, normalized. */
479
+ type LatencyState$1 = LatencyRule$1 & {
480
+ operations: Record<string, LatencyRule$1>;
481
+ };
482
+ /** What {@link controlHeaders} turns into request headers. */
483
+ type ControlHeaderInput$1 = {
484
+ namespace?: string;
485
+ adminKey?: string;
486
+ branch?: string;
487
+ at?: string;
488
+ reset?: boolean;
489
+ restore?: string;
490
+ seed?: number | string;
491
+ time?: Instant$1 | Date;
492
+ advance?: Duration$1;
493
+ virtualTime?: boolean;
494
+ delay?: Duration$1;
495
+ timeout?: Duration$1;
496
+ /** A status, `"drop"`, a preset name, or a fault rule. */
497
+ fault?: number | string | Record<string, unknown>;
498
+ snapshot?: string;
278
499
  };
279
500
 
280
501
  /**
@@ -314,6 +535,8 @@ type RequestLog$1 = {
314
535
  unmatched: boolean;
315
536
  /** Set when a fault rule produced the response. */
316
537
  faultId?: string;
538
+ /** Milliseconds of injected wait: latency, fault delays and timeouts. Absent when none. */
539
+ delayMs?: number;
317
540
  /** Resource ids the handler touched (`userId`, `orderId`, …), when the service reports them. */
318
541
  ids?: Record<string, string>;
319
542
  /** Set when the service created a resource the request referred to but that did not exist. */
@@ -359,6 +582,12 @@ type JournalQuery$1 = {
359
582
  /** Only this namespace. Omit for every namespace, oldest first across all of them. */
360
583
  namespace?: string;
361
584
  operationId?: string;
585
+ /** Only this HTTP method, case-insensitive. */
586
+ method?: string;
587
+ /** Only this exact path. */
588
+ path?: string;
589
+ /** Only requests this fault rule answered or shaped. */
590
+ faultId?: string;
362
591
  status?: number;
363
592
  /** Only entries at or after this instant (epoch ms). */
364
593
  since?: number;
@@ -373,6 +602,50 @@ type Journal$1 = {
373
602
  clear(namespace?: string): void;
374
603
  };
375
604
 
605
+ /**
606
+ * Baseline response time, per namespace: how long every vendor request takes before any
607
+ * fault is considered. Jitter draws from a stream the caller owns, one per namespace and
608
+ * separate from the fault stream, so adding latency never shifts which requests a `rate`
609
+ * fault hits.
610
+ */
611
+ type LatencyRegistry$1 = {
612
+ get(namespace: string): LatencyState$1;
613
+ set(namespace: string, state: LatencyState$1): LatencyState$1;
614
+ /** Remove one namespace's latency, or every namespace's. */
615
+ clear(namespace?: string): void;
616
+ /** Milliseconds this request waits. Draws jitter, so call it once per request. */
617
+ take(namespace: string, operationId: string | undefined): number;
618
+ };
619
+
620
+ /** Clock state as the admin API reports it. */
621
+ type ControlClock$1 = ClockState$1 & {
622
+ /** `now`, as ISO-8601. */
623
+ iso: string;
624
+ /** Milliseconds the clock steps before every vendor request. */
625
+ autoAdvanceMs: number;
626
+ };
627
+ /** One namespace's controls: the body of `GET /__admin/controls`. */
628
+ type ControlState$1 = {
629
+ namespace: string;
630
+ seed: number | string;
631
+ clock: ControlClock$1;
632
+ virtualTime: boolean;
633
+ latency: LatencyState$1;
634
+ faults: FaultListing$1[];
635
+ };
636
+
637
+ /** What `GET /__admin/snapshots` lists for each snapshot. */
638
+ type SnapshotInfo$1 = {
639
+ id: string;
640
+ namespace: string;
641
+ /** Stored rows in the snapshot. */
642
+ records: number;
643
+ /** The namespace clock when it was taken, epoch ms. */
644
+ at: number;
645
+ /** Whether `GET /snapshots/:id` can return it as a {@link SnapshotDocument}. */
646
+ portable: boolean;
647
+ };
648
+
376
649
  /** Credential → namespace mapping behind `PUT /__admin/credentials`. */
377
650
  type CredentialRegistry$1 = {
378
651
  set(credential: string, namespace: string): void;
@@ -527,7 +800,10 @@ type ServiceInstance$1 = FetchAPI$2 & {
527
800
  };
528
801
  type ServiceTimelineState$1 = Readonly<{
529
802
  snapshot: NamespaceSnapshot$1;
530
- clock: Readonly<ReturnType<Clock$1["state"]>>;
803
+ /** `pinned`: the namespace's clock was frozen itself, not just following a frozen base. */
804
+ clock: Readonly<ClockState$1 & {
805
+ pinned?: boolean;
806
+ }>;
531
807
  rngState: number;
532
808
  }>;
533
809
  type ServiceCheckpoint$1 = Checkpoint$1<ServiceTimelineState$1>;
@@ -535,17 +811,23 @@ type ServiceRuntime$1<T extends ServiceInstance$1> = FetchAPI$2 & {
535
811
  /** Stop package-owned lifecycle timers when a supervisor closes the runtime. */
536
812
  stop?(): void;
537
813
  readonly name: string;
814
+ /** Same-origin Fetch handler and App Router method exports, sharing this runtime. */
815
+ mount(prefix: string): MountedAPI$1;
538
816
  readonly sqlite: SqliteClient$2;
539
817
  readonly clock: Clock$1;
540
818
  readonly faults: FaultRegistry$1;
819
+ /** Baseline response time per namespace. */
820
+ readonly latency: LatencyRegistry$1;
541
821
  readonly metrics: Metrics$1;
542
822
  readonly journal: Journal$1;
543
823
  readonly rng: Rng$1;
544
824
  readonly credentials: CredentialRegistry$1;
545
825
  /** The webhook hub, when the service has outbound webhooks. */
546
826
  readonly webhooks: WebhookHub$1 | undefined;
547
- /** Enable independent namespace clocks and PRNGs before serving a fleet. */
548
- isolateNamespaces(): void;
827
+ /**
828
+ * A namespace's clock. Each follows the base clock, {@link ServiceRuntime.clock}, with an
829
+ * offset and a freeze of its own, so moving one never moves another.
830
+ */
549
831
  namespaceClock(namespace?: string): Clock$1;
550
832
  namespaceOf(request: Request): string;
551
833
  /** Opaque in-process checkpoint including records, controls and webhook history. */
@@ -557,8 +839,38 @@ type ServiceRuntime$1<T extends ServiceInstance$1> = FetchAPI$2 & {
557
839
  instance(namespace?: string): T;
558
840
  /** Public names of every namespace created so far. */
559
841
  namespaces(): string[];
560
- /** Reset one namespace, or every namespace with `"*"`. */
842
+ /** Return one namespace to its boot state, or every namespace with `"*"`. */
561
843
  reset(namespace?: string): Promise<void>;
844
+ /** Reset a namespace and forget it, releasing everything it held. */
845
+ dropNamespace(namespace: string): Promise<void>;
846
+ /** A namespace's controls: seed, clock, virtual time, latency, faults and snapshots. */
847
+ controls(namespace?: string): ControlState$1 & {
848
+ snapshots: SnapshotInfo$1[];
849
+ };
850
+ /** Apply a control document to a namespace. A given key replaces that control. */
851
+ configure(controls: NamespaceControls$1, namespace?: string): ControlState$1 & {
852
+ snapshots: SnapshotInfo$1[];
853
+ };
854
+ /** Named snapshots of a namespace: records, clock, random streams, faults and latency. */
855
+ readonly snapshots: {
856
+ /** Capture the namespace now. Reusing a name replaces that snapshot. */
857
+ create(options?: {
858
+ name?: string;
859
+ namespace?: string;
860
+ }): SnapshotInfo$1;
861
+ list(namespace?: string): SnapshotInfo$1[];
862
+ /** The snapshot as portable JSON, to commit beside a suite or boot another mock from. */
863
+ export(id: string, namespace?: string): SnapshotDocument$1;
864
+ /** Store a document as a snapshot without restoring it. */
865
+ import(document: SnapshotDocument$1, options?: {
866
+ name?: string;
867
+ namespace?: string;
868
+ }): SnapshotInfo$1;
869
+ restore(id: string, namespace?: string): void;
870
+ delete(id: string, namespace?: string): boolean;
871
+ };
872
+ /** Request headers that carry controls, checked: spread them into a `fetch` or an SDK's defaults. */
873
+ headers(input: ControlHeaderInput$1): Record<string, string>;
562
874
  snapshot(namespace?: string): NamespaceSnapshot$1;
563
875
  restore(snapshot: NamespaceSnapshot$1, namespace?: string): void;
564
876
  /** Capture the current branch. Mutating HTTP calls do this automatically. */
@@ -601,6 +913,11 @@ type CommonServeOptions = {
601
913
  adminKey: string | undefined;
602
914
  seed: string | undefined;
603
915
  onLog: ((entry: RequestLog$1) => void) | undefined;
916
+ /** Admin controls to boot with: clock, latency, faults, a starting snapshot. */
917
+ adminControls?: MockControls$1;
918
+ /** Synthetic provider fixture objects supplied by a fleet entry. */
919
+ fixtures?: Record<string, unknown>;
920
+ baseUrl?: string;
604
921
  };
605
922
  /**
606
923
  * What a service contributes to `serve`: how to build its runtime from CLI flags,
@@ -648,88 +965,16 @@ type H2cListening = {
648
965
  */
649
966
  declare const listenH2c: (api: FetchAPI$1, options?: H2cListenOptions) => Promise<H2cListening>;
650
967
 
651
- /** Bind values accepted by Mockingbird's SQLite port (matches sqlite-mem / better-sqlite3). */
652
- type SqliteValue$1 = null | number | bigint | string | Uint8Array | boolean;
653
- /** Mutation counters returned by {@link SqliteStatement.run}. */
654
- type SqliteRunResult$1 = {
655
- changes: number;
656
- lastInsertRowid: number | bigint;
968
+ type MountedAPI = FetchAPI & {
969
+ readonly prefix: string;
970
+ GET: FetchHandler;
971
+ POST: FetchHandler;
972
+ PUT: FetchHandler;
973
+ PATCH: FetchHandler;
974
+ DELETE: FetchHandler;
975
+ HEAD: FetchHandler;
976
+ OPTIONS: FetchHandler;
657
977
  };
658
- /**
659
- * Prepared statement bound to a {@link SqliteClient}.
660
- *
661
- * Pass bind values as rest arguments on each call (no sticky `bind()`).
662
- */
663
- interface SqliteStatement$1 {
664
- run(...params: SqliteValue$1[]): SqliteRunResult$1;
665
- all<T = Record<string, unknown>>(...params: SqliteValue$1[]): T[];
666
- get<T = Record<string, unknown>>(...params: SqliteValue$1[]): T | undefined;
667
- }
668
- /**
669
- * Sync SQLite client port owned by Mockingbird.
670
- *
671
- * Duck-typed so `@crvouga/mockingbird-service-sqlite` `Database`, better-sqlite3, and wrapped
672
- * `bun:sqlite` instances all work when they expose this surface.
673
- */
674
- interface SqliteClient$1 {
675
- exec(sql: string): void;
676
- prepare(sql: string): SqliteStatement$1;
677
- transaction<T>(fn: () => T): T;
678
- }
679
-
680
- /** Every stored record carries a monotonically increasing sequence for stable ordering. */
681
- type Stored<T> = {
682
- seq: number;
683
- value: T;
684
- };
685
- type ListRecordsOptions<T> = {
686
- /** Keep only records passing the predicate. */
687
- where?: (value: T, seq: number) => boolean;
688
- /** Sort order; default newest first. */
689
- order?: "newest" | "oldest";
690
- };
691
- /**
692
- * A SQLite-backed table of JSON records addressed by id. Ordering is by insertion
693
- * sequence, never by id lexicographic order, so list semantics stay stable.
694
- */
695
- declare class Collection<T> {
696
- private readonly sqlite;
697
- /** Storage namespace. Admin introspection uses this to ignore another namespace's tables. */
698
- readonly namespace: string;
699
- /** Table name inside the namespace. Stable across resets of the rows themselves. */
700
- readonly collectionName: string;
701
- constructor(sqlite: SqliteClient$1,
702
- /** Storage namespace. Admin introspection uses this to ignore another namespace's tables. */
703
- namespace: string,
704
- /** Table name inside the namespace. Stable across resets of the rows themselves. */
705
- collectionName: string);
706
- private bumpCollectionSeq;
707
- nextSequence(): number;
708
- get(id: string): T | undefined;
709
- has(id: string): boolean;
710
- /** Insert a new record, assigning it the next sequence number. */
711
- insert(id: string, value: T): Stored<T>;
712
- /** Replace an existing record's value, keeping its position. */
713
- update(id: string, value: T): Stored<T> | undefined;
714
- delete(id: string): boolean;
715
- /** How many records the collection holds, without reading them. */
716
- count(): number;
717
- list(options?: ListRecordsOptions<T>): Array<Stored<T> & {
718
- id: string;
719
- }>;
720
- }
721
-
722
- /**
723
- * Sequential id source persisted in SQLite. Ids are deterministic for a given
724
- * sequence history (`cus_` + 14 opaque chars), so reproductions stay stable.
725
- */
726
- declare class IdSequence {
727
- private readonly sqlite;
728
- private readonly namespace;
729
- private readonly salt;
730
- constructor(sqlite: SqliteClient$1, namespace: string, salt?: string);
731
- next(prefix: string, length?: number): string;
732
- }
733
978
 
734
979
  /** A stable identifier for a point in a {@link Timeline}. */
735
980
  type CheckpointId = string;
@@ -820,6 +1065,91 @@ declare class Timeline<T> {
820
1065
  interface FetchAPI {
821
1066
  fetch(request: Request): Promise<Response>;
822
1067
  }
1068
+ /** A bare function form of {@link FetchAPI}, compatible with `Bun.serve`, workerd, and Deno. */
1069
+ type FetchHandler = (request: Request) => Promise<Response>;
1070
+
1071
+ /** Bind values accepted by Mockingbird's SQLite port (matches sqlite-mem / better-sqlite3). */
1072
+ type SqliteValue$1 = null | number | bigint | string | Uint8Array | boolean;
1073
+ /** Mutation counters returned by {@link SqliteStatement.run}. */
1074
+ type SqliteRunResult$1 = {
1075
+ changes: number;
1076
+ lastInsertRowid: number | bigint;
1077
+ };
1078
+ /**
1079
+ * Prepared statement bound to a {@link SqliteClient}.
1080
+ *
1081
+ * Pass bind values as rest arguments on each call (no sticky `bind()`).
1082
+ */
1083
+ interface SqliteStatement$1 {
1084
+ run(...params: SqliteValue$1[]): SqliteRunResult$1;
1085
+ all<T = Record<string, unknown>>(...params: SqliteValue$1[]): T[];
1086
+ get<T = Record<string, unknown>>(...params: SqliteValue$1[]): T | undefined;
1087
+ }
1088
+ /**
1089
+ * Sync SQLite client port owned by Mockingbird.
1090
+ *
1091
+ * Duck-typed so `@crvouga/mockingbird-service-sqlite` `Database`, better-sqlite3, and wrapped
1092
+ * `bun:sqlite` instances all work when they expose this surface.
1093
+ */
1094
+ interface SqliteClient$1 {
1095
+ exec(sql: string): void;
1096
+ prepare(sql: string): SqliteStatement$1;
1097
+ transaction<T>(fn: () => T): T;
1098
+ }
1099
+
1100
+ /** Every stored record carries a monotonically increasing sequence for stable ordering. */
1101
+ type Stored<T> = {
1102
+ seq: number;
1103
+ value: T;
1104
+ };
1105
+ type ListRecordsOptions<T> = {
1106
+ /** Keep only records passing the predicate. */
1107
+ where?: (value: T, seq: number) => boolean;
1108
+ /** Sort order; default newest first. */
1109
+ order?: "newest" | "oldest";
1110
+ };
1111
+ /**
1112
+ * A SQLite-backed table of JSON records addressed by id. Ordering is by insertion
1113
+ * sequence, never by id lexicographic order, so list semantics stay stable.
1114
+ */
1115
+ declare class Collection<T> {
1116
+ private readonly sqlite;
1117
+ /** Storage namespace. Admin introspection uses this to ignore another namespace's tables. */
1118
+ readonly namespace: string;
1119
+ /** Table name inside the namespace. Stable across resets of the rows themselves. */
1120
+ readonly collectionName: string;
1121
+ constructor(sqlite: SqliteClient$1,
1122
+ /** Storage namespace. Admin introspection uses this to ignore another namespace's tables. */
1123
+ namespace: string,
1124
+ /** Table name inside the namespace. Stable across resets of the rows themselves. */
1125
+ collectionName: string);
1126
+ private bumpCollectionSeq;
1127
+ nextSequence(): number;
1128
+ get(id: string): T | undefined;
1129
+ has(id: string): boolean;
1130
+ /** Insert a new record, assigning it the next sequence number. */
1131
+ insert(id: string, value: T): Stored<T>;
1132
+ /** Replace an existing record's value, keeping its position. */
1133
+ update(id: string, value: T): Stored<T> | undefined;
1134
+ delete(id: string): boolean;
1135
+ /** How many records the collection holds, without reading them. */
1136
+ count(): number;
1137
+ list(options?: ListRecordsOptions<T>): Array<Stored<T> & {
1138
+ id: string;
1139
+ }>;
1140
+ }
1141
+
1142
+ /**
1143
+ * Sequential id source persisted in SQLite. Ids are deterministic for a given
1144
+ * sequence history (`cus_` + 14 opaque chars), so reproductions stay stable.
1145
+ */
1146
+ declare class IdSequence {
1147
+ private readonly sqlite;
1148
+ private readonly namespace;
1149
+ private readonly salt;
1150
+ constructor(sqlite: SqliteClient$1, namespace: string, salt?: string);
1151
+ next(prefix: string, length?: number): string;
1152
+ }
823
1153
 
824
1154
  /** Options every provider constructor accepts. */
825
1155
  type APIOptions = {
@@ -846,7 +1176,7 @@ type ClockState = {
846
1176
  now: number;
847
1177
  /** True while time does not advance on its own. */
848
1178
  frozen: boolean;
849
- /** Milliseconds this clock adds to its underlying source. */
1179
+ /** Milliseconds a running clock adds to its underlying source. `0` while frozen. */
850
1180
  offsetMs: number;
851
1181
  };
852
1182
  type Clock = {
@@ -882,7 +1212,10 @@ type Rng = {
882
1212
  state(): number;
883
1213
  /** Restore a state previously returned by {@link state}. */
884
1214
  setState(state: number): void;
885
- seed: number;
1215
+ /** Restart the stream from a new seed. `reset` then returns to this seed. */
1216
+ reseed(seed: number | string): void;
1217
+ /** The seed the stream currently starts from. */
1218
+ readonly seed: number;
886
1219
  };
887
1220
 
888
1221
  /**
@@ -891,44 +1224,83 @@ type Rng = {
891
1224
  * This is how a suite reaches the vendor's failure modes without the vendor: the
892
1225
  * quota error that only appears when a shared sandbox is full, the 429 that only
893
1226
  * appears under load, the 5xx that proves a retry path works.
1227
+ *
1228
+ * A rule has three parts. What it **matches** (`operationId`, `method`, `path`, …), **when**
1229
+ * it fires among the matching requests (`after`, `every`, `count`, `rate`, `from`, `until`),
1230
+ * and what it **does** (`status`, `delay`, `timeout`, `drop`, `truncate`, `effect`).
894
1231
  */
895
1232
  type FaultRule = {
896
- /** Stable id, so a suite can retire exactly the rule it added. */
1233
+ /** Stable id, so a suite can retire exactly the rule it added. Unique within a namespace. */
897
1234
  id: string;
898
1235
  /** Fault only this operation. Omit to match every operation. */
899
1236
  operationId?: string;
900
1237
  /** Fault only this HTTP method, case-insensitive. Omit to match every method. */
901
1238
  method?: string;
1239
+ /** Fault only this exact path. */
1240
+ path?: string;
902
1241
  /** Fault only paths starting with this prefix. Omit to match every path. */
903
1242
  pathPrefix?: string;
1243
+ /** Fault only paths matching this regular expression (JavaScript syntax, unanchored). */
1244
+ pathPattern?: string;
1245
+ /** Fault only requests carrying these headers. `"*"` matches any value. */
1246
+ requestHeaders?: Record<string, string>;
1247
+ /** Fault only requests carrying these query parameters. `"*"` matches any value. */
1248
+ query?: Record<string, string>;
904
1249
  /**
905
1250
  * Fault only this namespace. Omit (or `"*"`) to fault every namespace — which is what
906
1251
  * an in-process caller usually wants, and what a parallel worker usually does not:
907
1252
  * rules added through `POST /__admin/faults` default to the calling namespace.
908
1253
  */
909
1254
  namespace?: string;
1255
+ /** Let this many matching requests through first. */
1256
+ after?: number;
1257
+ /** Then fault only every nth matching request: `3` faults the 3rd, 6th, 9th. */
1258
+ every?: number;
1259
+ /** Retire the rule after this many faults. Omit to keep it until removed. */
1260
+ count?: number;
1261
+ /** Fault this fraction of the remaining requests, `0`–`1`, drawn from the seed. Default `1`. */
1262
+ rate?: number;
910
1263
  /**
911
- * Status of the injected response. Omit for a rule that only delays (`delayMs` /
912
- * `latencyMs`), only drops the connection (`drop`), or only switches on an `effect`:
913
- * the request then still reaches the service.
1264
+ * Fault only from this instant on the namespace clock. A duration (`"5m"`) counts from the
1265
+ * clock when the rule was added. Listed as epoch ms.
1266
+ */
1267
+ from?: Instant | Duration;
1268
+ /** Stop faulting at this instant on the namespace clock. A duration counts from when added. */
1269
+ until?: Instant | Duration;
1270
+ /**
1271
+ * Status of the injected response. Omit for a rule that only delays, times out, drops,
1272
+ * truncates, or switches on an `effect`: the request then still reaches the service.
914
1273
  */
915
1274
  status?: number;
916
1275
  /** Response body, serialized as JSON. A string is sent as-is. */
917
1276
  body?: unknown;
1277
+ /** Response headers. */
918
1278
  headers?: Record<string, string>;
919
- /** Retire the rule after this many faults. Omit to keep it until removed. */
920
- count?: number;
921
- /** Fault this fraction of matching requests, `0`–`1`. Default `1`. */
922
- rate?: number;
923
- /** Hold the response back this long, to exercise timeouts. */
1279
+ /** Hold the response back this long. Listed as `delayMs`. */
1280
+ delay?: Duration;
1281
+ /** `delay`, in milliseconds. */
924
1282
  delayMs?: number;
925
1283
  /** Alias of `delayMs`. */
926
1284
  latencyMs?: number;
1285
+ /** Extra seeded delay in `[0, jitter]`. Listed as `jitterMs`. */
1286
+ jitter?: Duration;
1287
+ jitterMs?: number;
1288
+ /**
1289
+ * Never answer: hold the request this long, then drop the connection. Listed as
1290
+ * `timeoutMs`. With virtual time the wait is spent on the mock clock.
1291
+ */
1292
+ timeout?: Duration;
1293
+ timeoutMs?: number;
927
1294
  /**
928
1295
  * Drop the connection instead of answering: an in-process `fetch` rejects with a
929
1296
  * `TypeError`, and a served mock destroys the socket. Models "unknown outcome" failures.
930
1297
  */
931
1298
  drop?: boolean;
1299
+ /**
1300
+ * Cut the response body off after this many bytes: the status and headers arrive, then
1301
+ * the connection dies mid-body.
1302
+ */
1303
+ truncate?: number;
932
1304
  /**
933
1305
  * A named service behaviour to switch on for the matching request instead of (or
934
1306
  * before) a canned response, e.g. `created_but_500` or `numeric_tracking_id`. Services
@@ -937,8 +1309,8 @@ type FaultRule = {
937
1309
  effect?: string;
938
1310
  /** Parameters for `effect`. */
939
1311
  params?: Record<string, unknown>;
940
- /** From the preset this rule was expanded from, if any. */
941
- preset?: string;
1312
+ /** The preset this rule was expanded from, if any. */
1313
+ fromPreset?: string;
942
1314
  };
943
1315
  /** A fault that fired for one request. */
944
1316
  type FaultHit = {
@@ -946,6 +1318,10 @@ type FaultHit = {
946
1318
  /** The injected response; absent when the rule only delays, drops, or sets an effect. */
947
1319
  response?: Response;
948
1320
  drop?: boolean;
1321
+ /** Set with `drop` when the rule held the request for its `timeout` first. */
1322
+ timeout?: boolean;
1323
+ /** Bytes of response body to let through before the connection dies. */
1324
+ truncate?: number;
949
1325
  effect?: {
950
1326
  name: string;
951
1327
  params: Record<string, unknown>;
@@ -957,38 +1333,200 @@ type FaultCandidate = {
957
1333
  method: string;
958
1334
  path: string;
959
1335
  namespace: string;
1336
+ /** Request headers and query, for rules that match on them. */
1337
+ headers?: Headers;
1338
+ query?: URLSearchParams;
1339
+ /** The namespace clock, for `from` / `until`. Rules with a window are skipped without it. */
1340
+ now?: number;
1341
+ /** How to spend a delay for this request. Default: the registry's own sleep. */
1342
+ wait?: (ms: number) => Promise<void>;
1343
+ };
1344
+ /** A stored rule and how often it was consulted. */
1345
+ type FaultListing = FaultRule & {
1346
+ /** Faults left before the rule retires. `null` when it has no `count`. */
1347
+ remaining: number | null;
1348
+ /** Times the rule faulted a request. */
1349
+ hits: number;
1350
+ /** Requests that matched the rule, faulted or not. */
1351
+ seen: number;
1352
+ };
1353
+ /** A namespace's own rules, with their counters, in the order they are tried. */
1354
+ type FaultSnapshot = {
1355
+ /**
1356
+ * `position` is how many `"*"` rules are tried before the rule, which is what its place
1357
+ * in the order means to a request and holds in any process.
1358
+ */
1359
+ rules: (FaultListing & {
1360
+ position?: number;
1361
+ })[];
1362
+ /** How many `fault_<n>` ids the namespace has handed out. */
1363
+ nextId?: number;
960
1364
  };
961
1365
  type FaultRegistry = {
962
- isolateNamespaces(): void;
963
- snapshot(namespace: string): {
964
- rules: (FaultRule & {
965
- remaining: number | null;
966
- hits: number;
967
- position: number;
968
- })[];
969
- rngState: number;
970
- };
1366
+ snapshot(namespace: string): FaultSnapshot;
1367
+ /** Add a rule, or replace the rule with the same id in the same namespace. */
971
1368
  add(rule: FaultRule): FaultRule;
972
- list(): (FaultRule & {
973
- remaining: number | null;
974
- hits: number;
975
- })[];
976
- remove(id: string): boolean;
977
- clear(): void;
978
- restore(namespace: string, state: {
979
- rules: (FaultRule & {
980
- remaining: number | null;
981
- hits: number;
982
- position: number;
983
- })[];
984
- rngState: number;
985
- }): void;
1369
+ /** The next unused `fault_<n>` id in `namespace`. */
1370
+ nextId(namespace: string): string;
1371
+ /** Every rule, or the rules a namespace's requests can hit: its own and the global ones. */
1372
+ list(namespace?: string): FaultListing[];
1373
+ get(id: string, namespace?: string): FaultListing | undefined;
1374
+ /** Remove a rule by id: from `namespace` (its own, then a global one), or wherever it is. */
1375
+ remove(id: string, namespace?: string): boolean;
1376
+ /** Remove every rule, or one namespace's own rules. */
1377
+ clear(namespace?: string): void;
1378
+ /** Replace a namespace's own rules with a snapshot's, wherever the snapshot was taken. */
1379
+ restore(namespace: string, state: FaultSnapshot): void;
986
1380
  /**
987
1381
  * Every fault this request should get, in rule order, stopping at the first that answers
988
1382
  * or drops (effect-only and delay-only rules let later rules match too). Consumes one of
989
1383
  * each matching rule's remaining uses.
990
1384
  */
991
1385
  take(candidate: FaultCandidate): Promise<FaultHit[]>;
1386
+ /**
1387
+ * Fire these rules at one request without storing them: no matching, no schedule, in order,
1388
+ * stopping at the first that answers or drops. Jitter draws from the namespace's stream.
1389
+ */
1390
+ fire(rules: readonly FaultRule[], candidate: FaultCandidate): Promise<FaultHit[]>;
1391
+ };
1392
+
1393
+ /**
1394
+ * The admin controls every mock shares, as one document.
1395
+ *
1396
+ * The same shape is accepted in three places, and means the same thing in each:
1397
+ *
1398
+ * - at boot: `createRuntime({ adminControls })`, `serve --admin-controls`,
1399
+ * `MOCKINGBIRD_ADMIN_CONTROLS`
1400
+ * - over HTTP: `PUT /__admin/controls`
1401
+ * - per request: the `x-mockingbird-*` headers in {@link CONTROL_HEADERS}
1402
+ *
1403
+ * Every control is deterministic: given the same seed, clock and requests, a mock answers
1404
+ * the same bytes. Nothing here reads the wall clock or `Math.random`.
1405
+ */
1406
+ /** Milliseconds, or a string like `"250ms"`, `"2s"`, `"15m"`, `"1h"`, `"3d"`. */
1407
+ type Duration = number | string;
1408
+ /** Epoch milliseconds, or an ISO-8601 string. */
1409
+ type Instant = number | string;
1410
+ type ClockControls = {
1411
+ /** Move the clock to this instant. */
1412
+ now?: Instant;
1413
+ /** Stop time. A frozen clock moves only when told to, so timestamps replay exactly. */
1414
+ frozen?: boolean;
1415
+ /**
1416
+ * Step the clock forward by this much before every vendor request. With a frozen clock
1417
+ * each request still gets its own, reproducible timestamp.
1418
+ */
1419
+ autoAdvance?: Duration;
1420
+ };
1421
+ /** How long a response takes: a fixed delay plus seeded jitter in `[0, jitter]`. */
1422
+ type LatencyRuleInput = {
1423
+ delay?: Duration;
1424
+ jitter?: Duration;
1425
+ };
1426
+ type LatencyControls = LatencyRuleInput & {
1427
+ /** Per-operation overrides, keyed by operationId. A bare duration is its `delay`. */
1428
+ operations?: Record<string, Duration | LatencyRuleInput>;
1429
+ };
1430
+ /** A fault to add: a rule (the id is assigned when omitted), or a named preset with overrides. */
1431
+ type FaultInput = (Omit<FaultRule, "id"> & {
1432
+ id?: string;
1433
+ }) | ({
1434
+ preset: string;
1435
+ } & Partial<FaultRule>);
1436
+ /** Identifies a {@link SnapshotDocument}. */
1437
+ declare const SNAPSHOT_FORMAT = "mockingbird.snapshot/v1";
1438
+ /**
1439
+ * A namespace, as portable JSON: what `GET /__admin/snapshots/:id` returns and what
1440
+ * `PUT /__admin/snapshots/:id` and the boot `snapshot` control accept. Only `format` and
1441
+ * `records` are required, so a hand-written seed file is a valid snapshot.
1442
+ */
1443
+ type SnapshotDocument = {
1444
+ format: typeof SNAPSHOT_FORMAT;
1445
+ /** The service that wrote it. A snapshot is rejected by any other service. */
1446
+ service?: string;
1447
+ /**
1448
+ * Stored rows. `seq` orders a collection; omitted, rows keep their listed order. `raw` is
1449
+ * the stored text of a row that is not a plain record, and replaces `value` when present.
1450
+ */
1451
+ records: {
1452
+ collection: string;
1453
+ id: string;
1454
+ seq?: number;
1455
+ value?: unknown;
1456
+ raw?: string;
1457
+ }[];
1458
+ /** Id counters, so the next generated id continues where the snapshot left off. */
1459
+ sequences?: {
1460
+ name: string;
1461
+ kind: string;
1462
+ value: number;
1463
+ }[];
1464
+ clock?: {
1465
+ now: number;
1466
+ frozen: boolean;
1467
+ autoAdvanceMs?: number;
1468
+ };
1469
+ seed?: number | string;
1470
+ /** Positions of the seeded random streams. */
1471
+ rng?: {
1472
+ state: number;
1473
+ faults?: number;
1474
+ latency?: number;
1475
+ };
1476
+ faults?: unknown;
1477
+ latency?: unknown;
1478
+ virtualTime?: boolean;
1479
+ };
1480
+ /** Controls for one namespace. */
1481
+ type NamespaceControls = {
1482
+ /** Seeds every random choice: fault rates, jitter, and whatever the service invents. */
1483
+ seed?: number | string;
1484
+ clock?: ClockControls;
1485
+ /**
1486
+ * Spend injected waits (latency, fault delays, timeouts) on the mock clock instead of the
1487
+ * wall clock: the request returns at once, the clock has moved, and the journal records
1488
+ * the wait exactly. Default `false`: waits are real, so a client's own timeout can fire.
1489
+ */
1490
+ virtualTime?: boolean;
1491
+ /** Baseline response time for every vendor request. A bare duration is its `delay`. */
1492
+ latency?: Duration | LatencyControls;
1493
+ faults?: readonly FaultInput[];
1494
+ /** Start from this state instead of the service's own seed data. */
1495
+ snapshot?: SnapshotDocument;
1496
+ };
1497
+ /** {@link NamespaceControls} for every namespace, with per-namespace overrides. */
1498
+ type MockControls = NamespaceControls & {
1499
+ /** Vendor credential → namespace, for SDKs that cannot send a namespace header. */
1500
+ credentials?: Record<string, string>;
1501
+ /** Overrides for named namespaces. A key given here replaces the shared value. */
1502
+ namespaces?: Record<string, NamespaceControls>;
1503
+ };
1504
+ /** A latency rule in milliseconds. */
1505
+ type LatencyRule = {
1506
+ delayMs: number;
1507
+ jitterMs: number;
1508
+ };
1509
+ /** Baseline latency for a namespace, normalized. */
1510
+ type LatencyState = LatencyRule & {
1511
+ operations: Record<string, LatencyRule>;
1512
+ };
1513
+ /** What {@link controlHeaders} turns into request headers. */
1514
+ type ControlHeaderInput = {
1515
+ namespace?: string;
1516
+ adminKey?: string;
1517
+ branch?: string;
1518
+ at?: string;
1519
+ reset?: boolean;
1520
+ restore?: string;
1521
+ seed?: number | string;
1522
+ time?: Instant | Date;
1523
+ advance?: Duration;
1524
+ virtualTime?: boolean;
1525
+ delay?: Duration;
1526
+ timeout?: Duration;
1527
+ /** A status, `"drop"`, a preset name, or a fault rule. */
1528
+ fault?: number | string | Record<string, unknown>;
1529
+ snapshot?: string;
992
1530
  };
993
1531
 
994
1532
  /**
@@ -1028,6 +1566,8 @@ type RequestLog = {
1028
1566
  unmatched: boolean;
1029
1567
  /** Set when a fault rule produced the response. */
1030
1568
  faultId?: string;
1569
+ /** Milliseconds of injected wait: latency, fault delays and timeouts. Absent when none. */
1570
+ delayMs?: number;
1031
1571
  /** Resource ids the handler touched (`userId`, `orderId`, …), when the service reports them. */
1032
1572
  ids?: Record<string, string>;
1033
1573
  /** Set when the service created a resource the request referred to but that did not exist. */
@@ -1073,6 +1613,12 @@ type JournalQuery = {
1073
1613
  /** Only this namespace. Omit for every namespace, oldest first across all of them. */
1074
1614
  namespace?: string;
1075
1615
  operationId?: string;
1616
+ /** Only this HTTP method, case-insensitive. */
1617
+ method?: string;
1618
+ /** Only this exact path. */
1619
+ path?: string;
1620
+ /** Only requests this fault rule answered or shaped. */
1621
+ faultId?: string;
1076
1622
  status?: number;
1077
1623
  /** Only entries at or after this instant (epoch ms). */
1078
1624
  since?: number;
@@ -1087,6 +1633,50 @@ type Journal = {
1087
1633
  clear(namespace?: string): void;
1088
1634
  };
1089
1635
 
1636
+ /**
1637
+ * Baseline response time, per namespace: how long every vendor request takes before any
1638
+ * fault is considered. Jitter draws from a stream the caller owns, one per namespace and
1639
+ * separate from the fault stream, so adding latency never shifts which requests a `rate`
1640
+ * fault hits.
1641
+ */
1642
+ type LatencyRegistry = {
1643
+ get(namespace: string): LatencyState;
1644
+ set(namespace: string, state: LatencyState): LatencyState;
1645
+ /** Remove one namespace's latency, or every namespace's. */
1646
+ clear(namespace?: string): void;
1647
+ /** Milliseconds this request waits. Draws jitter, so call it once per request. */
1648
+ take(namespace: string, operationId: string | undefined): number;
1649
+ };
1650
+
1651
+ /** Clock state as the admin API reports it. */
1652
+ type ControlClock = ClockState & {
1653
+ /** `now`, as ISO-8601. */
1654
+ iso: string;
1655
+ /** Milliseconds the clock steps before every vendor request. */
1656
+ autoAdvanceMs: number;
1657
+ };
1658
+ /** One namespace's controls: the body of `GET /__admin/controls`. */
1659
+ type ControlState = {
1660
+ namespace: string;
1661
+ seed: number | string;
1662
+ clock: ControlClock;
1663
+ virtualTime: boolean;
1664
+ latency: LatencyState;
1665
+ faults: FaultListing[];
1666
+ };
1667
+
1668
+ /** What `GET /__admin/snapshots` lists for each snapshot. */
1669
+ type SnapshotInfo = {
1670
+ id: string;
1671
+ namespace: string;
1672
+ /** Stored rows in the snapshot. */
1673
+ records: number;
1674
+ /** The namespace clock when it was taken, epoch ms. */
1675
+ at: number;
1676
+ /** Whether `GET /snapshots/:id` can return it as a {@link SnapshotDocument}. */
1677
+ portable: boolean;
1678
+ };
1679
+
1090
1680
  /** Credential → namespace mapping behind `PUT /__admin/credentials`. */
1091
1681
  type CredentialRegistry = {
1092
1682
  set(credential: string, namespace: string): void;
@@ -1241,7 +1831,10 @@ type ServiceInstance = FetchAPI & {
1241
1831
  };
1242
1832
  type ServiceTimelineState = Readonly<{
1243
1833
  snapshot: NamespaceSnapshot;
1244
- clock: Readonly<ReturnType<Clock["state"]>>;
1834
+ /** `pinned`: the namespace's clock was frozen itself, not just following a frozen base. */
1835
+ clock: Readonly<ClockState & {
1836
+ pinned?: boolean;
1837
+ }>;
1245
1838
  rngState: number;
1246
1839
  }>;
1247
1840
  type ServiceCheckpoint = Checkpoint<ServiceTimelineState>;
@@ -1249,17 +1842,23 @@ type ServiceRuntime<T extends ServiceInstance> = FetchAPI & {
1249
1842
  /** Stop package-owned lifecycle timers when a supervisor closes the runtime. */
1250
1843
  stop?(): void;
1251
1844
  readonly name: string;
1845
+ /** Same-origin Fetch handler and App Router method exports, sharing this runtime. */
1846
+ mount(prefix: string): MountedAPI;
1252
1847
  readonly sqlite: SqliteClient$1;
1253
1848
  readonly clock: Clock;
1254
1849
  readonly faults: FaultRegistry;
1850
+ /** Baseline response time per namespace. */
1851
+ readonly latency: LatencyRegistry;
1255
1852
  readonly metrics: Metrics;
1256
1853
  readonly journal: Journal;
1257
1854
  readonly rng: Rng;
1258
1855
  readonly credentials: CredentialRegistry;
1259
1856
  /** The webhook hub, when the service has outbound webhooks. */
1260
1857
  readonly webhooks: WebhookHub | undefined;
1261
- /** Enable independent namespace clocks and PRNGs before serving a fleet. */
1262
- isolateNamespaces(): void;
1858
+ /**
1859
+ * A namespace's clock. Each follows the base clock, {@link ServiceRuntime.clock}, with an
1860
+ * offset and a freeze of its own, so moving one never moves another.
1861
+ */
1263
1862
  namespaceClock(namespace?: string): Clock;
1264
1863
  namespaceOf(request: Request): string;
1265
1864
  /** Opaque in-process checkpoint including records, controls and webhook history. */
@@ -1271,8 +1870,38 @@ type ServiceRuntime<T extends ServiceInstance> = FetchAPI & {
1271
1870
  instance(namespace?: string): T;
1272
1871
  /** Public names of every namespace created so far. */
1273
1872
  namespaces(): string[];
1274
- /** Reset one namespace, or every namespace with `"*"`. */
1873
+ /** Return one namespace to its boot state, or every namespace with `"*"`. */
1275
1874
  reset(namespace?: string): Promise<void>;
1875
+ /** Reset a namespace and forget it, releasing everything it held. */
1876
+ dropNamespace(namespace: string): Promise<void>;
1877
+ /** A namespace's controls: seed, clock, virtual time, latency, faults and snapshots. */
1878
+ controls(namespace?: string): ControlState & {
1879
+ snapshots: SnapshotInfo[];
1880
+ };
1881
+ /** Apply a control document to a namespace. A given key replaces that control. */
1882
+ configure(controls: NamespaceControls, namespace?: string): ControlState & {
1883
+ snapshots: SnapshotInfo[];
1884
+ };
1885
+ /** Named snapshots of a namespace: records, clock, random streams, faults and latency. */
1886
+ readonly snapshots: {
1887
+ /** Capture the namespace now. Reusing a name replaces that snapshot. */
1888
+ create(options?: {
1889
+ name?: string;
1890
+ namespace?: string;
1891
+ }): SnapshotInfo;
1892
+ list(namespace?: string): SnapshotInfo[];
1893
+ /** The snapshot as portable JSON, to commit beside a suite or boot another mock from. */
1894
+ export(id: string, namespace?: string): SnapshotDocument;
1895
+ /** Store a document as a snapshot without restoring it. */
1896
+ import(document: SnapshotDocument, options?: {
1897
+ name?: string;
1898
+ namespace?: string;
1899
+ }): SnapshotInfo;
1900
+ restore(id: string, namespace?: string): void;
1901
+ delete(id: string, namespace?: string): boolean;
1902
+ };
1903
+ /** Request headers that carry controls, checked: spread them into a `fetch` or an SDK's defaults. */
1904
+ headers(input: ControlHeaderInput): Record<string, string>;
1276
1905
  snapshot(namespace?: string): NamespaceSnapshot;
1277
1906
  restore(snapshot: NamespaceSnapshot, namespace?: string): void;
1278
1907
  /** Capture the current branch. Mutating HTTP calls do this automatically. */
@@ -1534,6 +2163,8 @@ type BedrockRuntimeOptions = {
1534
2163
  seed?: number | string;
1535
2164
  adminPrefix?: string;
1536
2165
  adminKey?: string;
2166
+ /** Admin controls to boot with: clock, latency, faults, seed, a starting snapshot. */
2167
+ adminControls?: MockControls;
1537
2168
  onLog?: (entry: RequestLog) => void;
1538
2169
  settings?: Partial<Settings>;
1539
2170
  /** Scripts every namespace starts with (and returns to on reset). */