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