@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/CHANGELOG.md +11 -1
- package/DISCOVERY.md +23 -0
- package/README.md +15 -3
- package/dist/chunk-2M4V3TBY.js +6900 -0
- package/dist/chunk-2M4V3TBY.js.map +7 -0
- 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-FRHQ7ANR.js → chunk-P52TRCEH.js} +136 -25
- package/dist/chunk-P52TRCEH.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-FRHQ7ANR.js.map +0 -7
- package/dist/chunk-T3D2FSIN.js +0 -5102
- package/dist/chunk-T3D2FSIN.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
|
@@ -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
|
|
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
|
|
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
|
-
*
|
|
1002
|
-
*
|
|
1003
|
-
|
|
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
|
-
/**
|
|
1010
|
-
|
|
1011
|
-
/**
|
|
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
|
-
/**
|
|
1031
|
-
|
|
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
|
-
|
|
1066
|
-
|
|
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
|
-
|
|
1076
|
-
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
1080
|
-
|
|
1081
|
-
|
|
1082
|
-
|
|
1083
|
-
|
|
1084
|
-
|
|
1085
|
-
|
|
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
|
-
/**
|
|
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
|
-
|
|
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
|
|
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
|
-
/**
|
|
1525
|
-
|
|
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
|
-
/**
|
|
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