@crvouga/mockingbird-service-aws 0.1.0 → 0.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/cli.js CHANGED
@@ -3,9 +3,9 @@ import {
3
3
  runCli,
4
4
  serveCommand,
5
5
  serveTarget
6
- } from "./chunk-27QTGSE7.js";
7
- import "./chunk-NG4GI7NA.js";
8
- import "./chunk-M73LWCCP.js";
6
+ } from "./chunk-PPVNDNY7.js";
7
+ import "./chunk-LQOH4S7Z.js";
8
+ import "./chunk-6Z2MR3PO.js";
9
9
 
10
10
  // src/cli.ts
11
11
  var code = await runCli(
@@ -0,0 +1,21 @@
1
+ import {
2
+ createHash,
3
+ createHmac,
4
+ random,
5
+ randomBytes,
6
+ randomUUID,
7
+ timingSafeEqual,
8
+ useRandom,
9
+ withRandom
10
+ } from "./chunk-6Z2MR3PO.js";
11
+ export {
12
+ createHash,
13
+ createHmac,
14
+ random,
15
+ randomBytes,
16
+ randomUUID,
17
+ timingSafeEqual,
18
+ useRandom,
19
+ withRandom
20
+ };
21
+ //# sourceMappingURL=crypto-II2ETGQQ.js.map
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  randomUUID
3
- } from "./chunk-M73LWCCP.js";
3
+ } from "./chunk-6Z2MR3PO.js";
4
4
 
5
5
  // ../../http/provider/dist/vendor/clerk/helpers.js
6
6
  function generateClerkId(prefix) {
@@ -83,4 +83,4 @@ export {
83
83
  userDisplayName
84
84
  };
85
85
  /*! Adapted from vercel-labs/emulate (Apache-2.0), modified for Mockingbird. See port.json, LICENSE_EMULATE and THIRD_PARTY_NOTICES.md. */
86
- //# sourceMappingURL=helpers-BMHFVPFA.js.map
86
+ //# sourceMappingURL=helpers-5D4ROPWG.js.map
package/dist/index.d.ts CHANGED
@@ -404,6 +404,11 @@ type ProviderOptions = APIOptions & {
404
404
  fallbackUser?: AuthFallback;
405
405
  publicNamespace?: string;
406
406
  adminPrefix?: string;
407
+ /**
408
+ * A seeded stream of `[0, 1)` that ids and tokens are minted from, so a run replays from
409
+ * its seed. Default: the platform's randomness.
410
+ */
411
+ random?: () => number;
407
412
  };
408
413
  /** Portable vendor API backed by the shared namespace; it owns no separate history or listener. */
409
414
  declare class ProviderAPI {
@@ -938,7 +943,7 @@ type ClockState = {
938
943
  now: number;
939
944
  /** True while time does not advance on its own. */
940
945
  frozen: boolean;
941
- /** Milliseconds this clock adds to its underlying source. */
946
+ /** Milliseconds a running clock adds to its underlying source. `0` while frozen. */
942
947
  offsetMs: number;
943
948
  };
944
949
  type Clock = {
@@ -974,7 +979,10 @@ type Rng = {
974
979
  state(): number;
975
980
  /** Restore a state previously returned by {@link state}. */
976
981
  setState(state: number): void;
977
- seed: number;
982
+ /** Restart the stream from a new seed. `reset` then returns to this seed. */
983
+ reseed(seed: number | string): void;
984
+ /** The seed the stream currently starts from. */
985
+ readonly seed: number;
978
986
  };
979
987
 
980
988
  /**
@@ -983,44 +991,83 @@ type Rng = {
983
991
  * This is how a suite reaches the vendor's failure modes without the vendor: the
984
992
  * quota error that only appears when a shared sandbox is full, the 429 that only
985
993
  * appears under load, the 5xx that proves a retry path works.
994
+ *
995
+ * A rule has three parts. What it **matches** (`operationId`, `method`, `path`, …), **when**
996
+ * it fires among the matching requests (`after`, `every`, `count`, `rate`, `from`, `until`),
997
+ * and what it **does** (`status`, `delay`, `timeout`, `drop`, `truncate`, `effect`).
986
998
  */
987
999
  type FaultRule = {
988
- /** Stable id, so a suite can retire exactly the rule it added. */
1000
+ /** Stable id, so a suite can retire exactly the rule it added. Unique within a namespace. */
989
1001
  id: string;
990
1002
  /** Fault only this operation. Omit to match every operation. */
991
1003
  operationId?: string;
992
1004
  /** Fault only this HTTP method, case-insensitive. Omit to match every method. */
993
1005
  method?: string;
1006
+ /** Fault only this exact path. */
1007
+ path?: string;
994
1008
  /** Fault only paths starting with this prefix. Omit to match every path. */
995
1009
  pathPrefix?: string;
1010
+ /** Fault only paths matching this regular expression (JavaScript syntax, unanchored). */
1011
+ pathPattern?: string;
1012
+ /** Fault only requests carrying these headers. `"*"` matches any value. */
1013
+ requestHeaders?: Record<string, string>;
1014
+ /** Fault only requests carrying these query parameters. `"*"` matches any value. */
1015
+ query?: Record<string, string>;
996
1016
  /**
997
1017
  * Fault only this namespace. Omit (or `"*"`) to fault every namespace — which is what
998
1018
  * an in-process caller usually wants, and what a parallel worker usually does not:
999
1019
  * rules added through `POST /__admin/faults` default to the calling namespace.
1000
1020
  */
1001
1021
  namespace?: string;
1022
+ /** Let this many matching requests through first. */
1023
+ after?: number;
1024
+ /** Then fault only every nth matching request: `3` faults the 3rd, 6th, 9th. */
1025
+ every?: number;
1026
+ /** Retire the rule after this many faults. Omit to keep it until removed. */
1027
+ count?: number;
1028
+ /** Fault this fraction of the remaining requests, `0`–`1`, drawn from the seed. Default `1`. */
1029
+ rate?: number;
1002
1030
  /**
1003
- * Status of the injected response. Omit for a rule that only delays (`delayMs` /
1004
- * `latencyMs`), only drops the connection (`drop`), or only switches on an `effect`:
1005
- * the request then still reaches the service.
1031
+ * Fault only from this instant on the namespace clock. A duration (`"5m"`) counts from the
1032
+ * clock when the rule was added. Listed as epoch ms.
1033
+ */
1034
+ from?: Instant | Duration;
1035
+ /** Stop faulting at this instant on the namespace clock. A duration counts from when added. */
1036
+ until?: Instant | Duration;
1037
+ /**
1038
+ * Status of the injected response. Omit for a rule that only delays, times out, drops,
1039
+ * truncates, or switches on an `effect`: the request then still reaches the service.
1006
1040
  */
1007
1041
  status?: number;
1008
1042
  /** Response body, serialized as JSON. A string is sent as-is. */
1009
1043
  body?: unknown;
1044
+ /** Response headers. */
1010
1045
  headers?: Record<string, string>;
1011
- /** Retire the rule after this many faults. Omit to keep it until removed. */
1012
- count?: number;
1013
- /** Fault this fraction of matching requests, `0`–`1`. Default `1`. */
1014
- rate?: number;
1015
- /** Hold the response back this long, to exercise timeouts. */
1046
+ /** Hold the response back this long. Listed as `delayMs`. */
1047
+ delay?: Duration;
1048
+ /** `delay`, in milliseconds. */
1016
1049
  delayMs?: number;
1017
1050
  /** Alias of `delayMs`. */
1018
1051
  latencyMs?: number;
1052
+ /** Extra seeded delay in `[0, jitter]`. Listed as `jitterMs`. */
1053
+ jitter?: Duration;
1054
+ jitterMs?: number;
1055
+ /**
1056
+ * Never answer: hold the request this long, then drop the connection. Listed as
1057
+ * `timeoutMs`. With virtual time the wait is spent on the mock clock.
1058
+ */
1059
+ timeout?: Duration;
1060
+ timeoutMs?: number;
1019
1061
  /**
1020
1062
  * Drop the connection instead of answering: an in-process `fetch` rejects with a
1021
1063
  * `TypeError`, and a served mock destroys the socket. Models "unknown outcome" failures.
1022
1064
  */
1023
1065
  drop?: boolean;
1066
+ /**
1067
+ * Cut the response body off after this many bytes: the status and headers arrive, then
1068
+ * the connection dies mid-body.
1069
+ */
1070
+ truncate?: number;
1024
1071
  /**
1025
1072
  * A named service behaviour to switch on for the matching request instead of (or
1026
1073
  * before) a canned response, e.g. `created_but_500` or `numeric_tracking_id`. Services
@@ -1029,8 +1076,8 @@ type FaultRule = {
1029
1076
  effect?: string;
1030
1077
  /** Parameters for `effect`. */
1031
1078
  params?: Record<string, unknown>;
1032
- /** From the preset this rule was expanded from, if any. */
1033
- preset?: string;
1079
+ /** The preset this rule was expanded from, if any. */
1080
+ fromPreset?: string;
1034
1081
  };
1035
1082
  /** A fault that fired for one request. */
1036
1083
  type FaultHit = {
@@ -1038,6 +1085,10 @@ type FaultHit = {
1038
1085
  /** The injected response; absent when the rule only delays, drops, or sets an effect. */
1039
1086
  response?: Response;
1040
1087
  drop?: boolean;
1088
+ /** Set with `drop` when the rule held the request for its `timeout` first. */
1089
+ timeout?: boolean;
1090
+ /** Bytes of response body to let through before the connection dies. */
1091
+ truncate?: number;
1041
1092
  effect?: {
1042
1093
  name: string;
1043
1094
  params: Record<string, unknown>;
@@ -1062,38 +1113,202 @@ type FaultCandidate = {
1062
1113
  method: string;
1063
1114
  path: string;
1064
1115
  namespace: string;
1116
+ /** Request headers and query, for rules that match on them. */
1117
+ headers?: Headers;
1118
+ query?: URLSearchParams;
1119
+ /** The namespace clock, for `from` / `until`. Rules with a window are skipped without it. */
1120
+ now?: number;
1121
+ /** How to spend a delay for this request. Default: the registry's own sleep. */
1122
+ wait?: (ms: number) => Promise<void>;
1123
+ };
1124
+ /** A stored rule and how often it was consulted. */
1125
+ type FaultListing = FaultRule & {
1126
+ /** Faults left before the rule retires. `null` when it has no `count`. */
1127
+ remaining: number | null;
1128
+ /** Times the rule faulted a request. */
1129
+ hits: number;
1130
+ /** Requests that matched the rule, faulted or not. */
1131
+ seen: number;
1132
+ };
1133
+ /** A namespace's own rules, with their counters, in the order they are tried. */
1134
+ type FaultSnapshot = {
1135
+ /**
1136
+ * `position` is how many `"*"` rules are tried before the rule, which is what its place
1137
+ * in the order means to a request and holds in any process.
1138
+ */
1139
+ rules: (FaultListing & {
1140
+ position?: number;
1141
+ })[];
1142
+ /** How many `fault_<n>` ids the namespace has handed out. */
1143
+ nextId?: number;
1065
1144
  };
1066
1145
  type FaultRegistry = {
1067
- isolateNamespaces(): void;
1068
- snapshot(namespace: string): {
1069
- rules: (FaultRule & {
1070
- remaining: number | null;
1071
- hits: number;
1072
- position: number;
1073
- })[];
1074
- rngState: number;
1075
- };
1146
+ snapshot(namespace: string): FaultSnapshot;
1147
+ /** Add a rule, or replace the rule with the same id in the same namespace. */
1076
1148
  add(rule: FaultRule): FaultRule;
1077
- list(): (FaultRule & {
1078
- remaining: number | null;
1079
- hits: number;
1080
- })[];
1081
- remove(id: string): boolean;
1082
- clear(): void;
1083
- restore(namespace: string, state: {
1084
- rules: (FaultRule & {
1085
- remaining: number | null;
1086
- hits: number;
1087
- position: number;
1088
- })[];
1089
- rngState: number;
1090
- }): void;
1149
+ /** The next unused `fault_<n>` id in `namespace`. */
1150
+ nextId(namespace: string): string;
1151
+ /** Every rule, or the rules a namespace's requests can hit: its own and the global ones. */
1152
+ list(namespace?: string): FaultListing[];
1153
+ get(id: string, namespace?: string): FaultListing | undefined;
1154
+ /** Remove a rule by id: from `namespace` (its own, then a global one), or wherever it is. */
1155
+ remove(id: string, namespace?: string): boolean;
1156
+ /** Remove every rule, or one namespace's own rules. */
1157
+ clear(namespace?: string): void;
1158
+ /** Replace a namespace's own rules with a snapshot's, wherever the snapshot was taken. */
1159
+ restore(namespace: string, state: FaultSnapshot): void;
1091
1160
  /**
1092
1161
  * Every fault this request should get, in rule order, stopping at the first that answers
1093
1162
  * or drops (effect-only and delay-only rules let later rules match too). Consumes one of
1094
1163
  * each matching rule's remaining uses.
1095
1164
  */
1096
1165
  take(candidate: FaultCandidate): Promise<FaultHit[]>;
1166
+ /**
1167
+ * Fire these rules at one request without storing them: no matching, no schedule, in order,
1168
+ * stopping at the first that answers or drops. Jitter draws from the namespace's stream.
1169
+ */
1170
+ fire(rules: readonly FaultRule[], candidate: FaultCandidate): Promise<FaultHit[]>;
1171
+ };
1172
+
1173
+ /**
1174
+ * The admin controls every mock shares, as one document.
1175
+ *
1176
+ * The same shape is accepted in three places, and means the same thing in each:
1177
+ *
1178
+ * - at boot: `createRuntime({ adminControls })`, `serve --admin-controls`,
1179
+ * `MOCKINGBIRD_ADMIN_CONTROLS`
1180
+ * - over HTTP: `PUT /__admin/controls`
1181
+ * - per request: the `x-mockingbird-*` headers in {@link CONTROL_HEADERS}
1182
+ *
1183
+ * Every control is deterministic: given the same seed, clock and requests, a mock answers
1184
+ * the same bytes. Nothing here reads the wall clock or `Math.random`.
1185
+ */
1186
+ /** Milliseconds, or a string like `"250ms"`, `"2s"`, `"15m"`, `"1h"`, `"3d"`. */
1187
+ type Duration = number | string;
1188
+ /** Epoch milliseconds, or an ISO-8601 string. */
1189
+ type Instant = number | string;
1190
+ type ClockControls = {
1191
+ /** Move the clock to this instant. */
1192
+ now?: Instant;
1193
+ /** Stop time. A frozen clock moves only when told to, so timestamps replay exactly. */
1194
+ frozen?: boolean;
1195
+ /**
1196
+ * Step the clock forward by this much before every vendor request. With a frozen clock
1197
+ * each request still gets its own, reproducible timestamp.
1198
+ */
1199
+ autoAdvance?: Duration;
1200
+ };
1201
+ /** How long a response takes: a fixed delay plus seeded jitter in `[0, jitter]`. */
1202
+ type LatencyRuleInput = {
1203
+ delay?: Duration;
1204
+ jitter?: Duration;
1205
+ };
1206
+ type LatencyControls = LatencyRuleInput & {
1207
+ /** Per-operation overrides, keyed by operationId. A bare duration is its `delay`. */
1208
+ operations?: Record<string, Duration | LatencyRuleInput>;
1209
+ };
1210
+ /** A fault to add: a rule (the id is assigned when omitted), or a named preset with overrides. */
1211
+ type FaultInput = (Omit<FaultRule, "id"> & {
1212
+ id?: string;
1213
+ }) | ({
1214
+ preset: string;
1215
+ } & Partial<FaultRule>);
1216
+ /** Identifies a {@link SnapshotDocument}. */
1217
+ declare const SNAPSHOT_FORMAT = "mockingbird.snapshot/v1";
1218
+ /**
1219
+ * A namespace, as portable JSON: what `GET /__admin/snapshots/:id` returns and what
1220
+ * `PUT /__admin/snapshots/:id` and the boot `snapshot` control accept. Only `format` and
1221
+ * `records` are required, so a hand-written seed file is a valid snapshot.
1222
+ */
1223
+ type SnapshotDocument = {
1224
+ format: typeof SNAPSHOT_FORMAT;
1225
+ /** The service that wrote it. A snapshot is rejected by any other service. */
1226
+ service?: string;
1227
+ /**
1228
+ * Stored rows. `seq` orders a collection; omitted, rows keep their listed order. `raw` is
1229
+ * the stored text of a row that is not a plain record, and replaces `value` when present.
1230
+ */
1231
+ records: {
1232
+ collection: string;
1233
+ id: string;
1234
+ seq?: number;
1235
+ value?: unknown;
1236
+ raw?: string;
1237
+ }[];
1238
+ /** Id counters, so the next generated id continues where the snapshot left off. */
1239
+ sequences?: {
1240
+ name: string;
1241
+ kind: string;
1242
+ value: number;
1243
+ }[];
1244
+ clock?: {
1245
+ now: number;
1246
+ frozen: boolean;
1247
+ autoAdvanceMs?: number;
1248
+ };
1249
+ seed?: number | string;
1250
+ /** Positions of the seeded random streams. */
1251
+ rng?: {
1252
+ state: number;
1253
+ faults?: number;
1254
+ latency?: number;
1255
+ };
1256
+ faults?: unknown;
1257
+ latency?: unknown;
1258
+ virtualTime?: boolean;
1259
+ /** Quiescent webhook endpoints, delivery history and fault state. Contains private configuration. */
1260
+ webhooks?: unknown;
1261
+ };
1262
+ /** Controls for one namespace. */
1263
+ type NamespaceControls = {
1264
+ /** Seeds every random choice: fault rates, jitter, and whatever the service invents. */
1265
+ seed?: number | string;
1266
+ clock?: ClockControls;
1267
+ /**
1268
+ * Spend injected waits (latency, fault delays, timeouts) on the mock clock instead of the
1269
+ * wall clock: the request returns at once, the clock has moved, and the journal records
1270
+ * the wait exactly. Default `false`: waits are real, so a client's own timeout can fire.
1271
+ */
1272
+ virtualTime?: boolean;
1273
+ /** Baseline response time for every vendor request. A bare duration is its `delay`. */
1274
+ latency?: Duration | LatencyControls;
1275
+ faults?: readonly FaultInput[];
1276
+ /** Start from this state instead of the service's own seed data. */
1277
+ snapshot?: SnapshotDocument;
1278
+ };
1279
+ /** {@link NamespaceControls} for every namespace, with per-namespace overrides. */
1280
+ type MockControls = NamespaceControls & {
1281
+ /** Vendor credential → namespace, for SDKs that cannot send a namespace header. */
1282
+ credentials?: Record<string, string>;
1283
+ /** Overrides for named namespaces. A key given here replaces the shared value. */
1284
+ namespaces?: Record<string, NamespaceControls>;
1285
+ };
1286
+ /** A latency rule in milliseconds. */
1287
+ type LatencyRule = {
1288
+ delayMs: number;
1289
+ jitterMs: number;
1290
+ };
1291
+ /** Baseline latency for a namespace, normalized. */
1292
+ type LatencyState = LatencyRule & {
1293
+ operations: Record<string, LatencyRule>;
1294
+ };
1295
+ /** What {@link controlHeaders} turns into request headers. */
1296
+ type ControlHeaderInput = {
1297
+ namespace?: string;
1298
+ adminKey?: string;
1299
+ branch?: string;
1300
+ at?: string;
1301
+ reset?: boolean;
1302
+ restore?: string;
1303
+ seed?: number | string;
1304
+ time?: Instant | Date;
1305
+ advance?: Duration;
1306
+ virtualTime?: boolean;
1307
+ delay?: Duration;
1308
+ timeout?: Duration;
1309
+ /** A status, `"drop"`, a preset name, or a fault rule. */
1310
+ fault?: number | string | Record<string, unknown>;
1311
+ snapshot?: string;
1097
1312
  };
1098
1313
 
1099
1314
  /**
@@ -1133,6 +1348,8 @@ type RequestLog = {
1133
1348
  unmatched: boolean;
1134
1349
  /** Set when a fault rule produced the response. */
1135
1350
  faultId?: string;
1351
+ /** Milliseconds of injected wait: latency, fault delays and timeouts. Absent when none. */
1352
+ delayMs?: number;
1136
1353
  /** Resource ids the handler touched (`userId`, `orderId`, …), when the service reports them. */
1137
1354
  ids?: Record<string, string>;
1138
1355
  /** Set when the service created a resource the request referred to but that did not exist. */
@@ -1178,6 +1395,12 @@ type JournalQuery = {
1178
1395
  /** Only this namespace. Omit for every namespace, oldest first across all of them. */
1179
1396
  namespace?: string;
1180
1397
  operationId?: string;
1398
+ /** Only this HTTP method, case-insensitive. */
1399
+ method?: string;
1400
+ /** Only this exact path. */
1401
+ path?: string;
1402
+ /** Only requests this fault rule answered or shaped. */
1403
+ faultId?: string;
1181
1404
  status?: number;
1182
1405
  /** Only entries at or after this instant (epoch ms). */
1183
1406
  since?: number;
@@ -1192,6 +1415,38 @@ type Journal = {
1192
1415
  clear(namespace?: string): void;
1193
1416
  };
1194
1417
 
1418
+ /**
1419
+ * Baseline response time, per namespace: how long every vendor request takes before any
1420
+ * fault is considered. Jitter draws from a stream the caller owns, one per namespace and
1421
+ * separate from the fault stream, so adding latency never shifts which requests a `rate`
1422
+ * fault hits.
1423
+ */
1424
+ type LatencyRegistry = {
1425
+ get(namespace: string): LatencyState;
1426
+ set(namespace: string, state: LatencyState): LatencyState;
1427
+ /** Remove one namespace's latency, or every namespace's. */
1428
+ clear(namespace?: string): void;
1429
+ /** Milliseconds this request waits. Draws jitter, so call it once per request. */
1430
+ take(namespace: string, operationId: string | undefined): number;
1431
+ };
1432
+
1433
+ /** Clock state as the admin API reports it. */
1434
+ type ControlClock = ClockState & {
1435
+ /** `now`, as ISO-8601. */
1436
+ iso: string;
1437
+ /** Milliseconds the clock steps before every vendor request. */
1438
+ autoAdvanceMs: number;
1439
+ };
1440
+ /** One namespace's controls: the body of `GET /__admin/controls`. */
1441
+ type ControlState = {
1442
+ namespace: string;
1443
+ seed: number | string;
1444
+ clock: ControlClock;
1445
+ virtualTime: boolean;
1446
+ latency: LatencyState;
1447
+ faults: FaultListing[];
1448
+ };
1449
+
1195
1450
  type AdminRequest = {
1196
1451
  request: Request;
1197
1452
  url: URL;
@@ -1208,6 +1463,17 @@ type AdminRoute = (request: AdminRequest) => Response | Promise<Response>;
1208
1463
  * `:param` segments — e.g. `"POST /orders/:id/transition"`.
1209
1464
  */
1210
1465
  type AdminRoutes = Record<string, AdminRoute>;
1466
+ /** What `GET /__admin/snapshots` lists for each snapshot. */
1467
+ type SnapshotInfo = {
1468
+ id: string;
1469
+ namespace: string;
1470
+ /** Stored rows in the snapshot. */
1471
+ records: number;
1472
+ /** The namespace clock when it was taken, epoch ms. */
1473
+ at: number;
1474
+ /** Whether `GET /snapshots/:id` can return it as a {@link SnapshotDocument}. */
1475
+ portable: boolean;
1476
+ };
1211
1477
 
1212
1478
  /** Credential → namespace mapping behind `PUT /__admin/credentials`. */
1213
1479
  type CredentialRegistry = {
@@ -1221,6 +1487,8 @@ type CredentialRegistry = {
1221
1487
  }[];
1222
1488
  };
1223
1489
 
1490
+ type OwnedTransport = (request: Request, namespace: string, send: typeof fetch) => Promise<Response>;
1491
+
1224
1492
  /**
1225
1493
  * A point-in-time copy of everything a service namespace holds.
1226
1494
  *
@@ -1407,8 +1675,16 @@ type PublishInput = {
1407
1675
  id?: string;
1408
1676
  };
1409
1677
  type WebhookHub = {
1678
+ observeDeliveries(listener: (event: {
1679
+ namespace: string;
1680
+ state: string;
1681
+ deliveryId: string;
1682
+ }) => void): () => void;
1683
+ setTransportPolicy(policy: OwnedTransport): void;
1410
1684
  pending(namespace: string): number;
1411
1685
  snapshot(namespace: string): unknown;
1686
+ exportSnapshot(handle: unknown): unknown;
1687
+ importSnapshot(namespace: string, document: unknown): unknown;
1412
1688
  restore(namespace: string, snapshot: unknown): void;
1413
1689
  publish(input: PublishInput): WebhookMessage;
1414
1690
  /** Replace a namespace's own endpoints (`PUT /__admin/webhook-endpoints`). */
@@ -1421,7 +1697,7 @@ type WebhookHub = {
1421
1697
  /** Run every pending retry (and release held reordered messages) now, and every retry those attempts schedule, until nothing is pending. */
1422
1698
  flush(): Promise<void>;
1423
1699
  /** Resolve once nothing is in flight. */
1424
- idle(): Promise<void>;
1700
+ idle(namespace?: string): Promise<void>;
1425
1701
  fault(namespace: string, fault: WebhookFault): void;
1426
1702
  clear(namespace?: string): void;
1427
1703
  };
@@ -1452,14 +1728,26 @@ type RuntimeOptions<T extends ServiceInstance> = {
1452
1728
  sqlite?: SqliteClient;
1453
1729
  /** Defaults to a live clock over `Date.now`. */
1454
1730
  clock?: Clock;
1455
- /** Seeds every random choice the runtime makes (fault rates). Default `0`. */
1731
+ /** Seeds every random choice the runtime makes (fault rates, jitter). Default `0`. */
1456
1732
  seed?: number | string;
1733
+ /**
1734
+ * Admin controls to boot with: clock, latency, faults, a starting snapshot, credential
1735
+ * mappings and per-namespace overrides. `reset` returns a namespace to exactly this.
1736
+ */
1737
+ adminControls?: MockControls;
1457
1738
  /** Extra `GET /__admin/health` fields, such as the loaded corpus version. */
1458
1739
  describe?: () => Record<string, unknown>;
1459
1740
  /** Service-specific admin routes, given the runtime so they can reach any namespace. */
1460
1741
  admin?: (runtime: ServiceRuntime<T>) => AdminRoutes;
1461
1742
  /** Reserved tree for every internal HTTP endpoint, UI and namespace carrier. Default /__admin. */
1462
1743
  adminPrefix?: string;
1744
+ /**
1745
+ * A namespace's clock was moved — by `/__admin/clock`, a header, a restore, a reset, or a
1746
+ * wait spent in virtual time. Run whatever the service schedules by that clock, so what
1747
+ * came due is seen at once and not on the next request. Moving the base clock in process
1748
+ * (`runtime.clock`) is the caller's own doing and is not reported here.
1749
+ */
1750
+ onClockChange?: (namespace: string) => void;
1463
1751
  /** Invalidate transient handles before replacing an existing instance's stored state. */
1464
1752
  beforeRestore?: (instance: T) => void;
1465
1753
  /** Require this value in `x-mockingbird-admin-key` on admin data routes. */
@@ -1477,7 +1765,10 @@ type RuntimeOptions<T extends ServiceInstance> = {
1477
1765
  * `sigV4AccessKeyId`.
1478
1766
  */
1479
1767
  credential?: (request: Request) => string | undefined;
1480
- /** Named faults, switched on with `POST /__admin/faults {"preset": "<name>"}`. */
1768
+ /**
1769
+ * Named faults, switched on with `POST /__admin/faults {"preset": "<name>"}`. They join the
1770
+ * standard presets every mock has; one with a standard name replaces it.
1771
+ */
1481
1772
  presets?: Record<string, FaultPreset>;
1482
1773
  /** Outbound webhooks; adds the `/__admin/webhooks*` routes and clears on reset. */
1483
1774
  webhooks?: WebhookHub;
@@ -1500,11 +1791,15 @@ type RuntimeOptions<T extends ServiceInstance> = {
1500
1791
  type RuntimeIO = {
1501
1792
  wallNow(): number;
1502
1793
  monotonicNow(): number;
1503
- sleep(ms: number): Promise<void>;
1794
+ /** Wait on the wall clock. Rejects with the signal's reason when it aborts first. */
1795
+ sleep(ms: number, signal?: AbortSignal): Promise<void>;
1504
1796
  };
1505
1797
  type ServiceTimelineState = Readonly<{
1506
1798
  snapshot: NamespaceSnapshot;
1507
- clock: Readonly<ReturnType<Clock["state"]>>;
1799
+ /** `pinned`: the namespace's clock was frozen itself, not just following a frozen base. */
1800
+ clock: Readonly<ClockState & {
1801
+ pinned?: boolean;
1802
+ }>;
1508
1803
  rngState: number;
1509
1804
  }>;
1510
1805
  type ServiceCheckpoint = Checkpoint<ServiceTimelineState>;
@@ -1517,27 +1812,63 @@ type ServiceRuntime<T extends ServiceInstance> = FetchAPI & {
1517
1812
  readonly sqlite: SqliteClient;
1518
1813
  readonly clock: Clock;
1519
1814
  readonly faults: FaultRegistry;
1815
+ /** Baseline response time per namespace. */
1816
+ readonly latency: LatencyRegistry;
1520
1817
  readonly metrics: Metrics;
1521
1818
  readonly journal: Journal;
1522
1819
  readonly rng: Rng;
1523
1820
  readonly credentials: CredentialRegistry;
1524
1821
  /** The webhook hub, when the service has outbound webhooks. */
1525
1822
  readonly webhooks: WebhookHub | undefined;
1526
- /** Enable independent namespace clocks and PRNGs before serving a fleet. */
1527
- isolateNamespaces(): void;
1823
+ /**
1824
+ * A namespace's clock. Each follows the base clock, {@link ServiceRuntime.clock}, with an
1825
+ * offset and a freeze of its own, so moving one never moves another.
1826
+ */
1528
1827
  namespaceClock(namespace?: string): Clock;
1529
1828
  namespaceOf(request: Request): string;
1530
1829
  /** Opaque in-process checkpoint including records, controls and webhook history. */
1531
1830
  fleetSnapshot(namespace: string): object;
1532
1831
  fleetRestore(snapshot: unknown, namespace: string): void;
1832
+ fleetExport(snapshot: unknown): SnapshotDocument;
1833
+ fleetImport(namespace: string, document: unknown): object;
1533
1834
  /** Expand a named preset into fault rules (and webhook faults) for `namespace`. */
1534
1835
  applyPreset(name: string, namespace?: string, overrides?: Partial<FaultRule>): FaultRule[];
1535
1836
  /** The instance behind `namespace` (the default one when omitted), created on first use. */
1536
1837
  instance(namespace?: string): T;
1537
1838
  /** Public names of every namespace created so far. */
1538
1839
  namespaces(): string[];
1539
- /** Reset one namespace, or every namespace with `"*"`. */
1840
+ /** Return one namespace to its boot state, or every namespace with `"*"`. */
1540
1841
  reset(namespace?: string): Promise<void>;
1842
+ /** Reset a namespace and forget it, releasing everything it held. */
1843
+ dropNamespace(namespace: string): Promise<void>;
1844
+ /** A namespace's controls: seed, clock, virtual time, latency, faults and snapshots. */
1845
+ controls(namespace?: string): ControlState & {
1846
+ snapshots: SnapshotInfo[];
1847
+ };
1848
+ /** Apply a control document to a namespace. A given key replaces that control. */
1849
+ configure(controls: NamespaceControls, namespace?: string): ControlState & {
1850
+ snapshots: SnapshotInfo[];
1851
+ };
1852
+ /** Named snapshots of a namespace: records, clock, random streams, faults and latency. */
1853
+ readonly snapshots: {
1854
+ /** Capture the namespace now. Reusing a name replaces that snapshot. */
1855
+ create(options?: {
1856
+ name?: string;
1857
+ namespace?: string;
1858
+ }): SnapshotInfo;
1859
+ list(namespace?: string): SnapshotInfo[];
1860
+ /** The snapshot as portable JSON, to commit beside a suite or boot another mock from. */
1861
+ export(id: string, namespace?: string): SnapshotDocument;
1862
+ /** Store a document as a snapshot without restoring it. */
1863
+ import(document: SnapshotDocument, options?: {
1864
+ name?: string;
1865
+ namespace?: string;
1866
+ }): SnapshotInfo;
1867
+ restore(id: string, namespace?: string): void;
1868
+ delete(id: string, namespace?: string): boolean;
1869
+ };
1870
+ /** Request headers that carry controls, checked: spread them into a `fetch` or an SDK's defaults. */
1871
+ headers(input: ControlHeaderInput): Record<string, string>;
1541
1872
  snapshot(namespace?: string): NamespaceSnapshot;
1542
1873
  restore(snapshot: NamespaceSnapshot, namespace?: string): void;
1543
1874
  /** Capture the current branch. Mutating HTTP calls do this automatically. */
@@ -1558,7 +1889,7 @@ type ServiceRuntime<T extends ServiceInstance> = FetchAPI & {
1558
1889
  state(namespace?: string): StateView;
1559
1890
  };
1560
1891
 
1561
- type AwsRuntimeOptions = Pick<RuntimeOptions<AwsAPI>, "sqlite" | "clock" | "seed" | "adminPrefix" | "adminKey" | "onLog" | "journalSize" | "maxCheckpoints"> & Pick<AwsAPIOptions, "fixtures" | "baseUrl" | "tokens">;
1892
+ type AwsRuntimeOptions = Pick<RuntimeOptions<AwsAPI>, "sqlite" | "clock" | "seed" | "adminPrefix" | "adminKey" | "adminControls" | "onLog" | "journalSize" | "maxCheckpoints"> & Pick<AwsAPIOptions, "fixtures" | "baseUrl" | "tokens">;
1562
1893
  type AwsRuntime = ServiceRuntime<AwsAPI>;
1563
1894
  declare function createRuntime(options?: AwsRuntimeOptions): AwsRuntime;
1564
1895
 
package/dist/index.js CHANGED
@@ -5,8 +5,8 @@ import {
5
5
  document,
6
6
  operationIds,
7
7
  supportedOperationIds
8
- } from "./chunk-NG4GI7NA.js";
9
- import "./chunk-M73LWCCP.js";
8
+ } from "./chunk-LQOH4S7Z.js";
9
+ import "./chunk-6Z2MR3PO.js";
10
10
  export {
11
11
  AWS_NAMESPACE,
12
12
  AwsAPI,