@crvouga/mockingbird-service-junction 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/CHANGELOG.md +14 -2
- package/DISCOVERY.md +23 -0
- package/README.md +68 -76
- package/dist/chunk-PKEFSWT3.js +12812 -0
- package/dist/chunk-PKEFSWT3.js.map +7 -0
- package/dist/{chunk-SENEZJTT.js → chunk-YDXAOFS2.js} +139 -26
- package/dist/chunk-YDXAOFS2.js.map +7 -0
- package/dist/cli.js +2 -2
- package/dist/index.d.ts +381 -67
- package/dist/index.js +1 -1
- package/dist/server.d.ts +765 -134
- package/dist/server.js +2 -2
- package/package.json +3 -2
- package/dist/chunk-DBNCTIW4.js +0 -10932
- package/dist/chunk-DBNCTIW4.js.map +0 -7
- package/dist/chunk-SENEZJTT.js.map +0 -7
package/dist/index.d.ts
CHANGED
|
@@ -1,33 +1,15 @@
|
|
|
1
1
|
import { Hono } from 'hono';
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
3
|
+
type MountedAPI = FetchAPI$1 & {
|
|
4
|
+
readonly prefix: string;
|
|
5
|
+
GET: FetchHandler;
|
|
6
|
+
POST: FetchHandler;
|
|
7
|
+
PUT: FetchHandler;
|
|
8
|
+
PATCH: FetchHandler;
|
|
9
|
+
DELETE: FetchHandler;
|
|
10
|
+
HEAD: FetchHandler;
|
|
11
|
+
OPTIONS: FetchHandler;
|
|
9
12
|
};
|
|
10
|
-
/**
|
|
11
|
-
* Prepared statement bound to a {@link SqliteClient}.
|
|
12
|
-
*
|
|
13
|
-
* Pass bind values as rest arguments on each call (no sticky `bind()`).
|
|
14
|
-
*/
|
|
15
|
-
interface SqliteStatement$1 {
|
|
16
|
-
run(...params: SqliteValue$1[]): SqliteRunResult$1;
|
|
17
|
-
all<T = Record<string, unknown>>(...params: SqliteValue$1[]): T[];
|
|
18
|
-
get<T = Record<string, unknown>>(...params: SqliteValue$1[]): T | undefined;
|
|
19
|
-
}
|
|
20
|
-
/**
|
|
21
|
-
* Sync SQLite client port owned by Mockingbird.
|
|
22
|
-
*
|
|
23
|
-
* Duck-typed so `@crvouga/mockingbird-service-sqlite` `Database`, better-sqlite3, and wrapped
|
|
24
|
-
* `bun:sqlite` instances all work when they expose this surface.
|
|
25
|
-
*/
|
|
26
|
-
interface SqliteClient$1 {
|
|
27
|
-
exec(sql: string): void;
|
|
28
|
-
prepare(sql: string): SqliteStatement$1;
|
|
29
|
-
transaction<T>(fn: () => T): T;
|
|
30
|
-
}
|
|
31
13
|
|
|
32
14
|
/** A stable identifier for a point in a {@link Timeline}. */
|
|
33
15
|
type CheckpointId = string;
|
|
@@ -118,6 +100,37 @@ declare class Timeline<T> {
|
|
|
118
100
|
interface FetchAPI$1 {
|
|
119
101
|
fetch(request: Request): Promise<Response>;
|
|
120
102
|
}
|
|
103
|
+
/** A bare function form of {@link FetchAPI}, compatible with `Bun.serve`, workerd, and Deno. */
|
|
104
|
+
type FetchHandler = (request: Request) => Promise<Response>;
|
|
105
|
+
|
|
106
|
+
/** Bind values accepted by Mockingbird's SQLite port (matches sqlite-mem / better-sqlite3). */
|
|
107
|
+
type SqliteValue$1 = null | number | bigint | string | Uint8Array | boolean;
|
|
108
|
+
/** Mutation counters returned by {@link SqliteStatement.run}. */
|
|
109
|
+
type SqliteRunResult$1 = {
|
|
110
|
+
changes: number;
|
|
111
|
+
lastInsertRowid: number | bigint;
|
|
112
|
+
};
|
|
113
|
+
/**
|
|
114
|
+
* Prepared statement bound to a {@link SqliteClient}.
|
|
115
|
+
*
|
|
116
|
+
* Pass bind values as rest arguments on each call (no sticky `bind()`).
|
|
117
|
+
*/
|
|
118
|
+
interface SqliteStatement$1 {
|
|
119
|
+
run(...params: SqliteValue$1[]): SqliteRunResult$1;
|
|
120
|
+
all<T = Record<string, unknown>>(...params: SqliteValue$1[]): T[];
|
|
121
|
+
get<T = Record<string, unknown>>(...params: SqliteValue$1[]): T | undefined;
|
|
122
|
+
}
|
|
123
|
+
/**
|
|
124
|
+
* Sync SQLite client port owned by Mockingbird.
|
|
125
|
+
*
|
|
126
|
+
* Duck-typed so `@crvouga/mockingbird-service-sqlite` `Database`, better-sqlite3, and wrapped
|
|
127
|
+
* `bun:sqlite` instances all work when they expose this surface.
|
|
128
|
+
*/
|
|
129
|
+
interface SqliteClient$1 {
|
|
130
|
+
exec(sql: string): void;
|
|
131
|
+
prepare(sql: string): SqliteStatement$1;
|
|
132
|
+
transaction<T>(fn: () => T): T;
|
|
133
|
+
}
|
|
121
134
|
|
|
122
135
|
/** Options every provider constructor accepts. */
|
|
123
136
|
type APIOptions = {
|
|
@@ -144,7 +157,7 @@ type ClockState = {
|
|
|
144
157
|
now: number;
|
|
145
158
|
/** True while time does not advance on its own. */
|
|
146
159
|
frozen: boolean;
|
|
147
|
-
/** Milliseconds
|
|
160
|
+
/** Milliseconds a running clock adds to its underlying source. `0` while frozen. */
|
|
148
161
|
offsetMs: number;
|
|
149
162
|
};
|
|
150
163
|
type Clock = {
|
|
@@ -180,7 +193,10 @@ type Rng = {
|
|
|
180
193
|
state(): number;
|
|
181
194
|
/** Restore a state previously returned by {@link state}. */
|
|
182
195
|
setState(state: number): void;
|
|
183
|
-
seed
|
|
196
|
+
/** Restart the stream from a new seed. `reset` then returns to this seed. */
|
|
197
|
+
reseed(seed: number | string): void;
|
|
198
|
+
/** The seed the stream currently starts from. */
|
|
199
|
+
readonly seed: number;
|
|
184
200
|
};
|
|
185
201
|
|
|
186
202
|
/**
|
|
@@ -189,44 +205,83 @@ type Rng = {
|
|
|
189
205
|
* This is how a suite reaches the vendor's failure modes without the vendor: the
|
|
190
206
|
* quota error that only appears when a shared sandbox is full, the 429 that only
|
|
191
207
|
* appears under load, the 5xx that proves a retry path works.
|
|
208
|
+
*
|
|
209
|
+
* A rule has three parts. What it **matches** (`operationId`, `method`, `path`, …), **when**
|
|
210
|
+
* it fires among the matching requests (`after`, `every`, `count`, `rate`, `from`, `until`),
|
|
211
|
+
* and what it **does** (`status`, `delay`, `timeout`, `drop`, `truncate`, `effect`).
|
|
192
212
|
*/
|
|
193
213
|
type FaultRule = {
|
|
194
|
-
/** Stable id, so a suite can retire exactly the rule it added. */
|
|
214
|
+
/** Stable id, so a suite can retire exactly the rule it added. Unique within a namespace. */
|
|
195
215
|
id: string;
|
|
196
216
|
/** Fault only this operation. Omit to match every operation. */
|
|
197
217
|
operationId?: string;
|
|
198
218
|
/** Fault only this HTTP method, case-insensitive. Omit to match every method. */
|
|
199
219
|
method?: string;
|
|
220
|
+
/** Fault only this exact path. */
|
|
221
|
+
path?: string;
|
|
200
222
|
/** Fault only paths starting with this prefix. Omit to match every path. */
|
|
201
223
|
pathPrefix?: string;
|
|
224
|
+
/** Fault only paths matching this regular expression (JavaScript syntax, unanchored). */
|
|
225
|
+
pathPattern?: string;
|
|
226
|
+
/** Fault only requests carrying these headers. `"*"` matches any value. */
|
|
227
|
+
requestHeaders?: Record<string, string>;
|
|
228
|
+
/** Fault only requests carrying these query parameters. `"*"` matches any value. */
|
|
229
|
+
query?: Record<string, string>;
|
|
202
230
|
/**
|
|
203
231
|
* Fault only this namespace. Omit (or `"*"`) to fault every namespace — which is what
|
|
204
232
|
* an in-process caller usually wants, and what a parallel worker usually does not:
|
|
205
233
|
* rules added through `POST /__admin/faults` default to the calling namespace.
|
|
206
234
|
*/
|
|
207
235
|
namespace?: string;
|
|
236
|
+
/** Let this many matching requests through first. */
|
|
237
|
+
after?: number;
|
|
238
|
+
/** Then fault only every nth matching request: `3` faults the 3rd, 6th, 9th. */
|
|
239
|
+
every?: number;
|
|
240
|
+
/** Retire the rule after this many faults. Omit to keep it until removed. */
|
|
241
|
+
count?: number;
|
|
242
|
+
/** Fault this fraction of the remaining requests, `0`–`1`, drawn from the seed. Default `1`. */
|
|
243
|
+
rate?: number;
|
|
244
|
+
/**
|
|
245
|
+
* Fault only from this instant on the namespace clock. A duration (`"5m"`) counts from the
|
|
246
|
+
* clock when the rule was added. Listed as epoch ms.
|
|
247
|
+
*/
|
|
248
|
+
from?: Instant | Duration;
|
|
249
|
+
/** Stop faulting at this instant on the namespace clock. A duration counts from when added. */
|
|
250
|
+
until?: Instant | Duration;
|
|
208
251
|
/**
|
|
209
|
-
* Status of the injected response. Omit for a rule that only delays
|
|
210
|
-
*
|
|
211
|
-
* the request then still reaches the service.
|
|
252
|
+
* Status of the injected response. Omit for a rule that only delays, times out, drops,
|
|
253
|
+
* truncates, or switches on an `effect`: the request then still reaches the service.
|
|
212
254
|
*/
|
|
213
255
|
status?: number;
|
|
214
256
|
/** Response body, serialized as JSON. A string is sent as-is. */
|
|
215
257
|
body?: unknown;
|
|
258
|
+
/** Response headers. */
|
|
216
259
|
headers?: Record<string, string>;
|
|
217
|
-
/**
|
|
218
|
-
|
|
219
|
-
/**
|
|
220
|
-
rate?: number;
|
|
221
|
-
/** Hold the response back this long, to exercise timeouts. */
|
|
260
|
+
/** Hold the response back this long. Listed as `delayMs`. */
|
|
261
|
+
delay?: Duration;
|
|
262
|
+
/** `delay`, in milliseconds. */
|
|
222
263
|
delayMs?: number;
|
|
223
264
|
/** Alias of `delayMs`. */
|
|
224
265
|
latencyMs?: number;
|
|
266
|
+
/** Extra seeded delay in `[0, jitter]`. Listed as `jitterMs`. */
|
|
267
|
+
jitter?: Duration;
|
|
268
|
+
jitterMs?: number;
|
|
269
|
+
/**
|
|
270
|
+
* Never answer: hold the request this long, then drop the connection. Listed as
|
|
271
|
+
* `timeoutMs`. With virtual time the wait is spent on the mock clock.
|
|
272
|
+
*/
|
|
273
|
+
timeout?: Duration;
|
|
274
|
+
timeoutMs?: number;
|
|
225
275
|
/**
|
|
226
276
|
* Drop the connection instead of answering: an in-process `fetch` rejects with a
|
|
227
277
|
* `TypeError`, and a served mock destroys the socket. Models "unknown outcome" failures.
|
|
228
278
|
*/
|
|
229
279
|
drop?: boolean;
|
|
280
|
+
/**
|
|
281
|
+
* Cut the response body off after this many bytes: the status and headers arrive, then
|
|
282
|
+
* the connection dies mid-body.
|
|
283
|
+
*/
|
|
284
|
+
truncate?: number;
|
|
230
285
|
/**
|
|
231
286
|
* A named service behaviour to switch on for the matching request instead of (or
|
|
232
287
|
* before) a canned response, e.g. `created_but_500` or `numeric_tracking_id`. Services
|
|
@@ -235,8 +290,8 @@ type FaultRule = {
|
|
|
235
290
|
effect?: string;
|
|
236
291
|
/** Parameters for `effect`. */
|
|
237
292
|
params?: Record<string, unknown>;
|
|
238
|
-
/**
|
|
239
|
-
|
|
293
|
+
/** The preset this rule was expanded from, if any. */
|
|
294
|
+
fromPreset?: string;
|
|
240
295
|
};
|
|
241
296
|
/** A fault that fired for one request. */
|
|
242
297
|
type FaultHit = {
|
|
@@ -244,6 +299,10 @@ type FaultHit = {
|
|
|
244
299
|
/** The injected response; absent when the rule only delays, drops, or sets an effect. */
|
|
245
300
|
response?: Response;
|
|
246
301
|
drop?: boolean;
|
|
302
|
+
/** Set with `drop` when the rule held the request for its `timeout` first. */
|
|
303
|
+
timeout?: boolean;
|
|
304
|
+
/** Bytes of response body to let through before the connection dies. */
|
|
305
|
+
truncate?: number;
|
|
247
306
|
effect?: {
|
|
248
307
|
name: string;
|
|
249
308
|
params: Record<string, unknown>;
|
|
@@ -255,38 +314,200 @@ type FaultCandidate = {
|
|
|
255
314
|
method: string;
|
|
256
315
|
path: string;
|
|
257
316
|
namespace: string;
|
|
317
|
+
/** Request headers and query, for rules that match on them. */
|
|
318
|
+
headers?: Headers;
|
|
319
|
+
query?: URLSearchParams;
|
|
320
|
+
/** The namespace clock, for `from` / `until`. Rules with a window are skipped without it. */
|
|
321
|
+
now?: number;
|
|
322
|
+
/** How to spend a delay for this request. Default: the registry's own sleep. */
|
|
323
|
+
wait?: (ms: number) => Promise<void>;
|
|
324
|
+
};
|
|
325
|
+
/** A stored rule and how often it was consulted. */
|
|
326
|
+
type FaultListing = FaultRule & {
|
|
327
|
+
/** Faults left before the rule retires. `null` when it has no `count`. */
|
|
328
|
+
remaining: number | null;
|
|
329
|
+
/** Times the rule faulted a request. */
|
|
330
|
+
hits: number;
|
|
331
|
+
/** Requests that matched the rule, faulted or not. */
|
|
332
|
+
seen: number;
|
|
333
|
+
};
|
|
334
|
+
/** A namespace's own rules, with their counters, in the order they are tried. */
|
|
335
|
+
type FaultSnapshot = {
|
|
336
|
+
/**
|
|
337
|
+
* `position` is how many `"*"` rules are tried before the rule, which is what its place
|
|
338
|
+
* in the order means to a request and holds in any process.
|
|
339
|
+
*/
|
|
340
|
+
rules: (FaultListing & {
|
|
341
|
+
position?: number;
|
|
342
|
+
})[];
|
|
343
|
+
/** How many `fault_<n>` ids the namespace has handed out. */
|
|
344
|
+
nextId?: number;
|
|
258
345
|
};
|
|
259
346
|
type FaultRegistry = {
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
rules: (FaultRule & {
|
|
263
|
-
remaining: number | null;
|
|
264
|
-
hits: number;
|
|
265
|
-
position: number;
|
|
266
|
-
})[];
|
|
267
|
-
rngState: number;
|
|
268
|
-
};
|
|
347
|
+
snapshot(namespace: string): FaultSnapshot;
|
|
348
|
+
/** Add a rule, or replace the rule with the same id in the same namespace. */
|
|
269
349
|
add(rule: FaultRule): FaultRule;
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
})[];
|
|
282
|
-
rngState: number;
|
|
283
|
-
}): void;
|
|
350
|
+
/** The next unused `fault_<n>` id in `namespace`. */
|
|
351
|
+
nextId(namespace: string): string;
|
|
352
|
+
/** Every rule, or the rules a namespace's requests can hit: its own and the global ones. */
|
|
353
|
+
list(namespace?: string): FaultListing[];
|
|
354
|
+
get(id: string, namespace?: string): FaultListing | undefined;
|
|
355
|
+
/** Remove a rule by id: from `namespace` (its own, then a global one), or wherever it is. */
|
|
356
|
+
remove(id: string, namespace?: string): boolean;
|
|
357
|
+
/** Remove every rule, or one namespace's own rules. */
|
|
358
|
+
clear(namespace?: string): void;
|
|
359
|
+
/** Replace a namespace's own rules with a snapshot's, wherever the snapshot was taken. */
|
|
360
|
+
restore(namespace: string, state: FaultSnapshot): void;
|
|
284
361
|
/**
|
|
285
362
|
* Every fault this request should get, in rule order, stopping at the first that answers
|
|
286
363
|
* or drops (effect-only and delay-only rules let later rules match too). Consumes one of
|
|
287
364
|
* each matching rule's remaining uses.
|
|
288
365
|
*/
|
|
289
366
|
take(candidate: FaultCandidate): Promise<FaultHit[]>;
|
|
367
|
+
/**
|
|
368
|
+
* Fire these rules at one request without storing them: no matching, no schedule, in order,
|
|
369
|
+
* stopping at the first that answers or drops. Jitter draws from the namespace's stream.
|
|
370
|
+
*/
|
|
371
|
+
fire(rules: readonly FaultRule[], candidate: FaultCandidate): Promise<FaultHit[]>;
|
|
372
|
+
};
|
|
373
|
+
|
|
374
|
+
/**
|
|
375
|
+
* The admin controls every mock shares, as one document.
|
|
376
|
+
*
|
|
377
|
+
* The same shape is accepted in three places, and means the same thing in each:
|
|
378
|
+
*
|
|
379
|
+
* - at boot: `createRuntime({ adminControls })`, `serve --admin-controls`,
|
|
380
|
+
* `MOCKINGBIRD_ADMIN_CONTROLS`
|
|
381
|
+
* - over HTTP: `PUT /__admin/controls`
|
|
382
|
+
* - per request: the `x-mockingbird-*` headers in {@link CONTROL_HEADERS}
|
|
383
|
+
*
|
|
384
|
+
* Every control is deterministic: given the same seed, clock and requests, a mock answers
|
|
385
|
+
* the same bytes. Nothing here reads the wall clock or `Math.random`.
|
|
386
|
+
*/
|
|
387
|
+
/** Milliseconds, or a string like `"250ms"`, `"2s"`, `"15m"`, `"1h"`, `"3d"`. */
|
|
388
|
+
type Duration = number | string;
|
|
389
|
+
/** Epoch milliseconds, or an ISO-8601 string. */
|
|
390
|
+
type Instant = number | string;
|
|
391
|
+
type ClockControls = {
|
|
392
|
+
/** Move the clock to this instant. */
|
|
393
|
+
now?: Instant;
|
|
394
|
+
/** Stop time. A frozen clock moves only when told to, so timestamps replay exactly. */
|
|
395
|
+
frozen?: boolean;
|
|
396
|
+
/**
|
|
397
|
+
* Step the clock forward by this much before every vendor request. With a frozen clock
|
|
398
|
+
* each request still gets its own, reproducible timestamp.
|
|
399
|
+
*/
|
|
400
|
+
autoAdvance?: Duration;
|
|
401
|
+
};
|
|
402
|
+
/** How long a response takes: a fixed delay plus seeded jitter in `[0, jitter]`. */
|
|
403
|
+
type LatencyRuleInput = {
|
|
404
|
+
delay?: Duration;
|
|
405
|
+
jitter?: Duration;
|
|
406
|
+
};
|
|
407
|
+
type LatencyControls = LatencyRuleInput & {
|
|
408
|
+
/** Per-operation overrides, keyed by operationId. A bare duration is its `delay`. */
|
|
409
|
+
operations?: Record<string, Duration | LatencyRuleInput>;
|
|
410
|
+
};
|
|
411
|
+
/** A fault to add: a rule (the id is assigned when omitted), or a named preset with overrides. */
|
|
412
|
+
type FaultInput = (Omit<FaultRule, "id"> & {
|
|
413
|
+
id?: string;
|
|
414
|
+
}) | ({
|
|
415
|
+
preset: string;
|
|
416
|
+
} & Partial<FaultRule>);
|
|
417
|
+
/** Identifies a {@link SnapshotDocument}. */
|
|
418
|
+
declare const SNAPSHOT_FORMAT = "mockingbird.snapshot/v1";
|
|
419
|
+
/**
|
|
420
|
+
* A namespace, as portable JSON: what `GET /__admin/snapshots/:id` returns and what
|
|
421
|
+
* `PUT /__admin/snapshots/:id` and the boot `snapshot` control accept. Only `format` and
|
|
422
|
+
* `records` are required, so a hand-written seed file is a valid snapshot.
|
|
423
|
+
*/
|
|
424
|
+
type SnapshotDocument = {
|
|
425
|
+
format: typeof SNAPSHOT_FORMAT;
|
|
426
|
+
/** The service that wrote it. A snapshot is rejected by any other service. */
|
|
427
|
+
service?: string;
|
|
428
|
+
/**
|
|
429
|
+
* Stored rows. `seq` orders a collection; omitted, rows keep their listed order. `raw` is
|
|
430
|
+
* the stored text of a row that is not a plain record, and replaces `value` when present.
|
|
431
|
+
*/
|
|
432
|
+
records: {
|
|
433
|
+
collection: string;
|
|
434
|
+
id: string;
|
|
435
|
+
seq?: number;
|
|
436
|
+
value?: unknown;
|
|
437
|
+
raw?: string;
|
|
438
|
+
}[];
|
|
439
|
+
/** Id counters, so the next generated id continues where the snapshot left off. */
|
|
440
|
+
sequences?: {
|
|
441
|
+
name: string;
|
|
442
|
+
kind: string;
|
|
443
|
+
value: number;
|
|
444
|
+
}[];
|
|
445
|
+
clock?: {
|
|
446
|
+
now: number;
|
|
447
|
+
frozen: boolean;
|
|
448
|
+
autoAdvanceMs?: number;
|
|
449
|
+
};
|
|
450
|
+
seed?: number | string;
|
|
451
|
+
/** Positions of the seeded random streams. */
|
|
452
|
+
rng?: {
|
|
453
|
+
state: number;
|
|
454
|
+
faults?: number;
|
|
455
|
+
latency?: number;
|
|
456
|
+
};
|
|
457
|
+
faults?: unknown;
|
|
458
|
+
latency?: unknown;
|
|
459
|
+
virtualTime?: boolean;
|
|
460
|
+
};
|
|
461
|
+
/** Controls for one namespace. */
|
|
462
|
+
type NamespaceControls = {
|
|
463
|
+
/** Seeds every random choice: fault rates, jitter, and whatever the service invents. */
|
|
464
|
+
seed?: number | string;
|
|
465
|
+
clock?: ClockControls;
|
|
466
|
+
/**
|
|
467
|
+
* Spend injected waits (latency, fault delays, timeouts) on the mock clock instead of the
|
|
468
|
+
* wall clock: the request returns at once, the clock has moved, and the journal records
|
|
469
|
+
* the wait exactly. Default `false`: waits are real, so a client's own timeout can fire.
|
|
470
|
+
*/
|
|
471
|
+
virtualTime?: boolean;
|
|
472
|
+
/** Baseline response time for every vendor request. A bare duration is its `delay`. */
|
|
473
|
+
latency?: Duration | LatencyControls;
|
|
474
|
+
faults?: readonly FaultInput[];
|
|
475
|
+
/** Start from this state instead of the service's own seed data. */
|
|
476
|
+
snapshot?: SnapshotDocument;
|
|
477
|
+
};
|
|
478
|
+
/** {@link NamespaceControls} for every namespace, with per-namespace overrides. */
|
|
479
|
+
type MockControls = NamespaceControls & {
|
|
480
|
+
/** Vendor credential → namespace, for SDKs that cannot send a namespace header. */
|
|
481
|
+
credentials?: Record<string, string>;
|
|
482
|
+
/** Overrides for named namespaces. A key given here replaces the shared value. */
|
|
483
|
+
namespaces?: Record<string, NamespaceControls>;
|
|
484
|
+
};
|
|
485
|
+
/** A latency rule in milliseconds. */
|
|
486
|
+
type LatencyRule = {
|
|
487
|
+
delayMs: number;
|
|
488
|
+
jitterMs: number;
|
|
489
|
+
};
|
|
490
|
+
/** Baseline latency for a namespace, normalized. */
|
|
491
|
+
type LatencyState = LatencyRule & {
|
|
492
|
+
operations: Record<string, LatencyRule>;
|
|
493
|
+
};
|
|
494
|
+
/** What {@link controlHeaders} turns into request headers. */
|
|
495
|
+
type ControlHeaderInput = {
|
|
496
|
+
namespace?: string;
|
|
497
|
+
adminKey?: string;
|
|
498
|
+
branch?: string;
|
|
499
|
+
at?: string;
|
|
500
|
+
reset?: boolean;
|
|
501
|
+
restore?: string;
|
|
502
|
+
seed?: number | string;
|
|
503
|
+
time?: Instant | Date;
|
|
504
|
+
advance?: Duration;
|
|
505
|
+
virtualTime?: boolean;
|
|
506
|
+
delay?: Duration;
|
|
507
|
+
timeout?: Duration;
|
|
508
|
+
/** A status, `"drop"`, a preset name, or a fault rule. */
|
|
509
|
+
fault?: number | string | Record<string, unknown>;
|
|
510
|
+
snapshot?: string;
|
|
290
511
|
};
|
|
291
512
|
|
|
292
513
|
/**
|
|
@@ -326,6 +547,8 @@ type RequestLog = {
|
|
|
326
547
|
unmatched: boolean;
|
|
327
548
|
/** Set when a fault rule produced the response. */
|
|
328
549
|
faultId?: string;
|
|
550
|
+
/** Milliseconds of injected wait: latency, fault delays and timeouts. Absent when none. */
|
|
551
|
+
delayMs?: number;
|
|
329
552
|
/** Resource ids the handler touched (`userId`, `orderId`, …), when the service reports them. */
|
|
330
553
|
ids?: Record<string, string>;
|
|
331
554
|
/** Set when the service created a resource the request referred to but that did not exist. */
|
|
@@ -371,6 +594,12 @@ type JournalQuery = {
|
|
|
371
594
|
/** Only this namespace. Omit for every namespace, oldest first across all of them. */
|
|
372
595
|
namespace?: string;
|
|
373
596
|
operationId?: string;
|
|
597
|
+
/** Only this HTTP method, case-insensitive. */
|
|
598
|
+
method?: string;
|
|
599
|
+
/** Only this exact path. */
|
|
600
|
+
path?: string;
|
|
601
|
+
/** Only requests this fault rule answered or shaped. */
|
|
602
|
+
faultId?: string;
|
|
374
603
|
status?: number;
|
|
375
604
|
/** Only entries at or after this instant (epoch ms). */
|
|
376
605
|
since?: number;
|
|
@@ -385,6 +614,50 @@ type Journal = {
|
|
|
385
614
|
clear(namespace?: string): void;
|
|
386
615
|
};
|
|
387
616
|
|
|
617
|
+
/**
|
|
618
|
+
* Baseline response time, per namespace: how long every vendor request takes before any
|
|
619
|
+
* fault is considered. Jitter draws from a stream the caller owns, one per namespace and
|
|
620
|
+
* separate from the fault stream, so adding latency never shifts which requests a `rate`
|
|
621
|
+
* fault hits.
|
|
622
|
+
*/
|
|
623
|
+
type LatencyRegistry = {
|
|
624
|
+
get(namespace: string): LatencyState;
|
|
625
|
+
set(namespace: string, state: LatencyState): LatencyState;
|
|
626
|
+
/** Remove one namespace's latency, or every namespace's. */
|
|
627
|
+
clear(namespace?: string): void;
|
|
628
|
+
/** Milliseconds this request waits. Draws jitter, so call it once per request. */
|
|
629
|
+
take(namespace: string, operationId: string | undefined): number;
|
|
630
|
+
};
|
|
631
|
+
|
|
632
|
+
/** Clock state as the admin API reports it. */
|
|
633
|
+
type ControlClock = ClockState & {
|
|
634
|
+
/** `now`, as ISO-8601. */
|
|
635
|
+
iso: string;
|
|
636
|
+
/** Milliseconds the clock steps before every vendor request. */
|
|
637
|
+
autoAdvanceMs: number;
|
|
638
|
+
};
|
|
639
|
+
/** One namespace's controls: the body of `GET /__admin/controls`. */
|
|
640
|
+
type ControlState = {
|
|
641
|
+
namespace: string;
|
|
642
|
+
seed: number | string;
|
|
643
|
+
clock: ControlClock;
|
|
644
|
+
virtualTime: boolean;
|
|
645
|
+
latency: LatencyState;
|
|
646
|
+
faults: FaultListing[];
|
|
647
|
+
};
|
|
648
|
+
|
|
649
|
+
/** What `GET /__admin/snapshots` lists for each snapshot. */
|
|
650
|
+
type SnapshotInfo = {
|
|
651
|
+
id: string;
|
|
652
|
+
namespace: string;
|
|
653
|
+
/** Stored rows in the snapshot. */
|
|
654
|
+
records: number;
|
|
655
|
+
/** The namespace clock when it was taken, epoch ms. */
|
|
656
|
+
at: number;
|
|
657
|
+
/** Whether `GET /snapshots/:id` can return it as a {@link SnapshotDocument}. */
|
|
658
|
+
portable: boolean;
|
|
659
|
+
};
|
|
660
|
+
|
|
388
661
|
/** Credential → namespace mapping behind `PUT /__admin/credentials`. */
|
|
389
662
|
type CredentialRegistry = {
|
|
390
663
|
set(credential: string, namespace: string): void;
|
|
@@ -539,7 +812,10 @@ type ServiceInstance = FetchAPI$1 & {
|
|
|
539
812
|
};
|
|
540
813
|
type ServiceTimelineState = Readonly<{
|
|
541
814
|
snapshot: NamespaceSnapshot;
|
|
542
|
-
clock
|
|
815
|
+
/** `pinned`: the namespace's clock was frozen itself, not just following a frozen base. */
|
|
816
|
+
clock: Readonly<ClockState & {
|
|
817
|
+
pinned?: boolean;
|
|
818
|
+
}>;
|
|
543
819
|
rngState: number;
|
|
544
820
|
}>;
|
|
545
821
|
type ServiceCheckpoint = Checkpoint<ServiceTimelineState>;
|
|
@@ -547,17 +823,23 @@ type ServiceRuntime<T extends ServiceInstance> = FetchAPI$1 & {
|
|
|
547
823
|
/** Stop package-owned lifecycle timers when a supervisor closes the runtime. */
|
|
548
824
|
stop?(): void;
|
|
549
825
|
readonly name: string;
|
|
826
|
+
/** Same-origin Fetch handler and App Router method exports, sharing this runtime. */
|
|
827
|
+
mount(prefix: string): MountedAPI;
|
|
550
828
|
readonly sqlite: SqliteClient$1;
|
|
551
829
|
readonly clock: Clock;
|
|
552
830
|
readonly faults: FaultRegistry;
|
|
831
|
+
/** Baseline response time per namespace. */
|
|
832
|
+
readonly latency: LatencyRegistry;
|
|
553
833
|
readonly metrics: Metrics;
|
|
554
834
|
readonly journal: Journal;
|
|
555
835
|
readonly rng: Rng;
|
|
556
836
|
readonly credentials: CredentialRegistry;
|
|
557
837
|
/** The webhook hub, when the service has outbound webhooks. */
|
|
558
838
|
readonly webhooks: WebhookHub | undefined;
|
|
559
|
-
/**
|
|
560
|
-
|
|
839
|
+
/**
|
|
840
|
+
* A namespace's clock. Each follows the base clock, {@link ServiceRuntime.clock}, with an
|
|
841
|
+
* offset and a freeze of its own, so moving one never moves another.
|
|
842
|
+
*/
|
|
561
843
|
namespaceClock(namespace?: string): Clock;
|
|
562
844
|
namespaceOf(request: Request): string;
|
|
563
845
|
/** Opaque in-process checkpoint including records, controls and webhook history. */
|
|
@@ -569,8 +851,38 @@ type ServiceRuntime<T extends ServiceInstance> = FetchAPI$1 & {
|
|
|
569
851
|
instance(namespace?: string): T;
|
|
570
852
|
/** Public names of every namespace created so far. */
|
|
571
853
|
namespaces(): string[];
|
|
572
|
-
/**
|
|
854
|
+
/** Return one namespace to its boot state, or every namespace with `"*"`. */
|
|
573
855
|
reset(namespace?: string): Promise<void>;
|
|
856
|
+
/** Reset a namespace and forget it, releasing everything it held. */
|
|
857
|
+
dropNamespace(namespace: string): Promise<void>;
|
|
858
|
+
/** A namespace's controls: seed, clock, virtual time, latency, faults and snapshots. */
|
|
859
|
+
controls(namespace?: string): ControlState & {
|
|
860
|
+
snapshots: SnapshotInfo[];
|
|
861
|
+
};
|
|
862
|
+
/** Apply a control document to a namespace. A given key replaces that control. */
|
|
863
|
+
configure(controls: NamespaceControls, namespace?: string): ControlState & {
|
|
864
|
+
snapshots: SnapshotInfo[];
|
|
865
|
+
};
|
|
866
|
+
/** Named snapshots of a namespace: records, clock, random streams, faults and latency. */
|
|
867
|
+
readonly snapshots: {
|
|
868
|
+
/** Capture the namespace now. Reusing a name replaces that snapshot. */
|
|
869
|
+
create(options?: {
|
|
870
|
+
name?: string;
|
|
871
|
+
namespace?: string;
|
|
872
|
+
}): SnapshotInfo;
|
|
873
|
+
list(namespace?: string): SnapshotInfo[];
|
|
874
|
+
/** The snapshot as portable JSON, to commit beside a suite or boot another mock from. */
|
|
875
|
+
export(id: string, namespace?: string): SnapshotDocument;
|
|
876
|
+
/** Store a document as a snapshot without restoring it. */
|
|
877
|
+
import(document: SnapshotDocument, options?: {
|
|
878
|
+
name?: string;
|
|
879
|
+
namespace?: string;
|
|
880
|
+
}): SnapshotInfo;
|
|
881
|
+
restore(id: string, namespace?: string): void;
|
|
882
|
+
delete(id: string, namespace?: string): boolean;
|
|
883
|
+
};
|
|
884
|
+
/** Request headers that carry controls, checked: spread them into a `fetch` or an SDK's defaults. */
|
|
885
|
+
headers(input: ControlHeaderInput): Record<string, string>;
|
|
574
886
|
snapshot(namespace?: string): NamespaceSnapshot;
|
|
575
887
|
restore(snapshot: NamespaceSnapshot, namespace?: string): void;
|
|
576
888
|
/** Capture the current branch. Mutating HTTP calls do this automatically. */
|
|
@@ -1553,6 +1865,8 @@ type JunctionRuntimeOptions = {
|
|
|
1553
1865
|
adminPrefix?: string;
|
|
1554
1866
|
/** Require `x-mockingbird-admin-key` on `/__admin/*`. */
|
|
1555
1867
|
adminKey?: string;
|
|
1868
|
+
/** Admin controls to boot with: clock, latency, faults, seed, a starting snapshot. */
|
|
1869
|
+
adminControls?: MockControls;
|
|
1556
1870
|
onLog?: (entry: RequestLog) => void;
|
|
1557
1871
|
};
|
|
1558
1872
|
type JunctionRuntime = ServiceRuntime<JunctionAPI> & {
|