@yolk-sdk/emulators 0.1.0-canary.96

package/dist/r2.d.mts

@@ -0,0 +1,166 @@
+import { EmulatorEvidence, EmulatorRouteEvidence } from "./route-evidence.mjs";
+import { R2EmulatorFailure, R2EmulatorFixture, r2EmulatorFixtures } from "./r2-fixtures.mjs";
+import * as Schema from "effect/Schema";
+
+//#region src/r2.d.ts
+/** The presigner port the presign fixture and manifest route name. */
+declare const r2EmulatorPresignerPort = "R2Presigner";
+/** The object-client port the get and put fixtures and manifest routes name. */
+declare const r2EmulatorObjectClientPort = "R2ObjectClient";
+/** Manifest routes of port emulators use this pseudo method; `path` is `<Port>.<method>`. */
+declare const r2EmulatorRouteMethod = "PORT";
+/**
+ * Route evidence manifest: every emulated port method (`PORT <Port>.<method>`) and the R2
+ * conformance cases whose (synthetic, unverified) fixtures it follows. `R2ObjectClient.put` is an
+ * unverified connector write: it needs a pending entry in the repo's evidence check until an
+ * owner-approved live run against a practice bucket verifies it. Presigning is local signing and
+ * `get` reads, so neither is a write.
+ */
+declare const r2EmulatorRoutes: ReadonlyArray<EmulatorRouteEvidence>;
+/** One object in the emulated bucket: its key, its etag (quotes kept), and its bytes as base64. */
+declare const R2EmulatorObject: Schema.Struct<{
+  readonly key: Schema.String;
+  readonly etag: Schema.String;
+  readonly bodyBase64: Schema.String;
+}>;
+type R2EmulatorObject = typeof R2EmulatorObject.Type;
+declare const R2EmulatorBucket: Schema.Struct<{
+  readonly name: Schema.String;
+  readonly objects: Schema.$Array<Schema.Struct<{
+    readonly key: Schema.String;
+    readonly etag: Schema.String;
+    readonly bodyBase64: Schema.String;
+  }>>;
+}>;
+type R2EmulatorBucket = typeof R2EmulatorBucket.Type;
+/** The emulated buckets: plain JSON, used both as the seed and as the `state()` snapshot. */
+declare const R2EmulatorSeed: Schema.Struct<{
+  readonly buckets: Schema.$Array<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly objects: Schema.$Array<Schema.Struct<{
+      readonly key: Schema.String;
+      readonly etag: Schema.String;
+      readonly bodyBase64: Schema.String;
+    }>>;
+  }>>;
+}>;
+type R2EmulatorSeed = typeof R2EmulatorSeed.Type;
+/**
+ * The synthetic practice bucket the R2 fixtures describe (the default seed): the seeded object the
+ * get fixtures read, with the etag and bytes they answer.
+ */
+declare const r2EmulatorDefaultSeed: R2EmulatorSeed;
+/**
+ * A fault: answer the next `count` calls (every one when omitted) of `port` and `method` whose
+ * credential-free request contains `match` (a deep subset: objects by key, arrays element by
+ * element, other values exactly) with `failure` instead of a fixture. Faults apply only to a call a
+ * fixture would answer, and change no bucket state.
+ */
+declare const R2EmulatorFault: Schema.Struct<{
+  readonly kind: Schema.Literal<"failure">;
+  readonly port: Schema.String;
+  readonly method: Schema.String;
+  readonly match: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+  readonly count: Schema.optionalKey<Schema.Int>;
+  readonly failure: Schema.Struct<{
+    readonly kind: Schema.Literals<readonly ["expected", "error"]>;
+    readonly code: Schema.String;
+    readonly message: Schema.String;
+    readonly status: Schema.optionalKey<Schema.Int>;
+  }>;
+}>;
+type R2EmulatorFault = typeof R2EmulatorFault.Type;
+type R2EmulatorFaultState = {
+  readonly id: number;
+  readonly fault: R2EmulatorFault; /** Remaining matching calls; `undefined` for an unlimited fault. */
+  readonly remaining: number | undefined;
+  readonly applied: number;
+};
+declare const R2EmulatorInputInvalid_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => import("effect/Cause").YieldableError & {
+  readonly _tag: "R2EmulatorInputInvalid";
+} & Readonly<A>;
+/** Thrown by `makeR2Emulator` (invalid seed) and `faults.add` (invalid fault). */
+declare class R2EmulatorInputInvalid extends R2EmulatorInputInvalid_base<{
+  readonly input: 'seed' | 'fault';
+  readonly reason: string;
+}> {
+  get message(): string;
+}
+/** Why a call failed closed. */
+type R2EmulatorNotEmulatedReason = 'unknown-method' | 'invalid-request' | 'uncheckable-body' | 'credential-in-request' | 'uncheckable-request' | 'no-matching-fixture' | 'state-conflict';
+/** The constant port, method, and request of a ledger entry that records nothing it received. */
+declare const r2EmulatorRedacted = "<redacted>";
+declare const r2EmulatorUnrecognised = "<unrecognised>";
+/** One emulator answer; structurally the reply of a plain-JSON `R2Backend`. */
+type R2EmulatorReply = {
+  readonly response: Schema.Json;
+} | {
+  readonly failure: R2EmulatorFailure;
+} | {
+  readonly notEmulated: {
+    readonly reason: string;
+  };
+};
+type R2EmulatorLedgerEntry = {
+  readonly seq: number; /** The port, or `<unrecognised>` for an `unknown-method` or `uncheckable-request` refusal. */
+  readonly port: string; /** The method, or `<unrecognised>` for an `unknown-method` or `uncheckable-request` refusal. */
+  readonly method: string;
+  /**
+   * For an answered or faulted call, the request without credential fields (a fixture request) with
+   * every `bodyBase64` value replaced by `<redacted>`; `<redacted>` whole for every refusal.
+   */
+  readonly request: Schema.Json; /** The decoded byte length of a recorded request's top-level `bodyBase64`. */
+  readonly bodyBytes?: number;
+  readonly outcome: 'answered' | 'fault' | 'not-emulated'; /** `unknown-method` for a call outside the manifest. */
+  readonly evidence: EmulatorEvidence | 'unknown-method';
+  readonly fixtureId?: string;
+  readonly faultId?: number;
+  readonly reason?: R2EmulatorNotEmulatedReason;
+};
+type R2EmulatorRouteCoverage = EmulatorRouteEvidence & {
+  /** Ledger calls to this route since the last ledger clear or reset. */readonly calls: number;
+};
+type R2EmulatorCoverage = {
+  readonly routes: ReadonlyArray<R2EmulatorRouteCoverage>; /** Ledger calls that failed closed. */
+  readonly notEmulatedCalls: number; /** Fixtures that have not answered a call since the emulator was made or last reset. */
+  readonly unusedFixtureIds: ReadonlyArray<string>;
+};
+type R2EmulatorOptions = {
+  /** The initial buckets. Defaults to `r2EmulatorDefaultSeed`. */readonly seed?: R2EmulatorSeed;
+};
+type R2Emulator = {
+  /** Answer one R2 port call; never throws. This makes the emulator an `R2Backend`. */readonly call: (port: string, method: string, request: Schema.Json) => R2EmulatorReply; /** The current buckets (a copy). */
+  readonly state: () => R2EmulatorSeed; /** The seed the emulator started from (a copy). */
+  readonly seed: () => R2EmulatorSeed;
+  readonly ledger: {
+    readonly entries: () => ReadonlyArray<R2EmulatorLedgerEntry>;
+    readonly clear: () => void;
+  }; /** Clear the ledger and faults, forget fixture use, and restore the seeded buckets. */
+  readonly reset: () => void;
+  readonly faults: {
+    readonly add: (fault: R2EmulatorFault) => R2EmulatorFaultState;
+    readonly list: () => ReadonlyArray<R2EmulatorFaultState>;
+    readonly clear: () => void;
+  };
+  readonly coverage: () => R2EmulatorCoverage;
+};
+/**
+ * Create an R2 emulator. Each call has its own buckets, ledger, faults, and fixture use.
+ *
+ * `call(port, method, request)` answers in this order: a port and method outside the manifest
+ * (`unknown-method`), a non-object request or one with an own `__proto__` key (`invalid-request`),
+ * a `bodyBase64` that is not canonical base64 of UTF-8 text (`uncheckable-body`), or a credential
+ * outside the credential fields (`credential-in-request`) fails closed; otherwise the fixtures
+ * whose port, method, and credential-free request match are checked against the buckets, and the
+ * first consistent one (preferring one not used since the last reset) is chosen; no match
+ * (`no-matching-fixture`) or no consistent match (`state-conflict`) fails closed. Only then does
+ * the first active matching fault answer its failure (changing nothing); otherwise the chosen
+ * fixture answers and updates the buckets. Every refusal is ledgered with constant text only; a
+ * request the checks cannot walk is refused as `uncheckable-request`, so `call` never throws.
+ *
+ * Throws `R2EmulatorInputInvalid` for an invalid seed.
+ */
+declare const makeR2Emulator: (options?: R2EmulatorOptions) => R2Emulator;
+//#endregion
+export { type EmulatorEvidence, type EmulatorRouteEvidence, R2Emulator, R2EmulatorBucket, R2EmulatorCoverage, type R2EmulatorFailure, R2EmulatorFault, R2EmulatorFaultState, type R2EmulatorFixture, R2EmulatorInputInvalid, R2EmulatorLedgerEntry, R2EmulatorNotEmulatedReason, R2EmulatorObject, R2EmulatorOptions, R2EmulatorReply, R2EmulatorRouteCoverage, R2EmulatorSeed, makeR2Emulator, r2EmulatorDefaultSeed, r2EmulatorFixtures, r2EmulatorObjectClientPort, r2EmulatorPresignerPort, r2EmulatorRedacted, r2EmulatorRouteMethod, r2EmulatorRoutes, r2EmulatorUnrecognised };
+//# sourceMappingURL=r2.d.mts.map

package/dist/r2.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2.d.mts","names":[],"sources":["../src/r2.ts"],"mappings":";;;;;AAqFA;AAAA,cAAa,uBAAA;;cAGA,0BAAA;AAHuB;AAAA,cAMvB,qBAAA;;;;AAH0B;AAGvC;;;cAoCa,gBAAA,EAAkB,aAAa,CAAC,qBAAA;AApCX;AAAA,cAyErB,gBAAA,EAAgB,MAAA,CAAA,MAAA;EAAA;;;;KAMjB,gBAAA,UAA0B,gBAAA,CAAiB,IAAI;AAAA,cAE9C,gBAAA,EAAgB,MAAA,CAAA,MAAA;EAAA;;;;;;;KAKjB,gBAAA,UAA0B,gBAAA,CAAiB,IAAI;;cAG9C,cAAA,EAAc,MAAA,CAAA,MAAA;EAAA;;;;;;;;;KAIf,cAAA,UAAwB,cAAA,CAAe,IAAI;AAdvD;;;;AAAA,cAoBa,qBAAA,EAAuB,cAanC;AA/BD;;;;;;AAAA,cA8Ca,eAAA,EAAe,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;;KAShB,eAAA,UAAyB,eAAA,CAAgB,IAAI;AAAA,KAE7C,oBAAA;EAAA,SACD,EAAA;EAAA,SACA,KAAA,EAAO,eAAe;WAEtB,SAAA;EAAA,SACA,OAAA;AAAA;AAAA,cACV,2BAAA;;;;cAGY,sBAAA,SAA+B,2BAAA;EAAA,SACjC,KAAA;EAAA,SACA,MAAA;AAAA;EAAA,IAEI,OAAA,CAAA;AAAA;AAjE4C;AAAA,KAuE/C,2BAAA;;cAqBC,kBAAA;AAAA,cAEA,sBAAA;;KAGD,eAAA;EAAA,SACG,QAAA,EAAU,MAAA,CAAO,IAAA;AAAA;EAAA,SACjB,OAAA,EAAS,iBAAiB;AAAA;EAAA,SAC1B,WAAA;IAAA,SAAwB,MAAA;EAAA;AAAA;AAAA,KAE3B,qBAAA;EAAA,SACD,GAAA;WAEA,IAAA;WAEA,MAAA;;;;;WAKA,OAAA,EAAS,MAAA,CAAO,IAAA;WAEhB,SAAA;EAAA,SACA,OAAA;WAEA,QAAA,EAAU,gBAAA;EAAA,SACV,SAAA;EAAA,SACA,OAAA;EAAA,SACA,MAAA,GAAS,2BAAA;AAAA;AAAA,KAGR,uBAAA,GAA0B,qBAAqB;kFAEhD,KAAK;AAAA;AAAA,KAGJ,kBAAA;EAAA,SACD,MAAA,EAAQ,aAAA,CAAc,uBAAA,GA1HrB;EAAA,SA4HD,gBAAA;WAEA,gBAAA,EAAkB,aAAA;AAAA;AAAA,KAGjB,iBAAA;EA9GX,yEAgHU,IAAA,GAAO,cAAc;AAAA;AAAA,KAGpB,UAAA;EApGC,8FAsGF,IAAA,GAAO,IAAA,UAAc,MAAA,UAAgB,OAAA,EAAS,MAAA,CAAO,IAAA,KAAS,eAAA;WAE9D,KAAA,QAAa,cAAA;WAEb,IAAA,QAAY,cAAA;EAAA,SACZ,MAAA;IAAA,SACE,OAAA,QAAe,aAAA,CAAc,qBAAA;IAAA,SAC7B,KAAA;EAAA;WAGF,KAAA;EAAA,SACA,MAAA;IAAA,SACE,GAAA,GAAM,KAAA,EAAO,eAAA,KAAoB,oBAAA;IAAA,SACjC,IAAA,QAAY,aAAA,CAAc,oBAAA;IAAA,SAC1B,KAAA;EAAA;EAAA,SAEF,QAAA,QAAgB,kBAAA;AAAA;;;;;;;;;;;;;;;;;cAuTd,cAAA,GAAkB,OAAA,GAAS,iBAAA,KAAyB,UAkPhE"}