@crvouga/mockingbird-service-google 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/CHANGELOG.md +11 -1
- package/DISCOVERY.md +23 -0
- package/README.md +35 -3
- package/dist/{chunk-M73LWCCP.js → chunk-6Z2MR3PO.js} +33 -3
- package/dist/{chunk-M73LWCCP.js.map → chunk-6Z2MR3PO.js.map} +2 -2
- package/dist/chunk-DI2MWIYZ.js +10171 -0
- package/dist/chunk-DI2MWIYZ.js.map +7 -0
- package/dist/{chunk-S6TECUBL.js → chunk-QV342ARR.js} +136 -25
- package/dist/chunk-QV342ARR.js.map +7 -0
- package/dist/cli.js +3 -3
- package/dist/crypto-II2ETGQQ.js +21 -0
- package/dist/{helpers-BMHFVPFA.js → helpers-5D4ROPWG.js} +2 -2
- package/dist/index.d.ts +361 -44
- package/dist/index.js +2 -2
- package/dist/server.d.ts +700 -84
- package/dist/server.js +3 -3
- package/package.json +3 -2
- package/dist/chunk-KRPPUJIW.js +0 -8361
- package/dist/chunk-KRPPUJIW.js.map +0 -7
- package/dist/chunk-S6TECUBL.js.map +0 -7
- package/dist/crypto-I5AVO7Q3.js +0 -15
- /package/dist/{crypto-I5AVO7Q3.js.map → crypto-II2ETGQQ.js.map} +0 -0
- /package/dist/{helpers-BMHFVPFA.js.map → helpers-5D4ROPWG.js.map} +0 -0
package/dist/index.d.ts
CHANGED
|
@@ -470,6 +470,11 @@ type ProviderOptions = APIOptions & {
|
|
|
470
470
|
fallbackUser?: AuthFallback;
|
|
471
471
|
publicNamespace?: string;
|
|
472
472
|
adminPrefix?: string;
|
|
473
|
+
/**
|
|
474
|
+
* A seeded stream of `[0, 1)` that ids and tokens are minted from, so a run replays from
|
|
475
|
+
* its seed. Default: the platform's randomness.
|
|
476
|
+
*/
|
|
477
|
+
random?: () => number;
|
|
473
478
|
};
|
|
474
479
|
/** Portable vendor API backed by the shared namespace; it owns no separate history or listener. */
|
|
475
480
|
declare class ProviderAPI {
|
|
@@ -1004,7 +1009,7 @@ type ClockState = {
|
|
|
1004
1009
|
now: number;
|
|
1005
1010
|
/** True while time does not advance on its own. */
|
|
1006
1011
|
frozen: boolean;
|
|
1007
|
-
/** Milliseconds
|
|
1012
|
+
/** Milliseconds a running clock adds to its underlying source. `0` while frozen. */
|
|
1008
1013
|
offsetMs: number;
|
|
1009
1014
|
};
|
|
1010
1015
|
type Clock = {
|
|
@@ -1040,7 +1045,10 @@ type Rng = {
|
|
|
1040
1045
|
state(): number;
|
|
1041
1046
|
/** Restore a state previously returned by {@link state}. */
|
|
1042
1047
|
setState(state: number): void;
|
|
1043
|
-
seed
|
|
1048
|
+
/** Restart the stream from a new seed. `reset` then returns to this seed. */
|
|
1049
|
+
reseed(seed: number | string): void;
|
|
1050
|
+
/** The seed the stream currently starts from. */
|
|
1051
|
+
readonly seed: number;
|
|
1044
1052
|
};
|
|
1045
1053
|
|
|
1046
1054
|
/**
|
|
@@ -1049,44 +1057,83 @@ type Rng = {
|
|
|
1049
1057
|
* This is how a suite reaches the vendor's failure modes without the vendor: the
|
|
1050
1058
|
* quota error that only appears when a shared sandbox is full, the 429 that only
|
|
1051
1059
|
* appears under load, the 5xx that proves a retry path works.
|
|
1060
|
+
*
|
|
1061
|
+
* A rule has three parts. What it **matches** (`operationId`, `method`, `path`, …), **when**
|
|
1062
|
+
* it fires among the matching requests (`after`, `every`, `count`, `rate`, `from`, `until`),
|
|
1063
|
+
* and what it **does** (`status`, `delay`, `timeout`, `drop`, `truncate`, `effect`).
|
|
1052
1064
|
*/
|
|
1053
1065
|
type FaultRule = {
|
|
1054
|
-
/** Stable id, so a suite can retire exactly the rule it added. */
|
|
1066
|
+
/** Stable id, so a suite can retire exactly the rule it added. Unique within a namespace. */
|
|
1055
1067
|
id: string;
|
|
1056
1068
|
/** Fault only this operation. Omit to match every operation. */
|
|
1057
1069
|
operationId?: string;
|
|
1058
1070
|
/** Fault only this HTTP method, case-insensitive. Omit to match every method. */
|
|
1059
1071
|
method?: string;
|
|
1072
|
+
/** Fault only this exact path. */
|
|
1073
|
+
path?: string;
|
|
1060
1074
|
/** Fault only paths starting with this prefix. Omit to match every path. */
|
|
1061
1075
|
pathPrefix?: string;
|
|
1076
|
+
/** Fault only paths matching this regular expression (JavaScript syntax, unanchored). */
|
|
1077
|
+
pathPattern?: string;
|
|
1078
|
+
/** Fault only requests carrying these headers. `"*"` matches any value. */
|
|
1079
|
+
requestHeaders?: Record<string, string>;
|
|
1080
|
+
/** Fault only requests carrying these query parameters. `"*"` matches any value. */
|
|
1081
|
+
query?: Record<string, string>;
|
|
1062
1082
|
/**
|
|
1063
1083
|
* Fault only this namespace. Omit (or `"*"`) to fault every namespace — which is what
|
|
1064
1084
|
* an in-process caller usually wants, and what a parallel worker usually does not:
|
|
1065
1085
|
* rules added through `POST /__admin/faults` default to the calling namespace.
|
|
1066
1086
|
*/
|
|
1067
1087
|
namespace?: string;
|
|
1088
|
+
/** Let this many matching requests through first. */
|
|
1089
|
+
after?: number;
|
|
1090
|
+
/** Then fault only every nth matching request: `3` faults the 3rd, 6th, 9th. */
|
|
1091
|
+
every?: number;
|
|
1092
|
+
/** Retire the rule after this many faults. Omit to keep it until removed. */
|
|
1093
|
+
count?: number;
|
|
1094
|
+
/** Fault this fraction of the remaining requests, `0`–`1`, drawn from the seed. Default `1`. */
|
|
1095
|
+
rate?: number;
|
|
1068
1096
|
/**
|
|
1069
|
-
*
|
|
1070
|
-
*
|
|
1071
|
-
|
|
1097
|
+
* Fault only from this instant on the namespace clock. A duration (`"5m"`) counts from the
|
|
1098
|
+
* clock when the rule was added. Listed as epoch ms.
|
|
1099
|
+
*/
|
|
1100
|
+
from?: Instant | Duration;
|
|
1101
|
+
/** Stop faulting at this instant on the namespace clock. A duration counts from when added. */
|
|
1102
|
+
until?: Instant | Duration;
|
|
1103
|
+
/**
|
|
1104
|
+
* Status of the injected response. Omit for a rule that only delays, times out, drops,
|
|
1105
|
+
* truncates, or switches on an `effect`: the request then still reaches the service.
|
|
1072
1106
|
*/
|
|
1073
1107
|
status?: number;
|
|
1074
1108
|
/** Response body, serialized as JSON. A string is sent as-is. */
|
|
1075
1109
|
body?: unknown;
|
|
1110
|
+
/** Response headers. */
|
|
1076
1111
|
headers?: Record<string, string>;
|
|
1077
|
-
/**
|
|
1078
|
-
|
|
1079
|
-
/**
|
|
1080
|
-
rate?: number;
|
|
1081
|
-
/** Hold the response back this long, to exercise timeouts. */
|
|
1112
|
+
/** Hold the response back this long. Listed as `delayMs`. */
|
|
1113
|
+
delay?: Duration;
|
|
1114
|
+
/** `delay`, in milliseconds. */
|
|
1082
1115
|
delayMs?: number;
|
|
1083
1116
|
/** Alias of `delayMs`. */
|
|
1084
1117
|
latencyMs?: number;
|
|
1118
|
+
/** Extra seeded delay in `[0, jitter]`. Listed as `jitterMs`. */
|
|
1119
|
+
jitter?: Duration;
|
|
1120
|
+
jitterMs?: number;
|
|
1121
|
+
/**
|
|
1122
|
+
* Never answer: hold the request this long, then drop the connection. Listed as
|
|
1123
|
+
* `timeoutMs`. With virtual time the wait is spent on the mock clock.
|
|
1124
|
+
*/
|
|
1125
|
+
timeout?: Duration;
|
|
1126
|
+
timeoutMs?: number;
|
|
1085
1127
|
/**
|
|
1086
1128
|
* Drop the connection instead of answering: an in-process `fetch` rejects with a
|
|
1087
1129
|
* `TypeError`, and a served mock destroys the socket. Models "unknown outcome" failures.
|
|
1088
1130
|
*/
|
|
1089
1131
|
drop?: boolean;
|
|
1132
|
+
/**
|
|
1133
|
+
* Cut the response body off after this many bytes: the status and headers arrive, then
|
|
1134
|
+
* the connection dies mid-body.
|
|
1135
|
+
*/
|
|
1136
|
+
truncate?: number;
|
|
1090
1137
|
/**
|
|
1091
1138
|
* A named service behaviour to switch on for the matching request instead of (or
|
|
1092
1139
|
* before) a canned response, e.g. `created_but_500` or `numeric_tracking_id`. Services
|
|
@@ -1095,8 +1142,8 @@ type FaultRule = {
|
|
|
1095
1142
|
effect?: string;
|
|
1096
1143
|
/** Parameters for `effect`. */
|
|
1097
1144
|
params?: Record<string, unknown>;
|
|
1098
|
-
/**
|
|
1099
|
-
|
|
1145
|
+
/** The preset this rule was expanded from, if any. */
|
|
1146
|
+
fromPreset?: string;
|
|
1100
1147
|
};
|
|
1101
1148
|
/** A fault that fired for one request. */
|
|
1102
1149
|
type FaultHit = {
|
|
@@ -1104,6 +1151,10 @@ type FaultHit = {
|
|
|
1104
1151
|
/** The injected response; absent when the rule only delays, drops, or sets an effect. */
|
|
1105
1152
|
response?: Response;
|
|
1106
1153
|
drop?: boolean;
|
|
1154
|
+
/** Set with `drop` when the rule held the request for its `timeout` first. */
|
|
1155
|
+
timeout?: boolean;
|
|
1156
|
+
/** Bytes of response body to let through before the connection dies. */
|
|
1157
|
+
truncate?: number;
|
|
1107
1158
|
effect?: {
|
|
1108
1159
|
name: string;
|
|
1109
1160
|
params: Record<string, unknown>;
|
|
@@ -1128,38 +1179,200 @@ type FaultCandidate = {
|
|
|
1128
1179
|
method: string;
|
|
1129
1180
|
path: string;
|
|
1130
1181
|
namespace: string;
|
|
1182
|
+
/** Request headers and query, for rules that match on them. */
|
|
1183
|
+
headers?: Headers;
|
|
1184
|
+
query?: URLSearchParams;
|
|
1185
|
+
/** The namespace clock, for `from` / `until`. Rules with a window are skipped without it. */
|
|
1186
|
+
now?: number;
|
|
1187
|
+
/** How to spend a delay for this request. Default: the registry's own sleep. */
|
|
1188
|
+
wait?: (ms: number) => Promise<void>;
|
|
1189
|
+
};
|
|
1190
|
+
/** A stored rule and how often it was consulted. */
|
|
1191
|
+
type FaultListing = FaultRule & {
|
|
1192
|
+
/** Faults left before the rule retires. `null` when it has no `count`. */
|
|
1193
|
+
remaining: number | null;
|
|
1194
|
+
/** Times the rule faulted a request. */
|
|
1195
|
+
hits: number;
|
|
1196
|
+
/** Requests that matched the rule, faulted or not. */
|
|
1197
|
+
seen: number;
|
|
1198
|
+
};
|
|
1199
|
+
/** A namespace's own rules, with their counters, in the order they are tried. */
|
|
1200
|
+
type FaultSnapshot = {
|
|
1201
|
+
/**
|
|
1202
|
+
* `position` is how many `"*"` rules are tried before the rule, which is what its place
|
|
1203
|
+
* in the order means to a request and holds in any process.
|
|
1204
|
+
*/
|
|
1205
|
+
rules: (FaultListing & {
|
|
1206
|
+
position?: number;
|
|
1207
|
+
})[];
|
|
1208
|
+
/** How many `fault_<n>` ids the namespace has handed out. */
|
|
1209
|
+
nextId?: number;
|
|
1131
1210
|
};
|
|
1132
1211
|
type FaultRegistry = {
|
|
1133
|
-
|
|
1134
|
-
|
|
1135
|
-
rules: (FaultRule & {
|
|
1136
|
-
remaining: number | null;
|
|
1137
|
-
hits: number;
|
|
1138
|
-
position: number;
|
|
1139
|
-
})[];
|
|
1140
|
-
rngState: number;
|
|
1141
|
-
};
|
|
1212
|
+
snapshot(namespace: string): FaultSnapshot;
|
|
1213
|
+
/** Add a rule, or replace the rule with the same id in the same namespace. */
|
|
1142
1214
|
add(rule: FaultRule): FaultRule;
|
|
1143
|
-
|
|
1144
|
-
|
|
1145
|
-
|
|
1146
|
-
|
|
1147
|
-
|
|
1148
|
-
|
|
1149
|
-
|
|
1150
|
-
|
|
1151
|
-
|
|
1152
|
-
|
|
1153
|
-
|
|
1154
|
-
})[];
|
|
1155
|
-
rngState: number;
|
|
1156
|
-
}): void;
|
|
1215
|
+
/** The next unused `fault_<n>` id in `namespace`. */
|
|
1216
|
+
nextId(namespace: string): string;
|
|
1217
|
+
/** Every rule, or the rules a namespace's requests can hit: its own and the global ones. */
|
|
1218
|
+
list(namespace?: string): FaultListing[];
|
|
1219
|
+
get(id: string, namespace?: string): FaultListing | undefined;
|
|
1220
|
+
/** Remove a rule by id: from `namespace` (its own, then a global one), or wherever it is. */
|
|
1221
|
+
remove(id: string, namespace?: string): boolean;
|
|
1222
|
+
/** Remove every rule, or one namespace's own rules. */
|
|
1223
|
+
clear(namespace?: string): void;
|
|
1224
|
+
/** Replace a namespace's own rules with a snapshot's, wherever the snapshot was taken. */
|
|
1225
|
+
restore(namespace: string, state: FaultSnapshot): void;
|
|
1157
1226
|
/**
|
|
1158
1227
|
* Every fault this request should get, in rule order, stopping at the first that answers
|
|
1159
1228
|
* or drops (effect-only and delay-only rules let later rules match too). Consumes one of
|
|
1160
1229
|
* each matching rule's remaining uses.
|
|
1161
1230
|
*/
|
|
1162
1231
|
take(candidate: FaultCandidate): Promise<FaultHit[]>;
|
|
1232
|
+
/**
|
|
1233
|
+
* Fire these rules at one request without storing them: no matching, no schedule, in order,
|
|
1234
|
+
* stopping at the first that answers or drops. Jitter draws from the namespace's stream.
|
|
1235
|
+
*/
|
|
1236
|
+
fire(rules: readonly FaultRule[], candidate: FaultCandidate): Promise<FaultHit[]>;
|
|
1237
|
+
};
|
|
1238
|
+
|
|
1239
|
+
/**
|
|
1240
|
+
* The admin controls every mock shares, as one document.
|
|
1241
|
+
*
|
|
1242
|
+
* The same shape is accepted in three places, and means the same thing in each:
|
|
1243
|
+
*
|
|
1244
|
+
* - at boot: `createRuntime({ adminControls })`, `serve --admin-controls`,
|
|
1245
|
+
* `MOCKINGBIRD_ADMIN_CONTROLS`
|
|
1246
|
+
* - over HTTP: `PUT /__admin/controls`
|
|
1247
|
+
* - per request: the `x-mockingbird-*` headers in {@link CONTROL_HEADERS}
|
|
1248
|
+
*
|
|
1249
|
+
* Every control is deterministic: given the same seed, clock and requests, a mock answers
|
|
1250
|
+
* the same bytes. Nothing here reads the wall clock or `Math.random`.
|
|
1251
|
+
*/
|
|
1252
|
+
/** Milliseconds, or a string like `"250ms"`, `"2s"`, `"15m"`, `"1h"`, `"3d"`. */
|
|
1253
|
+
type Duration = number | string;
|
|
1254
|
+
/** Epoch milliseconds, or an ISO-8601 string. */
|
|
1255
|
+
type Instant = number | string;
|
|
1256
|
+
type ClockControls = {
|
|
1257
|
+
/** Move the clock to this instant. */
|
|
1258
|
+
now?: Instant;
|
|
1259
|
+
/** Stop time. A frozen clock moves only when told to, so timestamps replay exactly. */
|
|
1260
|
+
frozen?: boolean;
|
|
1261
|
+
/**
|
|
1262
|
+
* Step the clock forward by this much before every vendor request. With a frozen clock
|
|
1263
|
+
* each request still gets its own, reproducible timestamp.
|
|
1264
|
+
*/
|
|
1265
|
+
autoAdvance?: Duration;
|
|
1266
|
+
};
|
|
1267
|
+
/** How long a response takes: a fixed delay plus seeded jitter in `[0, jitter]`. */
|
|
1268
|
+
type LatencyRuleInput = {
|
|
1269
|
+
delay?: Duration;
|
|
1270
|
+
jitter?: Duration;
|
|
1271
|
+
};
|
|
1272
|
+
type LatencyControls = LatencyRuleInput & {
|
|
1273
|
+
/** Per-operation overrides, keyed by operationId. A bare duration is its `delay`. */
|
|
1274
|
+
operations?: Record<string, Duration | LatencyRuleInput>;
|
|
1275
|
+
};
|
|
1276
|
+
/** A fault to add: a rule (the id is assigned when omitted), or a named preset with overrides. */
|
|
1277
|
+
type FaultInput = (Omit<FaultRule, "id"> & {
|
|
1278
|
+
id?: string;
|
|
1279
|
+
}) | ({
|
|
1280
|
+
preset: string;
|
|
1281
|
+
} & Partial<FaultRule>);
|
|
1282
|
+
/** Identifies a {@link SnapshotDocument}. */
|
|
1283
|
+
declare const SNAPSHOT_FORMAT = "mockingbird.snapshot/v1";
|
|
1284
|
+
/**
|
|
1285
|
+
* A namespace, as portable JSON: what `GET /__admin/snapshots/:id` returns and what
|
|
1286
|
+
* `PUT /__admin/snapshots/:id` and the boot `snapshot` control accept. Only `format` and
|
|
1287
|
+
* `records` are required, so a hand-written seed file is a valid snapshot.
|
|
1288
|
+
*/
|
|
1289
|
+
type SnapshotDocument = {
|
|
1290
|
+
format: typeof SNAPSHOT_FORMAT;
|
|
1291
|
+
/** The service that wrote it. A snapshot is rejected by any other service. */
|
|
1292
|
+
service?: string;
|
|
1293
|
+
/**
|
|
1294
|
+
* Stored rows. `seq` orders a collection; omitted, rows keep their listed order. `raw` is
|
|
1295
|
+
* the stored text of a row that is not a plain record, and replaces `value` when present.
|
|
1296
|
+
*/
|
|
1297
|
+
records: {
|
|
1298
|
+
collection: string;
|
|
1299
|
+
id: string;
|
|
1300
|
+
seq?: number;
|
|
1301
|
+
value?: unknown;
|
|
1302
|
+
raw?: string;
|
|
1303
|
+
}[];
|
|
1304
|
+
/** Id counters, so the next generated id continues where the snapshot left off. */
|
|
1305
|
+
sequences?: {
|
|
1306
|
+
name: string;
|
|
1307
|
+
kind: string;
|
|
1308
|
+
value: number;
|
|
1309
|
+
}[];
|
|
1310
|
+
clock?: {
|
|
1311
|
+
now: number;
|
|
1312
|
+
frozen: boolean;
|
|
1313
|
+
autoAdvanceMs?: number;
|
|
1314
|
+
};
|
|
1315
|
+
seed?: number | string;
|
|
1316
|
+
/** Positions of the seeded random streams. */
|
|
1317
|
+
rng?: {
|
|
1318
|
+
state: number;
|
|
1319
|
+
faults?: number;
|
|
1320
|
+
latency?: number;
|
|
1321
|
+
};
|
|
1322
|
+
faults?: unknown;
|
|
1323
|
+
latency?: unknown;
|
|
1324
|
+
virtualTime?: boolean;
|
|
1325
|
+
};
|
|
1326
|
+
/** Controls for one namespace. */
|
|
1327
|
+
type NamespaceControls = {
|
|
1328
|
+
/** Seeds every random choice: fault rates, jitter, and whatever the service invents. */
|
|
1329
|
+
seed?: number | string;
|
|
1330
|
+
clock?: ClockControls;
|
|
1331
|
+
/**
|
|
1332
|
+
* Spend injected waits (latency, fault delays, timeouts) on the mock clock instead of the
|
|
1333
|
+
* wall clock: the request returns at once, the clock has moved, and the journal records
|
|
1334
|
+
* the wait exactly. Default `false`: waits are real, so a client's own timeout can fire.
|
|
1335
|
+
*/
|
|
1336
|
+
virtualTime?: boolean;
|
|
1337
|
+
/** Baseline response time for every vendor request. A bare duration is its `delay`. */
|
|
1338
|
+
latency?: Duration | LatencyControls;
|
|
1339
|
+
faults?: readonly FaultInput[];
|
|
1340
|
+
/** Start from this state instead of the service's own seed data. */
|
|
1341
|
+
snapshot?: SnapshotDocument;
|
|
1342
|
+
};
|
|
1343
|
+
/** {@link NamespaceControls} for every namespace, with per-namespace overrides. */
|
|
1344
|
+
type MockControls = NamespaceControls & {
|
|
1345
|
+
/** Vendor credential → namespace, for SDKs that cannot send a namespace header. */
|
|
1346
|
+
credentials?: Record<string, string>;
|
|
1347
|
+
/** Overrides for named namespaces. A key given here replaces the shared value. */
|
|
1348
|
+
namespaces?: Record<string, NamespaceControls>;
|
|
1349
|
+
};
|
|
1350
|
+
/** A latency rule in milliseconds. */
|
|
1351
|
+
type LatencyRule = {
|
|
1352
|
+
delayMs: number;
|
|
1353
|
+
jitterMs: number;
|
|
1354
|
+
};
|
|
1355
|
+
/** Baseline latency for a namespace, normalized. */
|
|
1356
|
+
type LatencyState = LatencyRule & {
|
|
1357
|
+
operations: Record<string, LatencyRule>;
|
|
1358
|
+
};
|
|
1359
|
+
/** What {@link controlHeaders} turns into request headers. */
|
|
1360
|
+
type ControlHeaderInput = {
|
|
1361
|
+
namespace?: string;
|
|
1362
|
+
adminKey?: string;
|
|
1363
|
+
branch?: string;
|
|
1364
|
+
at?: string;
|
|
1365
|
+
reset?: boolean;
|
|
1366
|
+
restore?: string;
|
|
1367
|
+
seed?: number | string;
|
|
1368
|
+
time?: Instant | Date;
|
|
1369
|
+
advance?: Duration;
|
|
1370
|
+
virtualTime?: boolean;
|
|
1371
|
+
delay?: Duration;
|
|
1372
|
+
timeout?: Duration;
|
|
1373
|
+
/** A status, `"drop"`, a preset name, or a fault rule. */
|
|
1374
|
+
fault?: number | string | Record<string, unknown>;
|
|
1375
|
+
snapshot?: string;
|
|
1163
1376
|
};
|
|
1164
1377
|
|
|
1165
1378
|
/**
|
|
@@ -1199,6 +1412,8 @@ type RequestLog = {
|
|
|
1199
1412
|
unmatched: boolean;
|
|
1200
1413
|
/** Set when a fault rule produced the response. */
|
|
1201
1414
|
faultId?: string;
|
|
1415
|
+
/** Milliseconds of injected wait: latency, fault delays and timeouts. Absent when none. */
|
|
1416
|
+
delayMs?: number;
|
|
1202
1417
|
/** Resource ids the handler touched (`userId`, `orderId`, …), when the service reports them. */
|
|
1203
1418
|
ids?: Record<string, string>;
|
|
1204
1419
|
/** Set when the service created a resource the request referred to but that did not exist. */
|
|
@@ -1244,6 +1459,12 @@ type JournalQuery = {
|
|
|
1244
1459
|
/** Only this namespace. Omit for every namespace, oldest first across all of them. */
|
|
1245
1460
|
namespace?: string;
|
|
1246
1461
|
operationId?: string;
|
|
1462
|
+
/** Only this HTTP method, case-insensitive. */
|
|
1463
|
+
method?: string;
|
|
1464
|
+
/** Only this exact path. */
|
|
1465
|
+
path?: string;
|
|
1466
|
+
/** Only requests this fault rule answered or shaped. */
|
|
1467
|
+
faultId?: string;
|
|
1247
1468
|
status?: number;
|
|
1248
1469
|
/** Only entries at or after this instant (epoch ms). */
|
|
1249
1470
|
since?: number;
|
|
@@ -1258,6 +1479,38 @@ type Journal = {
|
|
|
1258
1479
|
clear(namespace?: string): void;
|
|
1259
1480
|
};
|
|
1260
1481
|
|
|
1482
|
+
/**
|
|
1483
|
+
* Baseline response time, per namespace: how long every vendor request takes before any
|
|
1484
|
+
* fault is considered. Jitter draws from a stream the caller owns, one per namespace and
|
|
1485
|
+
* separate from the fault stream, so adding latency never shifts which requests a `rate`
|
|
1486
|
+
* fault hits.
|
|
1487
|
+
*/
|
|
1488
|
+
type LatencyRegistry = {
|
|
1489
|
+
get(namespace: string): LatencyState;
|
|
1490
|
+
set(namespace: string, state: LatencyState): LatencyState;
|
|
1491
|
+
/** Remove one namespace's latency, or every namespace's. */
|
|
1492
|
+
clear(namespace?: string): void;
|
|
1493
|
+
/** Milliseconds this request waits. Draws jitter, so call it once per request. */
|
|
1494
|
+
take(namespace: string, operationId: string | undefined): number;
|
|
1495
|
+
};
|
|
1496
|
+
|
|
1497
|
+
/** Clock state as the admin API reports it. */
|
|
1498
|
+
type ControlClock = ClockState & {
|
|
1499
|
+
/** `now`, as ISO-8601. */
|
|
1500
|
+
iso: string;
|
|
1501
|
+
/** Milliseconds the clock steps before every vendor request. */
|
|
1502
|
+
autoAdvanceMs: number;
|
|
1503
|
+
};
|
|
1504
|
+
/** One namespace's controls: the body of `GET /__admin/controls`. */
|
|
1505
|
+
type ControlState = {
|
|
1506
|
+
namespace: string;
|
|
1507
|
+
seed: number | string;
|
|
1508
|
+
clock: ControlClock;
|
|
1509
|
+
virtualTime: boolean;
|
|
1510
|
+
latency: LatencyState;
|
|
1511
|
+
faults: FaultListing[];
|
|
1512
|
+
};
|
|
1513
|
+
|
|
1261
1514
|
type AdminRequest = {
|
|
1262
1515
|
request: Request;
|
|
1263
1516
|
url: URL;
|
|
@@ -1274,6 +1527,17 @@ type AdminRoute = (request: AdminRequest) => Response | Promise<Response>;
|
|
|
1274
1527
|
* `:param` segments — e.g. `"POST /orders/:id/transition"`.
|
|
1275
1528
|
*/
|
|
1276
1529
|
type AdminRoutes = Record<string, AdminRoute>;
|
|
1530
|
+
/** What `GET /__admin/snapshots` lists for each snapshot. */
|
|
1531
|
+
type SnapshotInfo = {
|
|
1532
|
+
id: string;
|
|
1533
|
+
namespace: string;
|
|
1534
|
+
/** Stored rows in the snapshot. */
|
|
1535
|
+
records: number;
|
|
1536
|
+
/** The namespace clock when it was taken, epoch ms. */
|
|
1537
|
+
at: number;
|
|
1538
|
+
/** Whether `GET /snapshots/:id` can return it as a {@link SnapshotDocument}. */
|
|
1539
|
+
portable: boolean;
|
|
1540
|
+
};
|
|
1277
1541
|
|
|
1278
1542
|
/** Credential → namespace mapping behind `PUT /__admin/credentials`. */
|
|
1279
1543
|
type CredentialRegistry = {
|
|
@@ -1518,14 +1782,26 @@ type RuntimeOptions<T extends ServiceInstance> = {
|
|
|
1518
1782
|
sqlite?: SqliteClient;
|
|
1519
1783
|
/** Defaults to a live clock over `Date.now`. */
|
|
1520
1784
|
clock?: Clock;
|
|
1521
|
-
/** Seeds every random choice the runtime makes (fault rates). Default `0`. */
|
|
1785
|
+
/** Seeds every random choice the runtime makes (fault rates, jitter). Default `0`. */
|
|
1522
1786
|
seed?: number | string;
|
|
1787
|
+
/**
|
|
1788
|
+
* Admin controls to boot with: clock, latency, faults, a starting snapshot, credential
|
|
1789
|
+
* mappings and per-namespace overrides. `reset` returns a namespace to exactly this.
|
|
1790
|
+
*/
|
|
1791
|
+
adminControls?: MockControls;
|
|
1523
1792
|
/** Extra `GET /__admin/health` fields, such as the loaded corpus version. */
|
|
1524
1793
|
describe?: () => Record<string, unknown>;
|
|
1525
1794
|
/** Service-specific admin routes, given the runtime so they can reach any namespace. */
|
|
1526
1795
|
admin?: (runtime: ServiceRuntime<T>) => AdminRoutes;
|
|
1527
1796
|
/** Reserved tree for every internal HTTP endpoint, UI and namespace carrier. Default /__admin. */
|
|
1528
1797
|
adminPrefix?: string;
|
|
1798
|
+
/**
|
|
1799
|
+
* A namespace's clock was moved — by `/__admin/clock`, a header, a restore, a reset, or a
|
|
1800
|
+
* wait spent in virtual time. Run whatever the service schedules by that clock, so what
|
|
1801
|
+
* came due is seen at once and not on the next request. Moving the base clock in process
|
|
1802
|
+
* (`runtime.clock`) is the caller's own doing and is not reported here.
|
|
1803
|
+
*/
|
|
1804
|
+
onClockChange?: (namespace: string) => void;
|
|
1529
1805
|
/** Invalidate transient handles before replacing an existing instance's stored state. */
|
|
1530
1806
|
beforeRestore?: (instance: T) => void;
|
|
1531
1807
|
/** Require this value in `x-mockingbird-admin-key` on admin data routes. */
|
|
@@ -1543,7 +1819,10 @@ type RuntimeOptions<T extends ServiceInstance> = {
|
|
|
1543
1819
|
* `sigV4AccessKeyId`.
|
|
1544
1820
|
*/
|
|
1545
1821
|
credential?: (request: Request) => string | undefined;
|
|
1546
|
-
/**
|
|
1822
|
+
/**
|
|
1823
|
+
* Named faults, switched on with `POST /__admin/faults {"preset": "<name>"}`. They join the
|
|
1824
|
+
* standard presets every mock has; one with a standard name replaces it.
|
|
1825
|
+
*/
|
|
1547
1826
|
presets?: Record<string, FaultPreset>;
|
|
1548
1827
|
/** Outbound webhooks; adds the `/__admin/webhooks*` routes and clears on reset. */
|
|
1549
1828
|
webhooks?: WebhookHub;
|
|
@@ -1566,11 +1845,15 @@ type RuntimeOptions<T extends ServiceInstance> = {
|
|
|
1566
1845
|
type RuntimeIO = {
|
|
1567
1846
|
wallNow(): number;
|
|
1568
1847
|
monotonicNow(): number;
|
|
1569
|
-
|
|
1848
|
+
/** Wait on the wall clock. Rejects with the signal's reason when it aborts first. */
|
|
1849
|
+
sleep(ms: number, signal?: AbortSignal): Promise<void>;
|
|
1570
1850
|
};
|
|
1571
1851
|
type ServiceTimelineState = Readonly<{
|
|
1572
1852
|
snapshot: NamespaceSnapshot;
|
|
1573
|
-
clock
|
|
1853
|
+
/** `pinned`: the namespace's clock was frozen itself, not just following a frozen base. */
|
|
1854
|
+
clock: Readonly<ClockState & {
|
|
1855
|
+
pinned?: boolean;
|
|
1856
|
+
}>;
|
|
1574
1857
|
rngState: number;
|
|
1575
1858
|
}>;
|
|
1576
1859
|
type ServiceCheckpoint = Checkpoint<ServiceTimelineState>;
|
|
@@ -1583,14 +1866,18 @@ type ServiceRuntime<T extends ServiceInstance> = FetchAPI & {
|
|
|
1583
1866
|
readonly sqlite: SqliteClient;
|
|
1584
1867
|
readonly clock: Clock;
|
|
1585
1868
|
readonly faults: FaultRegistry;
|
|
1869
|
+
/** Baseline response time per namespace. */
|
|
1870
|
+
readonly latency: LatencyRegistry;
|
|
1586
1871
|
readonly metrics: Metrics;
|
|
1587
1872
|
readonly journal: Journal;
|
|
1588
1873
|
readonly rng: Rng;
|
|
1589
1874
|
readonly credentials: CredentialRegistry;
|
|
1590
1875
|
/** The webhook hub, when the service has outbound webhooks. */
|
|
1591
1876
|
readonly webhooks: WebhookHub | undefined;
|
|
1592
|
-
/**
|
|
1593
|
-
|
|
1877
|
+
/**
|
|
1878
|
+
* A namespace's clock. Each follows the base clock, {@link ServiceRuntime.clock}, with an
|
|
1879
|
+
* offset and a freeze of its own, so moving one never moves another.
|
|
1880
|
+
*/
|
|
1594
1881
|
namespaceClock(namespace?: string): Clock;
|
|
1595
1882
|
namespaceOf(request: Request): string;
|
|
1596
1883
|
/** Opaque in-process checkpoint including records, controls and webhook history. */
|
|
@@ -1602,8 +1889,38 @@ type ServiceRuntime<T extends ServiceInstance> = FetchAPI & {
|
|
|
1602
1889
|
instance(namespace?: string): T;
|
|
1603
1890
|
/** Public names of every namespace created so far. */
|
|
1604
1891
|
namespaces(): string[];
|
|
1605
|
-
/**
|
|
1892
|
+
/** Return one namespace to its boot state, or every namespace with `"*"`. */
|
|
1606
1893
|
reset(namespace?: string): Promise<void>;
|
|
1894
|
+
/** Reset a namespace and forget it, releasing everything it held. */
|
|
1895
|
+
dropNamespace(namespace: string): Promise<void>;
|
|
1896
|
+
/** A namespace's controls: seed, clock, virtual time, latency, faults and snapshots. */
|
|
1897
|
+
controls(namespace?: string): ControlState & {
|
|
1898
|
+
snapshots: SnapshotInfo[];
|
|
1899
|
+
};
|
|
1900
|
+
/** Apply a control document to a namespace. A given key replaces that control. */
|
|
1901
|
+
configure(controls: NamespaceControls, namespace?: string): ControlState & {
|
|
1902
|
+
snapshots: SnapshotInfo[];
|
|
1903
|
+
};
|
|
1904
|
+
/** Named snapshots of a namespace: records, clock, random streams, faults and latency. */
|
|
1905
|
+
readonly snapshots: {
|
|
1906
|
+
/** Capture the namespace now. Reusing a name replaces that snapshot. */
|
|
1907
|
+
create(options?: {
|
|
1908
|
+
name?: string;
|
|
1909
|
+
namespace?: string;
|
|
1910
|
+
}): SnapshotInfo;
|
|
1911
|
+
list(namespace?: string): SnapshotInfo[];
|
|
1912
|
+
/** The snapshot as portable JSON, to commit beside a suite or boot another mock from. */
|
|
1913
|
+
export(id: string, namespace?: string): SnapshotDocument;
|
|
1914
|
+
/** Store a document as a snapshot without restoring it. */
|
|
1915
|
+
import(document: SnapshotDocument, options?: {
|
|
1916
|
+
name?: string;
|
|
1917
|
+
namespace?: string;
|
|
1918
|
+
}): SnapshotInfo;
|
|
1919
|
+
restore(id: string, namespace?: string): void;
|
|
1920
|
+
delete(id: string, namespace?: string): boolean;
|
|
1921
|
+
};
|
|
1922
|
+
/** Request headers that carry controls, checked: spread them into a `fetch` or an SDK's defaults. */
|
|
1923
|
+
headers(input: ControlHeaderInput): Record<string, string>;
|
|
1607
1924
|
snapshot(namespace?: string): NamespaceSnapshot;
|
|
1608
1925
|
restore(snapshot: NamespaceSnapshot, namespace?: string): void;
|
|
1609
1926
|
/** Capture the current branch. Mutating HTTP calls do this automatically. */
|
|
@@ -1624,7 +1941,7 @@ type ServiceRuntime<T extends ServiceInstance> = FetchAPI & {
|
|
|
1624
1941
|
state(namespace?: string): StateView;
|
|
1625
1942
|
};
|
|
1626
1943
|
|
|
1627
|
-
type GoogleRuntimeOptions = Pick<RuntimeOptions<GoogleAPI>, "sqlite" | "clock" | "seed" | "adminPrefix" | "adminKey" | "onLog" | "journalSize" | "maxCheckpoints"> & Pick<GoogleAPIOptions, "fixtures" | "baseUrl" | "tokens">;
|
|
1944
|
+
type GoogleRuntimeOptions = Pick<RuntimeOptions<GoogleAPI>, "sqlite" | "clock" | "seed" | "adminPrefix" | "adminKey" | "adminControls" | "onLog" | "journalSize" | "maxCheckpoints"> & Pick<GoogleAPIOptions, "fixtures" | "baseUrl" | "tokens">;
|
|
1628
1945
|
type GoogleRuntime = ServiceRuntime<GoogleAPI>;
|
|
1629
1946
|
declare function createRuntime(options?: GoogleRuntimeOptions): GoogleRuntime;
|
|
1630
1947
|
|
package/dist/index.js
CHANGED