@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/CHANGELOG.md +11 -1
- package/DISCOVERY.md +23 -0
- package/README.md +17 -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-GFJTN44G.js +7567 -0
- package/dist/chunk-GFJTN44G.js.map +7 -0
- package/dist/{chunk-27QTGSE7.js → chunk-VWCTZQML.js} +136 -25
- package/dist/chunk-VWCTZQML.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-27QTGSE7.js.map +0 -7
- package/dist/chunk-NG4GI7NA.js +0 -5769
- package/dist/chunk-NG4GI7NA.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
|
@@ -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
|
|
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
|
|
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
|
-
*
|
|
1004
|
-
*
|
|
1005
|
-
|
|
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
|
-
/**
|
|
1012
|
-
|
|
1013
|
-
/**
|
|
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
|
-
/**
|
|
1033
|
-
|
|
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
|
-
|
|
1068
|
-
|
|
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
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
1080
|
-
|
|
1081
|
-
|
|
1082
|
-
|
|
1083
|
-
|
|
1084
|
-
|
|
1085
|
-
|
|
1086
|
-
|
|
1087
|
-
|
|
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
|
-
/**
|
|
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
|
-
|
|
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
|
|
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
|
-
/**
|
|
1527
|
-
|
|
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
|
-
/**
|
|
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
|
|