@crvouga/mockingbird-service-aha 0.2.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +14 -1
- package/README.md +10 -7
- package/dist/{chunk-VJVM4I3P.js → chunk-J4SN6IVE.js} +7 -5
- package/dist/chunk-J4SN6IVE.js.map +7 -0
- package/dist/{chunk-HEWJBQGW.js → chunk-X63I2JY7.js} +121 -43
- package/dist/chunk-X63I2JY7.js.map +7 -0
- package/dist/cli.js +2 -2
- package/dist/index.d.ts +134 -106
- package/dist/index.js +1 -1
- package/dist/server.d.ts +236 -180
- package/dist/server.js +2 -2
- package/package.json +7 -2
- package/dist/chunk-HEWJBQGW.js.map +0 -7
- package/dist/chunk-VJVM4I3P.js.map +0 -7
package/dist/cli.js
CHANGED
package/dist/index.d.ts
CHANGED
|
@@ -228,6 +228,133 @@ type FaultRegistry = {
|
|
|
228
228
|
take(candidate: FaultCandidate): Promise<FaultHit[]>;
|
|
229
229
|
};
|
|
230
230
|
|
|
231
|
+
/** A stable identifier for a point in a {@link Timeline}. */
|
|
232
|
+
type CheckpointId = string;
|
|
233
|
+
/** An immutable node in a timeline's checkpoint DAG. */
|
|
234
|
+
type Checkpoint<T> = Readonly<{
|
|
235
|
+
id: CheckpointId;
|
|
236
|
+
branch: string;
|
|
237
|
+
parent: CheckpointId | null;
|
|
238
|
+
/** Logical time supplied by the timeline's injected clock. */
|
|
239
|
+
at: number;
|
|
240
|
+
value: T;
|
|
241
|
+
}>;
|
|
242
|
+
type TimelineOptions = {
|
|
243
|
+
/** Logical clock used to stamp checkpoints. Defaults to a deterministic counter. */
|
|
244
|
+
now?: () => number;
|
|
245
|
+
/** Maximum retained checkpoints. Branch heads are never collected. Default 1,000. */
|
|
246
|
+
maxCheckpoints?: number;
|
|
247
|
+
/** Customize deterministic checkpoint IDs. */
|
|
248
|
+
id?: (sequence: number) => CheckpointId;
|
|
249
|
+
};
|
|
250
|
+
type CommitOptions = {
|
|
251
|
+
branch?: string;
|
|
252
|
+
/** Parent checkpoint. Defaults to the selected branch's current head. */
|
|
253
|
+
parent?: CheckpointId | null;
|
|
254
|
+
};
|
|
255
|
+
type ForkOptions = {
|
|
256
|
+
/** Checkpoint to fork from. Defaults to the main branch's head. */
|
|
257
|
+
from?: CheckpointId;
|
|
258
|
+
};
|
|
259
|
+
/**
|
|
260
|
+
* Small, storage-agnostic checkpoint DAG shared by service runtimes. Its values may be immutable
|
|
261
|
+
* records, namespace images, or copy-on-write SQL engine snapshots.
|
|
262
|
+
*
|
|
263
|
+
* Values are retained by reference. Engines can therefore use persistent/COW snapshots while
|
|
264
|
+
* simpler services can use immutable values. IDs and GC order are deterministic, and all IO
|
|
265
|
+
* (the logical clock) is injected.
|
|
266
|
+
*/
|
|
267
|
+
declare class Timeline<T> {
|
|
268
|
+
readonly maxCheckpoints: number;
|
|
269
|
+
private readonly now;
|
|
270
|
+
private readonly makeId;
|
|
271
|
+
private readonly nodes;
|
|
272
|
+
private readonly heads;
|
|
273
|
+
/** Unreferenced nodes in the exact order they became collectible. */
|
|
274
|
+
private readonly evictable;
|
|
275
|
+
/** Branch heads plus explicit retainers. Absent means zero. */
|
|
276
|
+
private readonly references;
|
|
277
|
+
private readonly explicitPins;
|
|
278
|
+
private sequence;
|
|
279
|
+
constructor(options?: TimelineOptions);
|
|
280
|
+
/** Capture a new immutable value and move `branch` to it. */
|
|
281
|
+
commit(value: T, options?: CommitOptions): Checkpoint<T>;
|
|
282
|
+
/** Create a branch pointer without copying its checkpoint value. */
|
|
283
|
+
fork(branch: string, options?: ForkOptions): Checkpoint<T> | undefined;
|
|
284
|
+
/** Move a branch pointer to an existing checkpoint. */
|
|
285
|
+
checkout(branch: string, id: CheckpointId): Checkpoint<T>;
|
|
286
|
+
get(id: CheckpointId): Checkpoint<T>;
|
|
287
|
+
head(branch?: string): Checkpoint<T> | undefined;
|
|
288
|
+
hasBranch(branch: string): boolean;
|
|
289
|
+
branches(): Readonly<Record<string, CheckpointId>>;
|
|
290
|
+
checkpoints(): readonly Checkpoint<T>[];
|
|
291
|
+
/** Number of retained checkpoints without allocating an array. */
|
|
292
|
+
get size(): number;
|
|
293
|
+
/** Pin a checkpoint independently of branch heads (used by compatibility snapshot handles). */
|
|
294
|
+
retain(id: CheckpointId): Checkpoint<T>;
|
|
295
|
+
/** Release one explicit pin. Branch heads remain pinned until moved or deleted. */
|
|
296
|
+
release(id: CheckpointId): boolean;
|
|
297
|
+
deleteBranch(branch: string): boolean;
|
|
298
|
+
/**
|
|
299
|
+
* Deterministically discard oldest unpinned checkpoints. Collection is O(number removed):
|
|
300
|
+
* commits never scan pinned nodes or the retained history. Parents are metadata rather than a
|
|
301
|
+
* storage dependency, so a retained node remains usable after pruning.
|
|
302
|
+
*/
|
|
303
|
+
gc(max?: number): CheckpointId[];
|
|
304
|
+
private collect;
|
|
305
|
+
private moveHead;
|
|
306
|
+
private addReference;
|
|
307
|
+
private removeReference;
|
|
308
|
+
private assertBranch;
|
|
309
|
+
}
|
|
310
|
+
|
|
311
|
+
/**
|
|
312
|
+
* Anything that can answer a Fetch `Request` with a `Response`.
|
|
313
|
+
*
|
|
314
|
+
* Every Mockingbird service implements this, and every runtime adapter consumes it.
|
|
315
|
+
* It is the only contract shared across the whole graph.
|
|
316
|
+
*/
|
|
317
|
+
interface FetchAPI {
|
|
318
|
+
fetch(request: Request): Promise<Response>;
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
/** Options every provider constructor accepts. */
|
|
322
|
+
type APIOptions = {
|
|
323
|
+
/** Sync SQLite client. Defaults to `@crvouga/mockingbird-service-sqlite`. */
|
|
324
|
+
sqlite?: SqliteClient$1;
|
|
325
|
+
/** Clock used for `created`-style fields. Default `Date.now`. */
|
|
326
|
+
now?: () => number;
|
|
327
|
+
/**
|
|
328
|
+
* Storage namespace for this instance's records. Instances sharing one SQLite
|
|
329
|
+
* client stay isolated when their namespaces differ. Defaults to the service name.
|
|
330
|
+
*/
|
|
331
|
+
namespace?: string;
|
|
332
|
+
};
|
|
333
|
+
|
|
334
|
+
/**
|
|
335
|
+
* One problem with a request body, at a dotted path (`patient.address.city`, `items.0.sku`).
|
|
336
|
+
* `kind` is `media_type` when the body is present but its media type is not one the operation
|
|
337
|
+
* accepts (a `415` on most vendors), `syntax` when it could not be decoded, `required` when
|
|
338
|
+
* the operation needs a body and none arrived, and `schema` for a contract violation.
|
|
339
|
+
*/
|
|
340
|
+
type BodyIssue = {
|
|
341
|
+
path: string;
|
|
342
|
+
message: string;
|
|
343
|
+
kind?: "media_type" | "syntax" | "required" | "schema";
|
|
344
|
+
};
|
|
345
|
+
|
|
346
|
+
/**
|
|
347
|
+
* What the mock received from a request it rejected, so a 4xx can be attributed after the
|
|
348
|
+
* fact (an empty body, a missing `content-type`, a schema violation) without logging the body.
|
|
349
|
+
*/
|
|
350
|
+
type RejectedRequest = {
|
|
351
|
+
/** The raw `content-type` header, or `null` when the request sent none. */
|
|
352
|
+
contentType: string | null;
|
|
353
|
+
/** Bytes of body received from `content-length` (`0` for none), or `null` when the client sent no length (a streamed / chunked body). */
|
|
354
|
+
bodyBytes: number | null;
|
|
355
|
+
/** The raw `transfer-encoding` header (`chunked`), or `null`. */
|
|
356
|
+
transferEncoding: string | null;
|
|
357
|
+
};
|
|
231
358
|
/** One handled request, as the structured log sees it. */
|
|
232
359
|
type RequestLog = {
|
|
233
360
|
service: string;
|
|
@@ -245,6 +372,10 @@ type RequestLog = {
|
|
|
245
372
|
ids?: Record<string, string>;
|
|
246
373
|
/** Set when the service created a resource the request referred to but that did not exist. */
|
|
247
374
|
adopted?: boolean;
|
|
375
|
+
/** Set on a rejection (status ≥ 400) the mock produced itself, never on a scripted fault. */
|
|
376
|
+
request?: RejectedRequest;
|
|
377
|
+
/** The validation issues behind a rejection, when the service found any. */
|
|
378
|
+
issues?: BodyIssue[];
|
|
248
379
|
};
|
|
249
380
|
type MetricsReport = {
|
|
250
381
|
requests: number;
|
|
@@ -334,96 +465,6 @@ declare class IdSequence {
|
|
|
334
465
|
next(prefix: string, length?: number): string;
|
|
335
466
|
}
|
|
336
467
|
|
|
337
|
-
/** A stable identifier for a point in a {@link Timeline}. */
|
|
338
|
-
type CheckpointId = string;
|
|
339
|
-
/** An immutable node in a timeline's checkpoint DAG. */
|
|
340
|
-
type Checkpoint<T> = Readonly<{
|
|
341
|
-
id: CheckpointId;
|
|
342
|
-
branch: string;
|
|
343
|
-
parent: CheckpointId | null;
|
|
344
|
-
/** Logical time supplied by the timeline's injected clock. */
|
|
345
|
-
at: number;
|
|
346
|
-
value: T;
|
|
347
|
-
}>;
|
|
348
|
-
type TimelineOptions = {
|
|
349
|
-
/** Logical clock used to stamp checkpoints. Defaults to a deterministic counter. */
|
|
350
|
-
now?: () => number;
|
|
351
|
-
/** Maximum retained checkpoints. Branch heads are never collected. Default 1,000. */
|
|
352
|
-
maxCheckpoints?: number;
|
|
353
|
-
/** Customize deterministic checkpoint IDs. */
|
|
354
|
-
id?: (sequence: number) => CheckpointId;
|
|
355
|
-
};
|
|
356
|
-
type CommitOptions = {
|
|
357
|
-
branch?: string;
|
|
358
|
-
/** Parent checkpoint. Defaults to the selected branch's current head. */
|
|
359
|
-
parent?: CheckpointId | null;
|
|
360
|
-
};
|
|
361
|
-
type ForkOptions = {
|
|
362
|
-
/** Checkpoint to fork from. Defaults to the main branch's head. */
|
|
363
|
-
from?: CheckpointId;
|
|
364
|
-
};
|
|
365
|
-
/**
|
|
366
|
-
* Small, storage-agnostic checkpoint DAG shared by service runtimes. Its values may be immutable
|
|
367
|
-
* records, namespace images, or copy-on-write SQL engine snapshots.
|
|
368
|
-
*
|
|
369
|
-
* Values are retained by reference. Engines can therefore use persistent/COW snapshots while
|
|
370
|
-
* simpler services can use immutable values. IDs and GC order are deterministic, and all IO
|
|
371
|
-
* (the logical clock) is injected.
|
|
372
|
-
*/
|
|
373
|
-
declare class Timeline<T> {
|
|
374
|
-
readonly maxCheckpoints: number;
|
|
375
|
-
private readonly now;
|
|
376
|
-
private readonly makeId;
|
|
377
|
-
private readonly nodes;
|
|
378
|
-
private readonly heads;
|
|
379
|
-
/** Unreferenced nodes in the exact order they became collectible. */
|
|
380
|
-
private readonly evictable;
|
|
381
|
-
/** Branch heads plus explicit retainers. Absent means zero. */
|
|
382
|
-
private readonly references;
|
|
383
|
-
private readonly explicitPins;
|
|
384
|
-
private sequence;
|
|
385
|
-
constructor(options?: TimelineOptions);
|
|
386
|
-
/** Capture a new immutable value and move `branch` to it. */
|
|
387
|
-
commit(value: T, options?: CommitOptions): Checkpoint<T>;
|
|
388
|
-
/** Create a branch pointer without copying its checkpoint value. */
|
|
389
|
-
fork(branch: string, options?: ForkOptions): Checkpoint<T> | undefined;
|
|
390
|
-
/** Move a branch pointer to an existing checkpoint. */
|
|
391
|
-
checkout(branch: string, id: CheckpointId): Checkpoint<T>;
|
|
392
|
-
get(id: CheckpointId): Checkpoint<T>;
|
|
393
|
-
head(branch?: string): Checkpoint<T> | undefined;
|
|
394
|
-
hasBranch(branch: string): boolean;
|
|
395
|
-
branches(): Readonly<Record<string, CheckpointId>>;
|
|
396
|
-
checkpoints(): readonly Checkpoint<T>[];
|
|
397
|
-
/** Number of retained checkpoints without allocating an array. */
|
|
398
|
-
get size(): number;
|
|
399
|
-
/** Pin a checkpoint independently of branch heads (used by compatibility snapshot handles). */
|
|
400
|
-
retain(id: CheckpointId): Checkpoint<T>;
|
|
401
|
-
/** Release one explicit pin. Branch heads remain pinned until moved or deleted. */
|
|
402
|
-
release(id: CheckpointId): boolean;
|
|
403
|
-
deleteBranch(branch: string): boolean;
|
|
404
|
-
/**
|
|
405
|
-
* Deterministically discard oldest unpinned checkpoints. Collection is O(number removed):
|
|
406
|
-
* commits never scan pinned nodes or the retained history. Parents are metadata rather than a
|
|
407
|
-
* storage dependency, so a retained node remains usable after pruning.
|
|
408
|
-
*/
|
|
409
|
-
gc(max?: number): CheckpointId[];
|
|
410
|
-
private collect;
|
|
411
|
-
private moveHead;
|
|
412
|
-
private addReference;
|
|
413
|
-
private removeReference;
|
|
414
|
-
private assertBranch;
|
|
415
|
-
}
|
|
416
|
-
|
|
417
|
-
/**
|
|
418
|
-
* Anything that can answer a Fetch `Request` with a `Response`.
|
|
419
|
-
*
|
|
420
|
-
* Every Mockingbird service implements this, and every runtime adapter consumes it.
|
|
421
|
-
* It is the only contract shared across the whole graph.
|
|
422
|
-
*/
|
|
423
|
-
interface FetchAPI {
|
|
424
|
-
fetch(request: Request): Promise<Response>;
|
|
425
|
-
}
|
|
426
|
-
|
|
427
468
|
/**
|
|
428
469
|
* A point-in-time copy of everything a service namespace holds.
|
|
429
470
|
*
|
|
@@ -574,19 +615,6 @@ type ServiceRuntime<T extends ServiceInstance> = FetchAPI & {
|
|
|
574
615
|
timeline(namespace?: string): Timeline<ServiceTimelineState>;
|
|
575
616
|
};
|
|
576
617
|
|
|
577
|
-
/** Options every provider constructor accepts. */
|
|
578
|
-
type APIOptions = {
|
|
579
|
-
/** Sync SQLite client. Defaults to `@crvouga/mockingbird-service-sqlite`. */
|
|
580
|
-
sqlite?: SqliteClient$1;
|
|
581
|
-
/** Clock used for `created`-style fields. Default `Date.now`. */
|
|
582
|
-
now?: () => number;
|
|
583
|
-
/**
|
|
584
|
-
* Storage namespace for this instance's records. Instances sharing one SQLite
|
|
585
|
-
* client stay isolated when their namespaces differ. Defaults to the service name.
|
|
586
|
-
*/
|
|
587
|
-
namespace?: string;
|
|
588
|
-
};
|
|
589
|
-
|
|
590
618
|
/** Bind values accepted by Mockingbird's SQLite port (matches sqlite-mem / better-sqlite3). */
|
|
591
619
|
type SqliteValue = null | number | bigint | string | Uint8Array | boolean;
|
|
592
620
|
/** Mutation counters returned by {@link SqliteStatement.run}. */
|
|
@@ -659,7 +687,7 @@ type Settings = {
|
|
|
659
687
|
* secret has its signature verified exactly.
|
|
660
688
|
*/
|
|
661
689
|
credentials: ApiCredential[];
|
|
662
|
-
/** Accept `X
|
|
690
|
+
/** Accept `X-<Partner>-Auth-Key` (legacy mode). Default true. */
|
|
663
691
|
allowLegacy: boolean;
|
|
664
692
|
/** Reject an `X-TIMESTAMP` further than this from wall-clock time; 0 disables. Default 5 min. */
|
|
665
693
|
timestampToleranceMs: number;
|
|
@@ -975,11 +1003,11 @@ type AhaAPIOptions = APIOptions & {
|
|
|
975
1003
|
};
|
|
976
1004
|
/**
|
|
977
1005
|
* Verify AHA partner authentication: HMAC mode (`X-API-KEY`, `X-TIMESTAMP`,
|
|
978
|
-
* `X-SIGNATURE` over `"<apiKey>:<path>:<timestamp>"`) or legacy `X
|
|
1006
|
+
* `X-SIGNATURE` over `"<apiKey>:<path>:<timestamp>"`) or legacy `X-<Partner>-Auth-Key`.
|
|
979
1007
|
* Returns an error message, or `undefined` when the request is authentic.
|
|
980
1008
|
*/
|
|
981
1009
|
declare const verifyAuth: (request: Request, path: string, settings: Settings, wallNow: number) => Promise<string | undefined>;
|
|
982
|
-
/** The credential a request carries (`X-API-KEY`, else `X
|
|
1010
|
+
/** The credential a request carries (`X-API-KEY`, else `X-<Partner>-Auth-Key`), for namespaces. */
|
|
983
1011
|
declare const apiKeyCredential: (request: Request) => string | undefined;
|
|
984
1012
|
/**
|
|
985
1013
|
* Stateful mock of the AHA partner API.
|