@distilled.cloud/core 1.0.0-rc.11 → 1.0.0-rc.13

package/src/response-validation.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from "bun:test";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
+import * as HttpClientResponse from "effect/http/HttpClientResponse";
+import * as API from "./api.ts";
+import { makeRestProtocol } from "./protocol-rest.ts";
+import * as ResponseValidation from "./response-validation.ts";
+
+class TestParseError extends Schema.TaggedError<TestParseError>()(
+  "TestParseError",
+  { body: Schema.Unknown, cause: Schema.Unknown },
+) {}
+
+class TestUnknownError extends Schema.TaggedError<TestUnknownError>()(
+  "TestUnknownError",
+  { message: Schema.String },
+) {}
+
+const TestProtocol = makeRestProtocol<{}>({
+  credentials: Effect.succeed({}),
+  baseUrl: () => "https://api.test",
+  headers: () => ({}),
+  unknownError: ({ message }) => new TestUnknownError({ message }),
+  parseError: ({ body, cause }) => new TestParseError({ body, cause }),
+});
+
+const Output = Schema.Struct({ id: Schema.String });
+
+const decode = (body: string) =>
+  Effect.gen(function* () {
+    const protocol = yield* API.Protocol;
+    const request = HttpClientRequest.get("https://api.test/thing");
+    return yield* protocol.decode({
+      response: HttpClientResponse.fromWeb(
+        request,
+        new Response(body, { status: 200 }),
+      ),
+      outputAst: Output.ast,
+      errors: [],
+      config: {},
+    });
+  }).pipe(Effect.provide(TestProtocol));
+
+const run = <A, E>(effect: Effect.Effect<A, E>, layer?: Layer.Layer<never>) =>
+  Effect.runPromise(
+    Effect.result(layer ? effect.pipe(Effect.provide(layer)) : effect),
+  );
+
+describe("makeRestProtocol response validation", () => {
+  test("lenient (default) returns a non-JSON 2xx body as text", async () => {
+    const result = await run(decode("not json"));
+    expect(result).toMatchObject({ _tag: "Success", success: "not json" });
+  });
+
+  test("lenient (default) returns {} for an output that requires id", async () => {
+    const result = await run(decode("{}"));
+    expect(result).toMatchObject({ _tag: "Success", success: {} });
+  });
+
+  test("strict fails a non-JSON 2xx body with the provider's parse error", async () => {
+    const result = await run(decode("not json"), ResponseValidation.strict);
+    expect(result._tag).toBe("Failure");
+    const error = (result as any).failure;
+    expect(error).toBeInstanceOf(TestParseError);
+    expect(error.body).toBe("not json");
+  });
+
+  test("strict fails a body missing a required member", async () => {
+    const result = await run(decode("{}"), ResponseValidation.strict);
+    expect(result._tag).toBe("Failure");
+    expect((result as any).failure).toBeInstanceOf(TestParseError);
+    expect((result as any).failure.body).toEqual({});
+  });
+
+  test("strict passes a matching body through unchanged, extra members included", async () => {
+    const result = await run(
+      decode(JSON.stringify({ id: "a", extra: 1 })),
+      ResponseValidation.strict,
+    );
+    expect(result).toMatchObject({
+      _tag: "Success",
+      success: { id: "a", extra: 1 },
+    });
+  });
+
+  test("an inner lenient layer overrides an outer strict one", async () => {
+    const result = await run(
+      decode("{}").pipe(Effect.provide(ResponseValidation.lenient)),
+      ResponseValidation.strict,
+    );
+    expect(result).toMatchObject({ _tag: "Success", success: {} });
+  });
+});

package/src/response-validation.ts

@@ -0,0 +1,116 @@
+/**
+ * Response validation mode, shared by every distilled SDK.
+ *
+ * Generated SDKs carry a schema for every operation's output. What a
+ * protocol does with it on a 2xx response depends on the mode:
+ *
+ *   lenient (default): the response is returned as the protocol read it.
+ *                      A body that does not match the declared output type
+ *                      (a missing member, a wrong primitive, a non-JSON
+ *                      body) still succeeds.
+ *   strict:            the response is decoded against the output schema,
+ *                      and a mismatch fails the call with the SDK's
+ *                      `<Sdk>ParseError` (AWS: `ParseError`).
+ *
+ * The mode is one {@link ResponseValidation} reference keyed by a string, so
+ * a single `Layer` switches every distilled SDK in a program — AWS,
+ * Cloudflare, Neon, … — at once, and nests like any other Effect service:
+ *
+ * ```ts
+ * import { ResponseValidation } from "@distilled.cloud/core";
+ *
+ * // whole program
+ * program.pipe(Effect.provide(ResponseValidation.strict));
+ *
+ * // one call back to lenient inside a strict program
+ * Neon.getProject({ projectId }).pipe(Effect.provide(ResponseValidation.lenient));
+ * ```
+ *
+ * The mode is set only by these layers; without one, every call is lenient.
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import type * as AST from "effect/SchemaAST";
+
+export type Mode = "lenient" | "strict";
+
+/**
+ * The active validation mode. Read by protocols at call time on the calling
+ * fiber; `lenient` unless a {@link strict} layer is provided.
+ */
+export const ResponseValidation = Context.Reference<Mode>(
+  "@distilled.cloud/core/ResponseValidation",
+  { defaultValue: () => "lenient" },
+);
+
+/** Decode every 2xx response against its output schema; fail on mismatch. */
+export const strict: Layer.Layer<never> = Layer.succeed(
+  ResponseValidation,
+  "strict",
+);
+
+/** Return 2xx responses as read, without checking them against the schema. */
+export const lenient: Layer.Layer<never> = Layer.succeed(
+  ResponseValidation,
+  "lenient",
+);
+
+/** Whether the calling fiber is in strict mode. */
+export const isStrict: Effect.Effect<boolean> = Effect.map(
+  ResponseValidation,
+  (mode) => mode === "strict",
+);
+
+/**
+ * For a 2xx body the protocol could not read into the shape it transforms
+ * (e.g. invalid JSON): fail with `error` in strict mode, succeed with
+ * `asRead` (usually the body text) in lenient mode.
+ */
+export const failIfStrict = <A, E>(error: E, asRead: A): Effect.Effect<A, E> =>
+  Effect.flatMap(ResponseValidation, (mode) =>
+    mode === "strict" ? Effect.fail(error) : Effect.succeed(asRead),
+  );
+
+const decoders = new WeakMap<
+  AST.AST,
+  (input: unknown) => Effect.Effect<unknown, Schema.SchemaError>
+>();
+
+const decoderFor = (ast: AST.AST) => {
+  let decode = decoders.get(ast);
+  if (!decode) {
+    decode = Schema.decodeUnknownEffect(Schema.make<Schema.Top>(ast)) as (
+      input: unknown,
+    ) => Effect.Effect<unknown, Schema.SchemaError>;
+    decoders.set(ast, decode);
+  }
+  return decode;
+};
+
+/**
+ * Check a 2xx response value against the operation's output schema.
+ *
+ * Lenient mode returns `value` untouched. Strict mode decodes it and, on a
+ * mismatch, fails with `onError(schemaError)` — protocols pass their SDK's
+ * `<Sdk>ParseError` constructor. On success the ORIGINAL value is returned
+ * (members the schema does not model are kept), so switching modes never
+ * changes what a successful call returns.
+ *
+ * `value` must already be in the schema's shape (TS member names), i.e.
+ * after any wire→TS key mapping and before `Redacted` wrapping.
+ */
+export const validateResponse = <E>(
+  outputAst: AST.AST,
+  value: unknown,
+  onError: (cause: Schema.SchemaError) => E,
+): Effect.Effect<unknown, E> =>
+  Effect.flatMap(ResponseValidation, (mode) =>
+    mode === "lenient"
+      ? Effect.succeed(value)
+      : decoderFor(outputAst)(value).pipe(
+          Effect.mapError(onError),
+          Effect.as(value),
+        ),
+  );

package/src/testing.ts

@@ -0,0 +1,78 @@
+/**
+ * Test helpers for SDK packages: a canned-response `HttpClient` and a runner
+ * that executes one operation under both response-validation modes.
+ *
+ * ```ts
+ * const { lenient, strict } = await runValidationModes(
+ *   Pkg.getThing({ id: "a" }).pipe(Retry.none, Effect.provide(TestCredentials)),
+ *   { body: "{}" },
+ * );
+ * expect(lenient).toMatchObject({ _tag: "Success", success: {} });
+ * expect(strict).toMatchObject({ _tag: "Failure" });
+ * ```
+ */
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type * as Result from "effect/Result";
+import * as HttpClient from "effect/http/HttpClient";
+import type * as HttpClientRequest from "effect/http/HttpClientRequest";
+import * as HttpClientResponse from "effect/http/HttpClientResponse";
+import * as ResponseValidation from "./response-validation.ts";
+
+export interface MockResponse {
+  /** Default 200. */
+  readonly status?: number;
+  /** Default `application/json`. */
+  readonly headers?: Record<string, string>;
+  readonly body: string;
+}
+
+/**
+ * An `HttpClient` that answers every request with `response` (or with what
+ * `response(request)` returns, for protocols that make more than one call).
+ */
+export const mockHttpClient = (
+  response:
+    | MockResponse
+    | ((request: HttpClientRequest.HttpClientRequest) => MockResponse),
+): Layer.Layer<HttpClient.HttpClient> =>
+  Layer.succeed(
+    HttpClient.HttpClient,
+    HttpClient.make((request) =>
+      Effect.sync(() => {
+        const r = typeof response === "function" ? response(request) : response;
+        return HttpClientResponse.fromWeb(
+          request,
+          new Response(r.body, {
+            status: r.status ?? 200,
+            headers: r.headers ?? { "content-type": "application/json" },
+          }),
+        );
+      }),
+    ),
+  );
+
+/**
+ * Run `effect` against `mockHttpClient(response)` once in lenient mode and
+ * once in strict mode.
+ */
+export const runValidationModes = <A, E>(
+  effect: Effect.Effect<A, E, HttpClient.HttpClient>,
+  response: Parameters<typeof mockHttpClient>[0],
+): Promise<{
+  readonly lenient: Result.Result<A, E>;
+  readonly strict: Result.Result<A, E>;
+}> => {
+  const run = (mode: Layer.Layer<never>) =>
+    effect.pipe(
+      Effect.provide(mockHttpClient(response)),
+      Effect.provide(mode),
+      Effect.result,
+    );
+  return Effect.runPromise(
+    Effect.all({
+      lenient: run(ResponseValidation.lenient),
+      strict: run(ResponseValidation.strict),
+    }),
+  );
+};

package/src/trait.ts

@@ -109,6 +109,19 @@ export const labelSymbol = Symbol.for("@distilled.cloud/core/http/label");
 export const Label = (name?: string) =>
   makeAnnotation(labelSymbol, name ?? true);
 
+export const labelEncodingSymbol = Symbol.for(
+  "@distilled.cloud/core/http/label-encoding",
+);
+/** Preserve selected RFC 3986 pchar delimiters inside a single URI label. */
+export const LabelEncoding = (options: { readonly preserve: string }) => {
+  if (!/^[!$&'()*+,;=:@]*$/.test(options.preserve)) {
+    throw new TypeError(
+      "LabelEncoding can preserve only URI path-segment delimiters",
+    );
+  }
+  return makeAnnotation(labelEncodingSymbol, options.preserve);
+};
+
 export const responseCodeSymbol = Symbol.for(
   "@distilled.cloud/core/http/response-code",
 );
@@ -237,19 +250,37 @@ export const errorMatchersSymbol = Symbol.for(
   "@distilled.cloud/core/error-matchers",
 );
 
+/** Exact text, or the conjunction of substring and regular-expression constraints. */
+export type ErrorTextMatcher =
+  | string
+  | { readonly includes?: string; readonly matches?: string };
+
 /**
- * One wire-matching rule for a typed error class. A matcher matches a wire
- * failure when every present field matches: `code` equals the wire error's
- * code, `status` equals the HTTP status, and `message` either equals the
- * error message (string form) or satisfies `includes` (substring) /
- * `matches` (regex). A matcher with no fields matches nothing.
+ * One wire-matching rule. All supplied constraints must match; separate
+ * matchers on a class are alternatives. Empty matchers match nothing.
+ *
+ * `body` maps RFC 6901 JSON Pointers to scalar constraints. For example,
+ * `{ "/success": false, "/result/status": "error" }`. Strings also accept
+ * `includes` / `matches`. Missing fields never match, including against null.
+ * The empty pointer addresses the entire body; array indices are supported.
+ * Header names are case-insensitive; their value constraints are case-sensitive.
+ * Each body path and header adds one specificity point, like code/status/message.
+ * Protocols evaluate these rules only after identifying a failed response.
+ *
+ * @example
+ * ```ts
+ * { status: 200, body: { "/success": false, "/result/status": "error" } }
+ * { status: 409, headers: { "x-error-type": { includes: "Conflict" } } }
+ * ```
  */
 export interface ErrorMatcher {
   readonly code?: number;
   readonly status?: number;
-  readonly message?:
-    | string
-    | { readonly includes?: string; readonly matches?: string };
+  readonly message?: ErrorTextMatcher;
+  readonly body?: Readonly<
+    Record<string, ErrorTextMatcher | number | boolean | null>
+  >;
+  readonly headers?: Readonly<Record<string, ErrorTextMatcher>>;
 }
 
 /**

package/src/xml.test.ts

@@ -0,0 +1,269 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import * as Effect from "effect/Effect";
+import fixtures from "./fixtures/xml/upstream-validator.json" with { type: "json" };
+import { escapeXml, parseXml, parseXmlSync, XmlParseError } from "./xml.ts";
+
+function parse(xml: string) {
+  // Compare the wire values independently of the null prototypes used for safety.
+  return JSON.parse(JSON.stringify(parseXmlSync(xml)));
+}
+
+describe("upstream fast-xml-parser validation corpus", () => {
+  for (const [index, fixture] of fixtures.entries()) {
+    it(`${index}: ${fixture.name}`, () => {
+      if (fixture.parserValid ?? fixture.valid) {
+        assert.doesNotThrow(() => parseXmlSync(fixture.xml));
+      } else {
+        assert.throws(() => parseXmlSync(fixture.xml), XmlParseError);
+      }
+    });
+  }
+});
+
+describe("XML object format", () => {
+  it("keeps primitives as strings and groups repeated children", () => {
+    assert.deepEqual(
+      parse("<R><x>001</x><x>false</x><x>1e3</x><empty/><empty></empty></R>"),
+      { R: { x: ["001", "false", "1e3"], empty: ["", ""] } },
+    );
+  });
+
+  it("preserves namespace names, attributes, and text with attributes", () => {
+    assert.deepEqual(
+      parse(
+        '<ns:R xmlns:ns="urn:r"><ns:x ns:id="01">value</ns:x><empty a=""/></ns:R>',
+      ),
+      {
+        "ns:R": {
+          "@_xmlns:ns": "urn:r",
+          "ns:x": { "@_ns:id": "01", "#text": "value" },
+          empty: { "@_a": "" },
+        },
+      },
+    );
+  });
+
+  it("preserves string whitespace, including attribute and CDATA values", () => {
+    assert.deepEqual(
+      parse(
+        '<R><Key> key </Key><blank> \t </blank><x a=" b "> text </x><c><![CDATA[ c ]]></c></R>',
+      ),
+      {
+        R: {
+          Key: " key ",
+          blank: " \t ",
+          x: { "@_a": " b ", "#text": " text " },
+          c: " c ",
+        },
+      },
+    );
+  });
+
+  it("discards layout-only container text but preserves mixed content", () => {
+    assert.deepEqual(parse("<R>\n  <x/>\n  <y/>\n</R>"), {
+      R: { x: "", y: "" },
+    });
+    assert.deepEqual(parse("<R>Hello <b>world</b> !</R>"), {
+      R: { b: "world", "#text": "Hello  !" },
+    });
+    assert.deepEqual(parse("<R><![CDATA[ ]]><b/></R>"), {
+      R: { b: "", "#text": " " },
+    });
+  });
+
+  it("decodes predefined and numeric entities exactly once", () => {
+    assert.deepEqual(
+      parse('<R a="&quot;&apos;&#9;">&amp;&lt;&gt;&#65;&#x1F600;&amp;lt;</R>'),
+      { R: { "@_a": "\"'\t", "#text": "&<>A😀&lt;" } },
+    );
+  });
+
+  it("normalizes literal line endings and attribute whitespace, not character references", () => {
+    assert.deepEqual(
+      parse('<R a="x\r\ny\tz\r&#13;&#10;&#9;">a\r\nb\rc&#13;</R>'),
+      { R: { "@_a": "x y z \r\n\t", "#text": "a\nb\nc\r" } },
+    );
+  });
+
+  it("joins CDATA and text without decoding CDATA entities", () => {
+    assert.deepEqual(parse("<R>a<![CDATA[<b>&amp;]]><![CDATA[c]]>d&amp;</R>"), {
+      R: "a<b>&amp;cd&",
+    });
+    assert.deepEqual(parse("<R><![CDATA[]]></R>"), { R: "" });
+  });
+
+  it("ignores declarations, comments and processing instructions", () => {
+    assert.deepEqual(
+      parse(
+        '\uFEFF<?xml version="1.0" encoding="UTF-8" standalone="yes"?><!--before--><?before a?><R>a<!--ignored--><?in x?>b</R><?after?><!--after-->',
+      ),
+      { R: "ab" },
+    );
+  });
+
+  it("supports XML Unicode names", () => {
+    assert.deepEqual(parse('<根 é="oui"><𐀀>😀</𐀀><á/></根>'), {
+      根: { "@_é": "oui", 𐀀: "😀", á: "" },
+    });
+  });
+
+  it("accepts empty HTTP bodies", () => {
+    for (const xml of ["", " \r\n\t", "\uFEFF"])
+      assert.deepEqual(parse(xml), {});
+  });
+
+  it("stores prototype-related names as own data properties", () => {
+    const result = parseXmlSync(
+      "<__proto__><constructor>one</constructor><constructor>two</constructor><__proto__>safe</__proto__><toString/></__proto__>",
+    );
+    const root = result.__proto__;
+    assert.equal(Object.getPrototypeOf(result), null);
+    assert.equal(Object.getPrototypeOf(root), null);
+    assert.deepEqual(
+      JSON.parse(JSON.stringify(root)),
+      JSON.parse(
+        '{"constructor":["one","two"],"__proto__":"safe","toString":""}',
+      ),
+    );
+    assert.equal(Object.hasOwn(Object.prototype, "safe"), false);
+  });
+
+  it("round trips escaped strings", () => {
+    for (const text of [
+      ' <tag a="x">&\'😀 ',
+      "",
+      "false",
+      "001",
+      "&#13;",
+      "\t\n",
+    ]) {
+      assert.deepEqual(parse(`<R>${escapeXml(text)}</R>`), { R: text });
+    }
+  });
+
+  it("handles large lists without recursion", () => {
+    const result = parse(`<R>${'<item a="1">value</item>'.repeat(10_000)}</R>`);
+    assert.equal(result.R.item.length, 10_000);
+    assert.deepEqual(result.R.item[9_999], { "@_a": "1", "#text": "value" });
+  });
+});
+
+describe("malformed and unsupported XML", () => {
+  const invalid = [
+    '<R a="1"a="2"/>',
+    '<R a="<"/>',
+    '<R a="&bad;"/>',
+    "<R a=1/>",
+    '<R a="1" a="2"/>',
+    "<R/ >",
+    "< R/>",
+    "<R></ R>",
+    "<R></R x>",
+    "<R>]]></R>",
+    "<R>&</R>",
+    "<R>&amp</R>",
+    "<R>&nope;</R>",
+    "<R>&#0;</R>",
+    "<R>&#xD800;</R>",
+    "<R>&#x110000;</R>",
+    "<R>&#xFFFE;</R>",
+    "<R>&#-1;</R>",
+    "<R>&#X41;</R>",
+    "<R>&#x;</R>",
+    "<R>&#;</R>",
+    "<R>\u0000</R>",
+    "<R>\u000B</R>",
+    "<R>\uD800</R>",
+    "<R>\uDC00</R>",
+    "<R>\uFFFE</R>",
+    "<R>\uFFFF</R>",
+    "<R><!--a--b--></R>",
+    "<R><!--a---></R>",
+    "<R><!--",
+    "<R><![CDATA[",
+    "<![CDATA[x]]><R/>",
+    "<R/><![CDATA[x]]>",
+    "<R><?pi",
+    "<R><?1bad?></R>",
+    "<R><?pi!?></R>",
+    '<?XML version="1.0"?><R/>',
+    "<?xml?><R/>",
+    '<?xml version="1.1"?><R/>',
+    '<?xml encoding="UTF-8"?><R/>',
+    '<?xml version="1.0" junk="x"?><R/>',
+    '<R><?xml version="1.0"?></R>',
+    '<!--x--><?xml version="1.0"?><R/>',
+    '<?xml version="1.0"?>',
+    "<!--only-->",
+    "<!DOCTYPE R><R/>",
+    '<!DOCTYPE R SYSTEM "file:///etc/passwd"><R/>',
+    '<!DOCTYPE R [<!ENTITY a "&a;">]><R>&a;</R>',
+    "<R/><R/>",
+    "before<R/>",
+    "<R/>after",
+    "<R><x></R>",
+    "<R>",
+    "<",
+    '<R a="',
+    "<R a",
+    "<R a=",
+    "<R ",
+    "</R>",
+    "<1bad/>",
+    '<R\u00A0a="x"/>',
+  ];
+  for (const xml of invalid) {
+    it(`rejects ${JSON.stringify(xml)}`, () => {
+      assert.throws(
+        () => parseXmlSync(xml),
+        (error) => {
+          assert.ok(error instanceof XmlParseError);
+          assert.ok(error.offset >= 0 && error.offset <= xml.length);
+          return true;
+        },
+      );
+    });
+  }
+
+  it("reports original input offsets and CRLF-aware line numbers", () => {
+    const xml = "<R>\r\n&bad;</R>";
+    assert.throws(
+      () => parseXmlSync(xml),
+      (error) => {
+        assert.ok(error instanceof XmlParseError);
+        assert.equal(error.offset, 5);
+        assert.equal(error.line, 2);
+        assert.equal(error.column, 1);
+        return true;
+      },
+    );
+  });
+
+  it("enforces depth and input length limits", () => {
+    assert.doesNotThrow(() => parseXmlSync("<a><b/></a>", { maxDepth: 2 }));
+    assert.throws(
+      () => parseXmlSync("<a><b/></a>", { maxDepth: 1 }),
+      XmlParseError,
+    );
+    assert.doesNotThrow(() => parseXmlSync("<a/>", { maxLength: 4 }));
+    assert.throws(() => parseXmlSync("<a/>", { maxLength: 3 }), XmlParseError);
+    assert.throws(() => parseXmlSync("<a/>", { maxDepth: NaN }), XmlParseError);
+    assert.throws(() => parseXmlSync("<a/>", { maxLength: -1 }), XmlParseError);
+    const nested = "<a>".repeat(2_000) + "</a>".repeat(2_000);
+    assert.throws(() => parseXmlSync(nested), XmlParseError);
+    assert.doesNotThrow(() => parseXmlSync(nested, { maxDepth: 2_000 }));
+  });
+
+  it("exposes parser failures through Effect's typed channel", () => {
+    const result = Effect.runSync(Effect.flip(parseXml("<R>")));
+    assert.ok(result instanceof XmlParseError);
+    assert.match(result.message, /Unclosed element/);
+  });
+
+  it("can execute the same lazy Effect repeatedly", () => {
+    const effect = parseXml("<R>ok</R>");
+    assert.equal(Effect.runSync(effect).R, "ok");
+    assert.equal(Effect.runSync(effect).R, "ok");
+  });
+});