@amerged/ohmyhost-runtime 0.1.37 → 0.1.39

package/src/packages/customer-runtime/src/http.ts

@@ -4,9 +4,13 @@ const MAX_RESPONSE_BYTES = 32 * 1024;
 const DEFAULT_TIMEOUT_MILLISECONDS = 10_000;
 
 export interface GatewayConnection {
+  /** Injected gateway origin for server code; never expose the runtime key to a browser. */
   readonly endpoint: string;
+  /** Environment capability key from OHMYHOST_MAIL_KEY or OHMYHOST_STORAGE_KEY. */
   readonly key: string;
+  /** Use (request) => fetch(request); an explicit transport remains available for tests. */
   readonly fetch: (request: Request) => Promise<Response>;
+  /** Gateway header timeout: 100–30000 ms, default 10000 ms. */
   readonly timeoutMilliseconds?: number;
 }
 
@@ -45,7 +49,7 @@ export function validateGatewayConnection(value: GatewayConnection): ValidatedGa
   }
   if (typeof value.fetch !== "function") {
     configurationInvalid(
-      "fetch is not a function; pass (request) => env.OHMYHOST_MAIL_GATEWAY.fetch(request) or env.OHMYHOST_STORAGE_GATEWAY.fetch(request)",
+      "fetch is not a function; pass (request) => fetch(request) in server code",
     );
   }
   const timeoutMilliseconds = value.timeoutMilliseconds ?? DEFAULT_TIMEOUT_MILLISECONDS;
@@ -112,19 +116,23 @@ export async function fetchWithTimeout(
   }
 }
 
-export function exactRecord(value: unknown, keys: readonly string[]): Record<string, unknown> {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) invalidResponse();
+export function exactRecord(
+  value: unknown,
+  keys: readonly string[],
+  status: number | null = null,
+): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) invalidResponse(status);
   const record = value as Record<string, unknown>;
   const actual = Object.keys(record).sort();
   const expected = [...keys].sort();
   if (actual.length !== expected.length || actual.some((key, index) => key !== expected[index])) {
-    invalidResponse();
+    invalidResponse(status);
   }
   return record;
 }
 
-export function invalidResponse(): never {
-  throw new CustomerRuntimeGatewayError("gateway_response_invalid", null, false);
+export function invalidResponse(status: number | null = null): never {
+  throw new CustomerRuntimeGatewayError("gateway_response_invalid", status, false);
 }
 
 /** A malformed platform ID is a configuration mistake, not a gateway answer. */
@@ -152,17 +160,61 @@ function assertServerRuntime(): void {
 
 async function readBoundedJson(response: Response): Promise<unknown> {
   if (response.headers.get("content-type")?.split(";", 1)[0]?.trim() !== "application/json") {
-    invalidResponse();
+    invalidResponse(response.status);
   }
   const declared = response.headers.get("content-length");
   if (declared !== null && (!/^[0-9]+$/u.test(declared) || Number(declared) > MAX_RESPONSE_BYTES)) {
-    invalidResponse();
+    invalidResponse(response.status);
+  }
+  let bytes: Uint8Array;
+  try {
+    bytes = new Uint8Array(await response.arrayBuffer());
+  } catch {
+    throw new CustomerRuntimeGatewayError("gateway_unavailable", response.status, true);
   }
-  const bytes = new Uint8Array(await response.arrayBuffer());
-  if (bytes.byteLength > MAX_RESPONSE_BYTES) invalidResponse();
+  if (bytes.byteLength > MAX_RESPONSE_BYTES) invalidResponse(response.status);
   try {
     return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
   } catch {
-    return invalidResponse();
+    return invalidResponse(response.status);
+  }
+}
+
+/** Relay failures share one vocabulary across mail, storage and batch control responses. */
+export function throwGatewayRelayError(status: number, body: unknown): void {
+  if (typeof body !== "object" || body === null || Array.isArray(body)) return;
+  const code = (body as Record<string, unknown>)["code"];
+  if (
+    (status === 403 && (code === "gateway_not_enabled" || code === "gateway_route_denied")) ||
+    (status === 429 && code === "gateway_rate_limited") ||
+    (status === 503 &&
+      (code === "mail_gateway_unavailable" || code === "storage_gateway_unavailable"))
+  ) {
+    exactRecord(body, ["code"], status);
+    if (code === "gateway_not_enabled") {
+      throw new CustomerRuntimeGatewayError(
+        code,
+        status,
+        false,
+        "enable the required mail or storage capability in ohmyhost.yaml and redeploy",
+      );
+    }
+    if (code === "gateway_route_denied") {
+      throw new CustomerRuntimeGatewayError(
+        code,
+        status,
+        false,
+        "use the current runtime client's supported gateway routes through (request) => fetch(request)",
+      );
+    }
+    if (code === "gateway_rate_limited") {
+      throw new CustomerRuntimeGatewayError(
+        code,
+        status,
+        true,
+        "wait before repeating this request with the same idempotency keys",
+      );
+    }
+    throw new CustomerRuntimeGatewayError("gateway_unavailable", status, true);
   }
 }

package/src/packages/customer-runtime/src/index.ts

@@ -1,7 +1,7 @@
 export * from "./errors.js";
 export * from "./database.js";
 export * from "./mail.js";
+export * from "./mail-attachment.js";
 export * from "./storage.js";
 export type { GatewayConnection } from "./http.js";
 export * from "./mail-webhook.js";
-export * from "./mail-attachments.js";

package/src/packages/customer-runtime/src/mail-attachment.ts

@@ -0,0 +1,238 @@
+import { CustomerRuntimeGatewayError } from "./errors.js";
+import {
+  exactRecord,
+  fetchWithTimeout,
+  invalidResponse,
+  requireConfiguredUlid,
+  throwGatewayRelayError,
+  validateGatewayConnection,
+  type GatewayConnection,
+} from "./http.js";
+
+export interface MailAttachmentDownloadOptions {
+  readonly signal?: AbortSignal;
+}
+
+/** Server-only receiving access using OHMYHOST_MAIL_KEY and global fetch. */
+export function createMailAttachmentClient(
+  configuration: GatewayConnection & {
+    readonly projectId: string;
+    /** Optional expected environment; otherwise use the canonical metadata download_path scope. */
+    readonly environmentId?: string;
+  },
+) {
+  const connection = validateGatewayConnection(configuration);
+  const projectId = requireConfiguredUlid(
+    configuration.projectId,
+    "projectId",
+    "OHMYHOST_PROJECT_ID",
+  );
+  const environmentId =
+    configuration.environmentId === undefined
+      ? undefined
+      : requireConfiguredUlid(
+          configuration.environmentId,
+          "environmentId",
+          "OHMYHOST_ENVIRONMENT_ID",
+        );
+  return Object.freeze({
+    /** Consume to EOF for success, or cancel the stream when its bytes are no longer needed. */
+    async download(
+      downloadPath: string,
+      options: MailAttachmentDownloadOptions = {},
+    ): Promise<ReadableStream<Uint8Array>> {
+      const match =
+        typeof downloadPath === "string"
+          ? /^\/v1\/projects\/([0-7][0-9A-HJKMNP-TV-Z]{25})\/environments\/([0-7][0-9A-HJKMNP-TV-Z]{25})\/mail\/messages\/([0-7][0-9A-HJKMNP-TV-Z]{25})\/attachments\/([A-Za-z0-9_-]{1,128})$/u.exec(
+              downloadPath,
+            )
+          : null;
+      if (
+        match === null ||
+        match[1] !== projectId ||
+        (environmentId !== undefined && match[2] !== environmentId)
+      ) {
+        throw new CustomerRuntimeGatewayError("gateway_request_invalid", null, false);
+      }
+      const body = JSON.stringify({
+        project_id: projectId,
+        environment_id: match[2],
+        message_id: match[3],
+        attachment_id: match[4],
+      });
+      if (new TextEncoder().encode(body).byteLength > 1024) {
+        throw new CustomerRuntimeGatewayError("gateway_request_invalid", null, false);
+      }
+      const cancellation = new AbortController();
+      const signal =
+        options.signal === undefined
+          ? cancellation.signal
+          : AbortSignal.any([cancellation.signal, options.signal]);
+      if (signal.aborted) throw new CustomerRuntimeGatewayError("gateway_timeout", null, true);
+      const response = await fetchWithTimeout(
+        connection.fetch,
+        new Request(new URL("/v1/attachments/download", connection.endpoint), {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${connection.key}`,
+            "content-type": "application/json",
+          },
+          body,
+          signal,
+        }),
+        connection.timeoutMilliseconds,
+      );
+      if (response.status !== 200) {
+        try {
+          throwAttachmentError(
+            response.status,
+            await readAttachmentError(response, connection.timeoutMilliseconds),
+          );
+        } finally {
+          cancellation.abort();
+        }
+      }
+      if (
+        response.body === null ||
+        response.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() !==
+          "application/octet-stream"
+      ) {
+        cancellation.abort();
+        void response.body?.cancel().catch(ignoreCancellationError);
+        invalidResponse(response.status);
+      }
+      return attachmentStream(response.body, response.status, cancellation, signal);
+    },
+  });
+}
+
+/** A pull reads one source chunk; cancellation never drains or duplicates the attachment. */
+function attachmentStream(
+  body: ReadableStream<Uint8Array>,
+  status: number,
+  cancellation: AbortController,
+  signal: AbortSignal,
+): ReadableStream<Uint8Array> {
+  const source = body.getReader();
+  let finished = false;
+  let abort: () => void;
+  function finish(cancel: boolean) {
+    if (finished) return;
+    finished = true;
+    signal.removeEventListener("abort", abort);
+    if (cancel) {
+      cancellation.abort();
+      void source.cancel().catch(ignoreCancellationError);
+    }
+    source.releaseLock();
+  }
+  return new ReadableStream<Uint8Array>(
+    {
+      start(controller) {
+        abort = () => {
+          controller.error(new CustomerRuntimeGatewayError("gateway_timeout", status, true));
+          finish(true);
+        };
+        if (signal.aborted) abort();
+        else signal.addEventListener("abort", abort, { once: true });
+      },
+      async pull(controller) {
+        try {
+          const next = await source.read();
+          if (finished) return;
+          if (next.done) {
+            finish(false);
+            controller.close();
+          } else if (next.value instanceof Uint8Array) {
+            controller.enqueue(next.value);
+          } else {
+            invalidResponse(status);
+          }
+        } catch {
+          if (finished) return;
+          finish(true);
+          controller.error(new CustomerRuntimeGatewayError("gateway_unavailable", status, true));
+        }
+      },
+      cancel() {
+        finish(true);
+      },
+    },
+    { highWaterMark: 0 },
+  );
+}
+
+/** Only small error records are buffered; binary successes never enter this parser. */
+async function readAttachmentError(
+  response: Response,
+  timeoutMilliseconds: number,
+): Promise<unknown> {
+  const declared = response.headers.get("content-length");
+  if (
+    response.headers.get("content-type")?.split(";", 1)[0]?.trim() !== "application/json" ||
+    response.body === null ||
+    (declared !== null && (!/^[0-9]+$/u.test(declared) || Number(declared) > 1024))
+  ) {
+    void response.body?.cancel().catch(ignoreCancellationError);
+    invalidResponse(response.status);
+  }
+  const source = response.body.getReader();
+  const bytes = new Uint8Array(1024);
+  let length = 0;
+  let finished = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const expired = new Promise<never>((_resolve, reject) => {
+      timer = setTimeout(
+        () => reject(new CustomerRuntimeGatewayError("gateway_timeout", response.status, true)),
+        timeoutMilliseconds,
+      );
+    });
+    for (;;) {
+      const next = await Promise.race([source.read(), expired]);
+      if (next.done) {
+        finished = true;
+        break;
+      }
+      if (!(next.value instanceof Uint8Array) || length + next.value.byteLength > bytes.byteLength)
+        invalidResponse(response.status);
+      bytes.set(next.value, length);
+      length += next.value.byteLength;
+    }
+    try {
+      return JSON.parse(
+        new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, length)),
+      ) as unknown;
+    } catch {
+      return invalidResponse(response.status);
+    }
+  } catch (error) {
+    if (error instanceof CustomerRuntimeGatewayError) throw error;
+    throw new CustomerRuntimeGatewayError("gateway_unavailable", response.status, true);
+  } finally {
+    clearTimeout(timer);
+    if (!finished) void source.cancel().catch(ignoreCancellationError);
+    source.releaseLock();
+  }
+}
+
+function ignoreCancellationError(): void {
+  // The original download failure remains the public error.
+}
+
+function throwAttachmentError(status: number, body: unknown): never {
+  throwGatewayRelayError(status, body);
+  const record = exactRecord(body, ["code"], status);
+  const code = record["code"];
+  if (status === 400 && code === "invalid_request")
+    throw new CustomerRuntimeGatewayError("gateway_request_invalid", status, false);
+  if (status === 401 && code === "unauthorized")
+    throw new CustomerRuntimeGatewayError("unauthorized", status, false);
+  if (status === 404 && code === "resource_not_found")
+    throw new CustomerRuntimeGatewayError("mail_message_not_found", status, false);
+  if (status === 410 && code === "mail_content_expired")
+    throw new CustomerRuntimeGatewayError("mail_content_expired", status, false);
+  if (status === 413 && code === "mail_attachment_too_large")
+    throw new CustomerRuntimeGatewayError("mail_attachment_too_large", status, false);
+  return invalidResponse(status);
+}

package/src/packages/customer-runtime/src/mail.ts

@@ -5,6 +5,7 @@ import {
   postGatewayJson,
   requireConfiguredUlid,
   validateGatewayConnection,
+  throwGatewayRelayError,
   type GatewayConnection,
 } from "./http.js";
 
@@ -38,6 +39,7 @@ export type TransactionalMailResult =
       readonly requestId: string;
     };
 
+/** Server-only transactional mail over the injected gateway URL and global fetch. */
 export function createTransactionalMailClient(
   configuration: GatewayConnection & { readonly projectId: string },
 ) {
@@ -72,8 +74,9 @@ export function createTransactionalMailClient(
         raw?.["state"] === "accepted"
           ? ["state", "request_id", "message_id"]
           : ["state", "request_id"],
+        response.status,
       );
-      const requestId = requireUlid(stateRecord["request_id"]);
+      const requestId = requireUlid(stateRecord["request_id"], response.status);
       if (stateRecord["state"] === "uncertain") {
         return Object.freeze({ state: "uncertain" as const, requestId });
       }
@@ -82,7 +85,7 @@ export function createTransactionalMailClient(
         typeof stateRecord["message_id"] !== "string" ||
         !/^[A-Za-z0-9._-]{1,256}$/u.test(stateRecord["message_id"])
       ) {
-        invalidResponse();
+        invalidResponse(response.status);
       }
       return Object.freeze({
         state: "accepted" as const,
@@ -108,13 +111,15 @@ function validateMailInput(input: TransactionalMailInput): void {
 }
 
 function throwMailError(status: number, body: unknown): never {
+  throwGatewayRelayError(status, body);
   const raw = body as Record<string, unknown>;
   const record = exactRecord(
     body,
     raw?.["request_id"] === undefined ? ["code"] : ["code", "request_id"],
+    status,
   );
   const code = record["code"];
-  if (record["request_id"] !== undefined) requireUlid(record["request_id"]);
+  if (record["request_id"] !== undefined) requireUlid(record["request_id"], status);
   if (status === 400 && code === "invalid_request") {
     throw new CustomerRuntimeGatewayError("gateway_request_invalid", status, false);
   }
@@ -145,11 +150,12 @@ function throwMailError(status: number, body: unknown): never {
   if (status === 503 && typeof code === "string") {
     throw new CustomerRuntimeGatewayError("gateway_unavailable", status, true);
   }
-  return invalidResponse();
+  return invalidResponse(status);
 }
 
-function requireUlid(value: unknown): string {
-  if (typeof value !== "string" || !/^[0-9A-HJKMNP-TV-Z]{26}$/u.test(value)) invalidResponse();
+function requireUlid(value: unknown, status: number | null = null): string {
+  if (typeof value !== "string" || !/^[0-9A-HJKMNP-TV-Z]{26}$/u.test(value))
+    invalidResponse(status);
   return value;
 }
 

package/src/packages/customer-runtime/src/storage-batch-stream.ts

@@ -28,6 +28,7 @@ const MAX_HEADER_BYTES = 2048;
 async function timedRead(
   reader: ReadableStreamDefaultReader<Uint8Array>,
   timeoutMilliseconds: number,
+  status: number,
   signal?: AbortSignal,
 ): Promise<ReadableStreamReadResult<Uint8Array>> {
   let timer: ReturnType<typeof setTimeout> | undefined;
@@ -35,13 +36,13 @@ async function timedRead(
   try {
     if (signal?.aborted) {
       void reader.cancel().catch(() => undefined);
-      throw new CustomerRuntimeGatewayError("gateway_timeout", null, true);
+      throw new CustomerRuntimeGatewayError("gateway_timeout", status, true);
     }
     return await Promise.race([
       reader.read(),
       new Promise<never>((_resolve, reject) => {
         const abort = () => {
-          reject(new CustomerRuntimeGatewayError("gateway_timeout", null, true));
+          reject(new CustomerRuntimeGatewayError("gateway_timeout", status, true));
           void reader.cancel().catch(() => undefined);
         };
         timer = setTimeout(abort, timeoutMilliseconds);
@@ -53,8 +54,8 @@ async function timedRead(
     ]);
   } catch (error) {
     if (error instanceof CustomerRuntimeGatewayError) throw error;
-    if (signal?.aborted) throw new CustomerRuntimeGatewayError("gateway_timeout", null, true);
-    throw new CustomerRuntimeGatewayError("gateway_unavailable", null, true);
+    if (signal?.aborted) throw new CustomerRuntimeGatewayError("gateway_timeout", status, true);
+    throw new CustomerRuntimeGatewayError("gateway_unavailable", status, true);
   } finally {
     clearTimeout(timer);
     if (abortListener !== undefined) signal?.removeEventListener("abort", abortListener);
@@ -72,7 +73,7 @@ export function decodeStorageBatch(
     response.body === null
   ) {
     void response.body?.cancel().catch(() => undefined);
-    invalidResponse();
+    invalidResponse(response.status);
   }
   const source = response.body.getReader();
   const decoder = new TextDecoder("utf-8", { fatal: true });
@@ -101,9 +102,9 @@ export function decodeStorageBatch(
   async function chunk(maximum: number): Promise<Uint8Array> {
     if (cancelled) throw cancellationError();
     while (offset === buffer.byteLength) {
-      const next = await timedRead(source, timeoutMilliseconds);
+      const next = await timedRead(source, timeoutMilliseconds, response.status);
       if (cancelled) throw cancellationError();
-      if (next.done || !(next.value instanceof Uint8Array)) invalidResponse();
+      if (next.done || !(next.value instanceof Uint8Array)) invalidResponse(response.status);
       buffer = next.value;
       offset = 0;
     }
@@ -126,7 +127,7 @@ export function decodeStorageBatch(
     const length = new DataView((await exactBytes(4)).buffer).getUint32(0);
     controlBytes += 4 + length;
     if (length < 1 || length > MAX_HEADER_BYTES || controlBytes > MAX_CONTROL_BYTES)
-      invalidResponse();
+      invalidResponse(response.status);
     const bytes = await exactBytes(length);
     return parseHeader(bytes);
   }
@@ -135,7 +136,7 @@ export function decodeStorageBatch(
     if (buffer.byteLength - offset < 4) return undefined;
     const length = new DataView(buffer.buffer, buffer.byteOffset + offset, 4).getUint32(0);
     if (length < 1 || length > MAX_HEADER_BYTES || controlBytes + 4 + length > MAX_CONTROL_BYTES)
-      invalidResponse();
+      invalidResponse(response.status);
     if (buffer.byteLength - offset < 4 + length) return undefined;
     controlBytes += 4 + length;
     const bytes = buffer.subarray(offset + 4, offset + 4 + length);
@@ -146,7 +147,7 @@ export function decodeStorageBatch(
     try {
       return JSON.parse(decoder.decode(bytes)) as unknown;
     } catch {
-      return invalidResponse();
+      return invalidResponse(response.status);
     }
   }
   const iterator = iterate();
@@ -173,7 +174,7 @@ export function decodeStorageBatch(
     try {
       for (let index = 0; index < keys.length; index++) {
         const objectKey = keys[index];
-        if (objectKey === undefined) invalidResponse();
+        if (objectKey === undefined) invalidResponse(response.status);
         if (!currentConsumed)
           throw new CustomerRuntimeGatewayError(
             "gateway_request_invalid",
@@ -190,8 +191,10 @@ export function decodeStorageBatch(
           candidate?.["state"] === "found"
             ? ["index", "objectKey", "state", "contentType", "contentLength", "etag"]
             : ["index", "objectKey", "state"],
+          response.status,
         );
-        if (record["index"] !== index || record["objectKey"] !== keys[index]) invalidResponse();
+        if (record["index"] !== index || record["objectKey"] !== keys[index])
+          invalidResponse(response.status);
         if (record["state"] === "not_found") {
           yield Object.freeze({ state: "not_found", objectKey });
           continue;
@@ -208,7 +211,7 @@ export function decodeStorageBatch(
           typeof record["etag"] !== "string" ||
           !/^[0-9a-f]{32}(?:-[1-9][0-9]{0,4})?$/u.test(record["etag"])
         )
-          invalidResponse();
+          invalidResponse(response.status);
         let remaining = Number(record["contentLength"]);
         currentConsumed = remaining === 0;
         const body = new ReadableStream<Uint8Array>(
@@ -268,18 +271,19 @@ export function decodeStorageBatch(
         );
       if (bodyFailure !== undefined) throw bodyFailure;
       const buffered = bufferedHeader();
-      const terminal = exactRecord(buffered === undefined ? await header() : buffered, [
-        "state",
-        "count",
-      ]);
+      const terminal = exactRecord(
+        buffered === undefined ? await header() : buffered,
+        ["state", "count"],
+        response.status,
+      );
       if (
         terminal["state"] !== "completed" ||
         terminal["count"] !== keys.length ||
         offset !== buffer.byteLength
       )
-        invalidResponse();
-      const end = await timedRead(source, timeoutMilliseconds);
-      if (!end.done) invalidResponse();
+        invalidResponse(response.status);
+      const end = await timedRead(source, timeoutMilliseconds, response.status);
+      if (!end.done) invalidResponse(response.status);
       if (cancelled) throw cancellationError();
       finished = true;
     } finally {
@@ -303,7 +307,7 @@ export async function readStorageBatchJson(
     response.body === null
   ) {
     void response.body?.cancel().catch(() => undefined);
-    invalidResponse();
+    invalidResponse(response.status);
   }
   const reader = response.body.getReader();
   const chunks: Uint8Array[] = [];
@@ -311,14 +315,14 @@ export async function readStorageBatchJson(
   let finished = false;
   try {
     for (;;) {
-      const next = await timedRead(reader, timeoutMilliseconds, signal);
+      const next = await timedRead(reader, timeoutMilliseconds, response.status, signal);
       if (next.done) {
         finished = true;
         break;
       }
-      if (!(next.value instanceof Uint8Array)) invalidResponse();
+      if (!(next.value instanceof Uint8Array)) invalidResponse(response.status);
       length += next.value.byteLength;
-      if (length > MAX_CONTROL_BYTES) invalidResponse();
+      if (length > MAX_CONTROL_BYTES) invalidResponse(response.status);
       chunks.push(next.value);
     }
   } finally {
@@ -334,6 +338,6 @@ export async function readStorageBatchJson(
   try {
     return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)) as unknown;
   } catch {
-    return invalidResponse();
+    return invalidResponse(response.status);
   }
 }