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

package/src/codegen/openapi.ts

@@ -23,7 +23,7 @@
  *     across operations; anonymous nested objects synthesize names from the
  *     parent + member path
  *   • responses: 200 → 201 → 204 precedence (`successStatuses` overrides),
- *     `application/json` only; object
+ *     JSON or opt-in binary `application/octet-stream`; object
  *     results become `<Op>Response` structures (a sole `$ref` reuses the named
  *     shape); bare array/scalar results wrap in a structure whose single
  *     member carries `com.distilled.openapi#rawResponse` (the SdkSpec maps it
@@ -161,6 +161,12 @@ export interface OpenApiConvertOptions {
    * ask for them.
    */
   readonly headerParams?: boolean;
+  /**
+   * Convert `format: binary` strings to blobs and include binary
+   * `application/octet-stream` responses. Opt in only when the provider's
+   * generator and protocol support binary inputs and outputs. Default false.
+   */
+  readonly binaryTypes?: boolean;
   /**
    * Response statuses to read the operation's output shape from, most
    * preferred first. Default `["200", "201", "204"]`. Extend it for an API
@@ -226,6 +232,7 @@ export interface SmithyModel {
 const PRELUDE = {
   Unit: "smithy.api#Unit",
   String: "smithy.api#String",
+  Blob: "smithy.api#Blob",
   Boolean: "smithy.api#Boolean",
   Double: "smithy.api#Double",
   Integer: "smithy.api#Integer",
@@ -308,6 +315,7 @@ interface Ctx {
    */
   readonly dirSensitiveRefs: Map<Dir, ReadonlySet<string>>;
   readonly sensitivePatterns: readonly RegExp[];
+  readonly binaryTypes: boolean;
 }
 
 interface Converted {
@@ -913,7 +921,12 @@ const convertSchema = (
   // --- scalars --------------------------------------------------------------
   switch (t) {
     case "string":
-      return inline(PRELUDE.String, nullable);
+      return inline(
+        ctx.binaryTypes && def.format === "binary"
+          ? PRELUDE.Blob
+          : PRELUDE.String,
+        nullable,
+      );
     case "boolean":
       return inline(PRELUDE.Boolean, nullable);
     case "integer":
@@ -1104,7 +1117,7 @@ const opDoc = (op: any): string | undefined => {
 // Responses
 // ============================================================================
 
-/** First declared status in `order` wins; response-level `$ref` resolved; JSON only. */
+/** First declared status wins; resolve response refs and preserve JSON or binary bodies. */
 const successSchema = (
   ctx: Ctx,
   responses: any,
@@ -1118,7 +1131,15 @@ const successSchema = (
     if (ctx.version === "2.0") {
       return { schema: resp.schema };
     }
-    return { schema: resp.content?.["application/json"]?.schema };
+    const json = resp.content?.["application/json"]?.schema;
+    const binary = resp.content?.["application/octet-stream"]?.schema;
+    return {
+      schema:
+        json ??
+        (ctx.binaryTypes && deref(ctx, binary)?.format === "binary"
+          ? binary
+          : undefined),
+    };
   }
   return { schema: undefined };
 };
@@ -1269,6 +1290,7 @@ export const convertOpenApiToSmithy = (
     refs: new Map(),
     dirSensitiveRefs: new Map(),
     sensitivePatterns: options.sensitivePatterns ?? SENSITIVE_FIELD_PATTERNS,
+    binaryTypes: options.binaryTypes ?? false,
   };
   const statusToErrorClass =
     options.statusToErrorClass ?? DEFAULT_STATUS_TO_ERROR_CLASS;

package/src/codegen/patches.test.ts

@@ -1,11 +1,14 @@
-import { describe, expect, test } from "bun:test";
+import { afterEach, describe, expect, test } from "bun:test";
 import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
   FINALIZED_KEY,
+  SKIP_PATCHES_ENV,
+  applyRfc6902Files,
   danglingTargets,
   finalizeConvert,
+  listRfc6902PatchFiles,
   syncServiceOperations,
 } from "./patches.ts";
 
@@ -128,3 +131,65 @@ describe("syncServiceOperations", () => {
     ]);
   });
 });
+
+describe(SKIP_PATCHES_ENV, () => {
+  afterEach(() => {
+    delete process.env[SKIP_PATCHES_ENV];
+  });
+
+  const patchDir = () => {
+    const dir = mkdtempSync(join(tmpdir(), "skip-"));
+    mkdirSync(join(dir, "svc"));
+    writeFileSync(
+      join(dir, "svc", "a.json"),
+      JSON.stringify({
+        patches: [
+          { op: "add", path: "/x", value: 1 },
+          { op: "add", path: "/y", value: 2 },
+        ],
+      }),
+    );
+    writeFileSync(
+      join(dir, "svc", "b.json"),
+      JSON.stringify({ patches: [{ op: "add", path: "/z", value: 3 }] }),
+    );
+    return join(dir, "svc");
+  };
+
+  test("unset applies everything", async () => {
+    const target: Record<string, unknown> = {};
+    const files = await listRfc6902PatchFiles(patchDir());
+    expect(files.map((f) => f.split("/").pop())).toEqual(["a.json", "b.json"]);
+    expect((await applyRfc6902Files(target, files)).applied).toBe(3);
+    expect(target).toEqual({ x: 1, y: 2, z: 3 });
+  });
+
+  test("all lists no files", async () => {
+    process.env[SKIP_PATCHES_ENV] = "all";
+    expect(await listRfc6902PatchFiles(patchDir())).toEqual([]);
+  });
+
+  test("a basename or a path suffix drops that file", async () => {
+    const dir = patchDir();
+    process.env[SKIP_PATCHES_ENV] = "a.json";
+    expect(
+      (await listRfc6902PatchFiles(dir)).map((f) => f.split("/").pop()),
+    ).toEqual(["b.json"]);
+    process.env[SKIP_PATCHES_ENV] = "svc/b.json";
+    expect(
+      (await listRfc6902PatchFiles(dir)).map((f) => f.split("/").pop()),
+    ).toEqual(["a.json"]);
+    process.env[SKIP_PATCHES_ENV] = "other/b.json";
+    expect((await listRfc6902PatchFiles(dir)).length).toBe(2);
+  });
+
+  test("<file>:<index> drops one op and keeps the rest of the file", async () => {
+    const dir = patchDir();
+    const files = await listRfc6902PatchFiles(dir);
+    process.env[SKIP_PATCHES_ENV] = "a.json:1";
+    const target: Record<string, unknown> = {};
+    const result = await applyRfc6902Files(target, files);
+    expect(result.applied).toBe(2);
+    expect(target).toEqual({ x: 1, z: 3 });
+  });
+});

package/src/codegen/patches.ts

@@ -40,12 +40,89 @@ const exists = async (p: string): Promise<boolean> => {
   }
 };
 
+/**
+ * Leave patches out of one convert run (dev-time only; the seam
+ * `scripts/patches.ts audit` uses to find patches the spec no longer
+ * needs). Comma-separated entries:
+ *
+ *   all                    skip every patch file
+ *   <file>                 skip a file — its basename, or a path suffix
+ *                          (`svc/a.json`) when basenames repeat
+ *   <file>:<index>         skip one op of a file, by its index in `patches`
+ *
+ * Like `DISTILLED_SPECS_LOCAL`, it lives in one command's environment: a
+ * model written under it is announced on stderr and must not be committed.
+ */
+export const SKIP_PATCHES_ENV = "DISTILLED_SKIP_PATCHES";
+
+interface SkipList {
+  readonly all: boolean;
+  readonly files: readonly string[];
+  readonly ops: ReadonlyMap<string, ReadonlySet<number>>;
+}
+
+const parseSkipList = (): SkipList | undefined => {
+  const raw = (process.env[SKIP_PATCHES_ENV] ?? "").trim();
+  if (raw === "") return undefined;
+  const files: string[] = [];
+  const ops = new Map<string, Set<number>>();
+  for (const entry of raw.split(",")) {
+    const item = entry.trim();
+    if (item === "") continue;
+    if (item === "all") return { all: true, files: [], ops: new Map() };
+    const at = item.lastIndexOf(":");
+    const index = at === -1 ? NaN : Number(item.slice(at + 1));
+    if (Number.isInteger(index) && index >= 0) {
+      const file = item.slice(0, at);
+      ops.set(file, (ops.get(file) ?? new Set()).add(index));
+    } else {
+      files.push(item);
+    }
+  }
+  return { all: false, files, ops };
+};
+
+const skipMatches = (file: string, entry: string): boolean =>
+  path.basename(file) === entry || file.endsWith(path.sep + entry);
+
+let skipAnnounced = false;
+
+const skipList = (): SkipList | undefined => {
+  const list = parseSkipList();
+  if (list && !skipAnnounced) {
+    skipAnnounced = true;
+    // stderr for the same reason as the DISTILLED_SPECS_LOCAL notice.
+    console.error(
+      `⚠  ${SKIP_PATCHES_ENV}=${process.env[SKIP_PATCHES_ENV]} — this model is missing patches; do not commit it.`,
+    );
+  }
+  return list;
+};
+
+const skipsFile = (list: SkipList | undefined, file: string): boolean =>
+  list !== undefined &&
+  (list.all || list.files.some((entry) => skipMatches(file, entry)));
+
+const skipsOp = (
+  list: SkipList | undefined,
+  file: string,
+  index: number,
+): boolean => {
+  if (list === undefined) return false;
+  for (const [entry, indices] of list.ops) {
+    if (indices.has(index) && skipMatches(file, entry)) return true;
+  }
+  return false;
+};
+
 /**
  * RFC-6902 files in `dir`: every `*.json`, `*.manual.json` last (those
- * usually target post-rename shape names). Missing dir → `[]`.
+ * usually target post-rename shape names). Missing dir → `[]`. Files named
+ * by {@link SKIP_PATCHES_ENV} are left out.
  */
 export const listRfc6902PatchFiles = async (dir: string): Promise<string[]> => {
   if (!(await exists(dir))) return [];
+  const skip = skipList();
   return (await fs.readdir(dir))
     .filter((f) => f.endsWith(".json"))
     .sort(
@@ -53,7 +130,8 @@ export const listRfc6902PatchFiles = async (dir: string): Promise<string[]> => {
         Number(a.endsWith(".manual.json")) -
           Number(b.endsWith(".manual.json")) || a.localeCompare(b),
     )
-    .map((f) => path.join(dir, f));
+    .map((f) => path.join(dir, f))
+    .filter((f) => !skipsFile(skip, f));
 };
 
 export const applyRfc6902Files = async (
@@ -73,12 +151,14 @@ export const applyRfc6902Files = async (
     stale: 0,
     errors: [],
   };
+  const skip = skipList();
   for (const file of files) {
+    if (skipsFile(skip, file)) continue;
     const parsed = JSON.parse(await fs.readFile(file, "utf8")) as PatchFile;
     const label = opts.label?.(file) ?? path.basename(file);
     result.files++;
-    for (const patchOp of parsed.patches ?? []) {
-      if (!include(patchOp)) continue;
+    for (const [index, patchOp] of (parsed.patches ?? []).entries()) {
+      if (!include(patchOp) || skipsOp(skip, file, index)) continue;
       try {
         applyOperation(target, patchOp);
         result.applied++;

package/src/codegen/untagged-unions.test.ts

@@ -0,0 +1,89 @@
+import { expect, test } from "bun:test";
+import { generateService } from "./generator.ts";
+
+const model = {
+  smithy: "2.0",
+  shapes: {
+    "com.example#Service": {
+      type: "service",
+      version: "1",
+      operations: [{ target: "com.example#GetValue" }],
+    },
+    "com.example#GetValue": {
+      type: "operation",
+      input: { target: "com.example#Input" },
+      output: { target: "com.example#Output" },
+      traits: {
+        "smithy.api#http": { method: "GET", uri: "/value", code: 200 },
+      },
+    },
+    "com.example#Input": { type: "structure", members: {} },
+    "com.example#Output": {
+      type: "structure",
+      members: { value: { target: "com.example#Choice" } },
+    },
+    "com.example#Choice": {
+      type: "union",
+      members: {
+        boolean: { target: "smithy.api#Boolean" },
+        paths: { target: "com.example#Paths" },
+      },
+    },
+    "com.example#Paths": {
+      type: "list",
+      member: { target: "smithy.api#String" },
+    },
+  },
+};
+
+const operationDecl = {
+  contextType: "ExampleOpContext",
+  commonErrorType: "ExampleOpError",
+  commonErrorClasses: [],
+  protocol: "ExampleProtocol",
+};
+
+test("untagged unions validate primitive and collection alternatives", () => {
+  const { code } = generateService(model, {
+    unionStyle: "untagged",
+    operationDecl,
+  });
+  expect(code).toContain("export type Choice = boolean | Paths;");
+  expect(code).toContain("S.Union([S.Boolean, Paths])");
+  expect(code).not.toContain("S.Unknown as any as S.Schema<Choice>");
+});
+
+test("untagged unions honor the configured schema type", () => {
+  for (const schemaType of ["Schema", "Codec"] as const) {
+    const { code } = generateService(model, {
+      unionStyle: "untagged",
+      schemaType,
+      operationDecl,
+    });
+    expect(code).toContain(
+      `S.Union([S.Boolean, Paths]) as any as S.${schemaType}<Choice>`,
+    );
+    expect(code).toContain(
+      `S.Array(S.String) as any as S.${schemaType}<Paths>`,
+    );
+  }
+});
+
+test("omitting a retry policy emits neither a retry import nor an operation setting", () => {
+  const { code } = generateService(model, {
+    unionStyle: "untagged",
+    operationDecl,
+  });
+  expect(code).not.toContain("../retry.ts");
+  expect(code).not.toContain("retry:");
+  expect(code).not.toContain('import {  } from "../errors.ts"');
+});
+
+test("an explicit retry policy retains the existing import and operation setting", () => {
+  const { code } = generateService(model, {
+    unionStyle: "untagged",
+    operationDecl: { ...operationDecl, retry: "Retry.Retry" },
+  });
+  expect(code).toContain('import * as Retry from "../retry.ts"');
+  expect(code).toContain("retry: Retry.Retry");
+});

package/src/errors.ts

@@ -133,7 +133,7 @@ export class ServiceUnavailable extends Schema.TaggedError<ServiceUnavailable>()
 ).pipe(Category.withServerError, Category.withRetryable()) {}
 
 /**
- * GatewayTimeout - Gateway timeout (504).
+ * GatewayTimeout - HTTP request or gateway timeout (408, 504).
  */
 export class GatewayTimeout extends Schema.TaggedError<GatewayTimeout>()(
   "GatewayTimeout",
@@ -163,6 +163,7 @@ export const HTTP_STATUS_MAP = {
   401: Unauthorized,
   403: Forbidden,
   404: NotFound,
+  408: GatewayTimeout,
   409: Conflict,
   422: UnprocessableEntity,
   423: Locked,
@@ -189,7 +190,9 @@ export const DEFAULT_ERROR_STATUSES = new Set([401, 429, 500, 502, 503, 504]);
  * classes (BadRequest/Unauthorized/etc.) would silently retain it as a
  * stale field on the instance and pollute serialized output.
  */
-export const RETRYABLE_HTTP_STATUSES = new Set([423, 429, 500, 502, 503, 504]);
+export const RETRYABLE_HTTP_STATUSES = new Set([
+  408, 423, 429, 500, 502, 503, 504,
+]);
 
 /**
  * All common API error classes.