@crvouga/mockingbird-service-aws 0.1.0 → 0.2.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/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,200 @@ 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
+ };
1260
+ /** Controls for one namespace. */
1261
+ type NamespaceControls = {
1262
+ /** Seeds every random choice: fault rates, jitter, and whatever the service invents. */
1263
+ seed?: number | string;
1264
+ clock?: ClockControls;
1265
+ /**
1266
+ * Spend injected waits (latency, fault delays, timeouts) on the mock clock instead of the
1267
+ * wall clock: the request returns at once, the clock has moved, and the journal records
1268
+ * the wait exactly. Default `false`: waits are real, so a client's own timeout can fire.
1269
+ */
1270
+ virtualTime?: boolean;
1271
+ /** Baseline response time for every vendor request. A bare duration is its `delay`. */
1272
+ latency?: Duration | LatencyControls;
1273
+ faults?: readonly FaultInput[];
1274
+ /** Start from this state instead of the service's own seed data. */
1275
+ snapshot?: SnapshotDocument;
1276
+ };
1277
+ /** {@link NamespaceControls} for every namespace, with per-namespace overrides. */
1278
+ type MockControls = NamespaceControls & {
1279
+ /** Vendor credential → namespace, for SDKs that cannot send a namespace header. */
1280
+ credentials?: Record<string, string>;
1281
+ /** Overrides for named namespaces. A key given here replaces the shared value. */
1282
+ namespaces?: Record<string, NamespaceControls>;
1283
+ };
1284
+ /** A latency rule in milliseconds. */
1285
+ type LatencyRule = {
1286
+ delayMs: number;
1287
+ jitterMs: number;
1288
+ };
1289
+ /** Baseline latency for a namespace, normalized. */
1290
+ type LatencyState = LatencyRule & {
1291
+ operations: Record<string, LatencyRule>;
1292
+ };
1293
+ /** What {@link controlHeaders} turns into request headers. */
1294
+ type ControlHeaderInput = {
1295
+ namespace?: string;
1296
+ adminKey?: string;
1297
+ branch?: string;
1298
+ at?: string;
1299
+ reset?: boolean;
1300
+ restore?: string;
1301
+ seed?: number | string;
1302
+ time?: Instant | Date;
1303
+ advance?: Duration;
1304
+ virtualTime?: boolean;
1305
+ delay?: Duration;
1306
+ timeout?: Duration;
1307
+ /** A status, `"drop"`, a preset name, or a fault rule. */
1308
+ fault?: number | string | Record<string, unknown>;
1309
+ snapshot?: string;
1097
1310
  };
1098
1311
 
1099
1312
  /**
@@ -1133,6 +1346,8 @@ type RequestLog = {
1133
1346
  unmatched: boolean;
1134
1347
  /** Set when a fault rule produced the response. */
1135
1348
  faultId?: string;
1349
+ /** Milliseconds of injected wait: latency, fault delays and timeouts. Absent when none. */
1350
+ delayMs?: number;
1136
1351
  /** Resource ids the handler touched (`userId`, `orderId`, …), when the service reports them. */
1137
1352
  ids?: Record<string, string>;
1138
1353
  /** Set when the service created a resource the request referred to but that did not exist. */
@@ -1178,6 +1393,12 @@ type JournalQuery = {
1178
1393
  /** Only this namespace. Omit for every namespace, oldest first across all of them. */
1179
1394
  namespace?: string;
1180
1395
  operationId?: string;
1396
+ /** Only this HTTP method, case-insensitive. */
1397
+ method?: string;
1398
+ /** Only this exact path. */
1399
+ path?: string;
1400
+ /** Only requests this fault rule answered or shaped. */
1401
+ faultId?: string;
1181
1402
  status?: number;
1182
1403
  /** Only entries at or after this instant (epoch ms). */
1183
1404
  since?: number;
@@ -1192,6 +1413,38 @@ type Journal = {
1192
1413
  clear(namespace?: string): void;
1193
1414
  };
1194
1415
 
1416
+ /**
1417
+ * Baseline response time, per namespace: how long every vendor request takes before any
1418
+ * fault is considered. Jitter draws from a stream the caller owns, one per namespace and
1419
+ * separate from the fault stream, so adding latency never shifts which requests a `rate`
1420
+ * fault hits.
1421
+ */
1422
+ type LatencyRegistry = {
1423
+ get(namespace: string): LatencyState;
1424
+ set(namespace: string, state: LatencyState): LatencyState;
1425
+ /** Remove one namespace's latency, or every namespace's. */
1426
+ clear(namespace?: string): void;
1427
+ /** Milliseconds this request waits. Draws jitter, so call it once per request. */
1428
+ take(namespace: string, operationId: string | undefined): number;
1429
+ };
1430
+
1431
+ /** Clock state as the admin API reports it. */
1432
+ type ControlClock = ClockState & {
1433
+ /** `now`, as ISO-8601. */
1434
+ iso: string;
1435
+ /** Milliseconds the clock steps before every vendor request. */
1436
+ autoAdvanceMs: number;
1437
+ };
1438
+ /** One namespace's controls: the body of `GET /__admin/controls`. */
1439
+ type ControlState = {
1440
+ namespace: string;
1441
+ seed: number | string;
1442
+ clock: ControlClock;
1443
+ virtualTime: boolean;
1444
+ latency: LatencyState;
1445
+ faults: FaultListing[];
1446
+ };
1447
+
1195
1448
  type AdminRequest = {
1196
1449
  request: Request;
1197
1450
  url: URL;
@@ -1208,6 +1461,17 @@ type AdminRoute = (request: AdminRequest) => Response | Promise<Response>;
1208
1461
  * `:param` segments — e.g. `"POST /orders/:id/transition"`.
1209
1462
  */
1210
1463
  type AdminRoutes = Record<string, AdminRoute>;
1464
+ /** What `GET /__admin/snapshots` lists for each snapshot. */
1465
+ type SnapshotInfo = {
1466
+ id: string;
1467
+ namespace: string;
1468
+ /** Stored rows in the snapshot. */
1469
+ records: number;
1470
+ /** The namespace clock when it was taken, epoch ms. */
1471
+ at: number;
1472
+ /** Whether `GET /snapshots/:id` can return it as a {@link SnapshotDocument}. */
1473
+ portable: boolean;
1474
+ };
1211
1475
 
1212
1476
  /** Credential → namespace mapping behind `PUT /__admin/credentials`. */
1213
1477
  type CredentialRegistry = {
@@ -1452,14 +1716,26 @@ type RuntimeOptions<T extends ServiceInstance> = {
1452
1716
  sqlite?: SqliteClient;
1453
1717
  /** Defaults to a live clock over `Date.now`. */
1454
1718
  clock?: Clock;
1455
- /** Seeds every random choice the runtime makes (fault rates). Default `0`. */
1719
+ /** Seeds every random choice the runtime makes (fault rates, jitter). Default `0`. */
1456
1720
  seed?: number | string;
1721
+ /**
1722
+ * Admin controls to boot with: clock, latency, faults, a starting snapshot, credential
1723
+ * mappings and per-namespace overrides. `reset` returns a namespace to exactly this.
1724
+ */
1725
+ adminControls?: MockControls;
1457
1726
  /** Extra `GET /__admin/health` fields, such as the loaded corpus version. */
1458
1727
  describe?: () => Record<string, unknown>;
1459
1728
  /** Service-specific admin routes, given the runtime so they can reach any namespace. */
1460
1729
  admin?: (runtime: ServiceRuntime<T>) => AdminRoutes;
1461
1730
  /** Reserved tree for every internal HTTP endpoint, UI and namespace carrier. Default /__admin. */
1462
1731
  adminPrefix?: string;
1732
+ /**
1733
+ * A namespace's clock was moved — by `/__admin/clock`, a header, a restore, a reset, or a
1734
+ * wait spent in virtual time. Run whatever the service schedules by that clock, so what
1735
+ * came due is seen at once and not on the next request. Moving the base clock in process
1736
+ * (`runtime.clock`) is the caller's own doing and is not reported here.
1737
+ */
1738
+ onClockChange?: (namespace: string) => void;
1463
1739
  /** Invalidate transient handles before replacing an existing instance's stored state. */
1464
1740
  beforeRestore?: (instance: T) => void;
1465
1741
  /** Require this value in `x-mockingbird-admin-key` on admin data routes. */
@@ -1477,7 +1753,10 @@ type RuntimeOptions<T extends ServiceInstance> = {
1477
1753
  * `sigV4AccessKeyId`.
1478
1754
  */
1479
1755
  credential?: (request: Request) => string | undefined;
1480
- /** Named faults, switched on with `POST /__admin/faults {"preset": "<name>"}`. */
1756
+ /**
1757
+ * Named faults, switched on with `POST /__admin/faults {"preset": "<name>"}`. They join the
1758
+ * standard presets every mock has; one with a standard name replaces it.
1759
+ */
1481
1760
  presets?: Record<string, FaultPreset>;
1482
1761
  /** Outbound webhooks; adds the `/__admin/webhooks*` routes and clears on reset. */
1483
1762
  webhooks?: WebhookHub;
@@ -1500,11 +1779,15 @@ type RuntimeOptions<T extends ServiceInstance> = {
1500
1779
  type RuntimeIO = {
1501
1780
  wallNow(): number;
1502
1781
  monotonicNow(): number;
1503
- sleep(ms: number): Promise<void>;
1782
+ /** Wait on the wall clock. Rejects with the signal's reason when it aborts first. */
1783
+ sleep(ms: number, signal?: AbortSignal): Promise<void>;
1504
1784
  };
1505
1785
  type ServiceTimelineState = Readonly<{
1506
1786
  snapshot: NamespaceSnapshot;
1507
- clock: Readonly<ReturnType<Clock["state"]>>;
1787
+ /** `pinned`: the namespace's clock was frozen itself, not just following a frozen base. */
1788
+ clock: Readonly<ClockState & {
1789
+ pinned?: boolean;
1790
+ }>;
1508
1791
  rngState: number;
1509
1792
  }>;
1510
1793
  type ServiceCheckpoint = Checkpoint<ServiceTimelineState>;
@@ -1517,14 +1800,18 @@ type ServiceRuntime<T extends ServiceInstance> = FetchAPI & {
1517
1800
  readonly sqlite: SqliteClient;
1518
1801
  readonly clock: Clock;
1519
1802
  readonly faults: FaultRegistry;
1803
+ /** Baseline response time per namespace. */
1804
+ readonly latency: LatencyRegistry;
1520
1805
  readonly metrics: Metrics;
1521
1806
  readonly journal: Journal;
1522
1807
  readonly rng: Rng;
1523
1808
  readonly credentials: CredentialRegistry;
1524
1809
  /** The webhook hub, when the service has outbound webhooks. */
1525
1810
  readonly webhooks: WebhookHub | undefined;
1526
- /** Enable independent namespace clocks and PRNGs before serving a fleet. */
1527
- isolateNamespaces(): void;
1811
+ /**
1812
+ * A namespace's clock. Each follows the base clock, {@link ServiceRuntime.clock}, with an
1813
+ * offset and a freeze of its own, so moving one never moves another.
1814
+ */
1528
1815
  namespaceClock(namespace?: string): Clock;
1529
1816
  namespaceOf(request: Request): string;
1530
1817
  /** Opaque in-process checkpoint including records, controls and webhook history. */
@@ -1536,8 +1823,38 @@ type ServiceRuntime<T extends ServiceInstance> = FetchAPI & {
1536
1823
  instance(namespace?: string): T;
1537
1824
  /** Public names of every namespace created so far. */
1538
1825
  namespaces(): string[];
1539
- /** Reset one namespace, or every namespace with `"*"`. */
1826
+ /** Return one namespace to its boot state, or every namespace with `"*"`. */
1540
1827
  reset(namespace?: string): Promise<void>;
1828
+ /** Reset a namespace and forget it, releasing everything it held. */
1829
+ dropNamespace(namespace: string): Promise<void>;
1830
+ /** A namespace's controls: seed, clock, virtual time, latency, faults and snapshots. */
1831
+ controls(namespace?: string): ControlState & {
1832
+ snapshots: SnapshotInfo[];
1833
+ };
1834
+ /** Apply a control document to a namespace. A given key replaces that control. */
1835
+ configure(controls: NamespaceControls, namespace?: string): ControlState & {
1836
+ snapshots: SnapshotInfo[];
1837
+ };
1838
+ /** Named snapshots of a namespace: records, clock, random streams, faults and latency. */
1839
+ readonly snapshots: {
1840
+ /** Capture the namespace now. Reusing a name replaces that snapshot. */
1841
+ create(options?: {
1842
+ name?: string;
1843
+ namespace?: string;
1844
+ }): SnapshotInfo;
1845
+ list(namespace?: string): SnapshotInfo[];
1846
+ /** The snapshot as portable JSON, to commit beside a suite or boot another mock from. */
1847
+ export(id: string, namespace?: string): SnapshotDocument;
1848
+ /** Store a document as a snapshot without restoring it. */
1849
+ import(document: SnapshotDocument, options?: {
1850
+ name?: string;
1851
+ namespace?: string;
1852
+ }): SnapshotInfo;
1853
+ restore(id: string, namespace?: string): void;
1854
+ delete(id: string, namespace?: string): boolean;
1855
+ };
1856
+ /** Request headers that carry controls, checked: spread them into a `fetch` or an SDK's defaults. */
1857
+ headers(input: ControlHeaderInput): Record<string, string>;
1541
1858
  snapshot(namespace?: string): NamespaceSnapshot;
1542
1859
  restore(snapshot: NamespaceSnapshot, namespace?: string): void;
1543
1860
  /** Capture the current branch. Mutating HTTP calls do this automatically. */
@@ -1558,7 +1875,7 @@ type ServiceRuntime<T extends ServiceInstance> = FetchAPI & {
1558
1875
  state(namespace?: string): StateView;
1559
1876
  };
1560
1877
 
1561
- type AwsRuntimeOptions = Pick<RuntimeOptions<AwsAPI>, "sqlite" | "clock" | "seed" | "adminPrefix" | "adminKey" | "onLog" | "journalSize" | "maxCheckpoints"> & Pick<AwsAPIOptions, "fixtures" | "baseUrl" | "tokens">;
1878
+ type AwsRuntimeOptions = Pick<RuntimeOptions<AwsAPI>, "sqlite" | "clock" | "seed" | "adminPrefix" | "adminKey" | "adminControls" | "onLog" | "journalSize" | "maxCheckpoints"> & Pick<AwsAPIOptions, "fixtures" | "baseUrl" | "tokens">;
1562
1879
  type AwsRuntime = ServiceRuntime<AwsAPI>;
1563
1880
  declare function createRuntime(options?: AwsRuntimeOptions): AwsRuntime;
1564
1881
 
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-GFJTN44G.js";
9
+ import "./chunk-6Z2MR3PO.js";
10
10
  export {
11
11
  AWS_NAMESPACE,
12
12
  AwsAPI,