@amerged/ohmyhost-runtime 0.1.10

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

@@ -0,0 +1,57 @@
+export type CustomerRuntimeGatewayErrorCode =
+  | "gateway_configuration_invalid"
+  | "gateway_request_invalid"
+  | "gateway_response_invalid"
+  | "gateway_timeout"
+  | "gateway_unavailable"
+  | "mail_credit_insufficient"
+  | "mail_rejected"
+  | "mail_reputation_suspended"
+  | "mail_send_conflict"
+  | "mail_send_limit_exceeded"
+  | "storage_conflict"
+  | "storage_object_not_found"
+  | "storage_quota_exceeded"
+  | "storage_upload_expired"
+  | "storage_upload_rejected"
+  | "unauthorized";
+
+export type CustomerRuntimeErrorCode =
+  | CustomerRuntimeGatewayErrorCode
+  | "database_query_invalid"
+  | "database_response_invalid"
+  | "database_unavailable"
+  | "scheduled_context_invalid";
+
+export class CustomerRuntimeError extends Error {
+  public constructor(
+    public readonly code: CustomerRuntimeErrorCode,
+    public readonly retryable: boolean,
+  ) {
+    super(code);
+    this.name = "CustomerRuntimeError";
+  }
+}
+
+/** A verified PostgreSQL statement failure, without SQL, row values or provider diagnostics. */
+export class CustomerDatabaseError extends Error {
+  public readonly retryable: boolean;
+
+  public constructor(public readonly code: string) {
+    super("database_statement_failed");
+    if (!/^[0-9A-Z]{5}$/u.test(code)) throw new TypeError("Invalid SQLSTATE");
+    this.name = "CustomerDatabaseError";
+    this.retryable = code === "40001" || code === "40P01";
+  }
+}
+
+export class CustomerRuntimeGatewayError extends CustomerRuntimeError {
+  public constructor(
+    code: CustomerRuntimeGatewayErrorCode,
+    public readonly status: number | null,
+    retryable: boolean,
+  ) {
+    super(code, retryable);
+    this.name = "CustomerRuntimeGatewayError";
+  }
+}

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

@@ -0,0 +1,135 @@
+import { CustomerRuntimeGatewayError } from "./errors.js";
+
+const MAX_RESPONSE_BYTES = 32 * 1024;
+const DEFAULT_TIMEOUT_MILLISECONDS = 10_000;
+
+export interface GatewayConnection {
+  readonly endpoint: string;
+  readonly key: string;
+  readonly fetch: (request: Request) => Promise<Response>;
+  readonly timeoutMilliseconds?: number;
+}
+
+export interface ValidatedGatewayConnection {
+  readonly endpoint: string;
+  readonly key: string;
+  readonly fetch: (request: Request) => Promise<Response>;
+  readonly timeoutMilliseconds: number;
+}
+
+export function validateGatewayConnection(value: GatewayConnection): ValidatedGatewayConnection {
+  assertServerRuntime();
+  let endpoint: URL;
+  try {
+    endpoint = new URL(value.endpoint);
+  } catch {
+    throw new CustomerRuntimeGatewayError("gateway_configuration_invalid", null, false);
+  }
+  const timeoutMilliseconds = value.timeoutMilliseconds ?? DEFAULT_TIMEOUT_MILLISECONDS;
+  if (
+    endpoint.protocol !== "https:" ||
+    endpoint.username !== "" ||
+    endpoint.password !== "" ||
+    endpoint.pathname !== "/" ||
+    endpoint.search !== "" ||
+    endpoint.hash !== "" ||
+    !/^[A-Za-z0-9_-]{43}$/u.test(value.key) ||
+    typeof value.fetch !== "function" ||
+    !Number.isSafeInteger(timeoutMilliseconds) ||
+    timeoutMilliseconds < 100 ||
+    timeoutMilliseconds > 30_000
+  ) {
+    throw new CustomerRuntimeGatewayError("gateway_configuration_invalid", null, false);
+  }
+  return Object.freeze({
+    endpoint: endpoint.href,
+    key: value.key,
+    fetch: value.fetch,
+    timeoutMilliseconds,
+  });
+}
+
+export async function postGatewayJson(
+  connection: ValidatedGatewayConnection,
+  path: string,
+  body: Readonly<Record<string, unknown>>,
+  maximumRequestBytes: number,
+  idempotencyKey?: string,
+): Promise<{ readonly status: number; readonly body: unknown }> {
+  const serializedBody = JSON.stringify(body);
+  if (new TextEncoder().encode(serializedBody).byteLength > maximumRequestBytes) {
+    throw new CustomerRuntimeGatewayError("gateway_request_invalid", null, false);
+  }
+  const response = await fetchWithTimeout(
+    connection.fetch,
+    new Request(new URL(path, connection.endpoint), {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${connection.key}`,
+        "content-type": "application/json",
+        ...(idempotencyKey === undefined ? {} : { "idempotency-key": idempotencyKey }),
+      },
+      body: serializedBody,
+    }),
+    connection.timeoutMilliseconds,
+  );
+  return Object.freeze({ status: response.status, body: await readBoundedJson(response) });
+}
+
+export async function fetchWithTimeout(
+  fetch: (request: Request) => Promise<Response>,
+  request: Request,
+  timeoutMilliseconds: number,
+): Promise<Response> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMilliseconds);
+  try {
+    return await fetch(new Request(request, { signal: controller.signal }));
+  } catch (error) {
+    if (error instanceof CustomerRuntimeGatewayError) throw error;
+    if (controller.signal.aborted) {
+      throw new CustomerRuntimeGatewayError("gateway_timeout", null, true);
+    }
+    throw new CustomerRuntimeGatewayError("gateway_unavailable", null, true);
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export function exactRecord(value: unknown, keys: readonly string[]): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) invalidResponse();
+  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();
+  }
+  return record;
+}
+
+export function invalidResponse(): never {
+  throw new CustomerRuntimeGatewayError("gateway_response_invalid", null, false);
+}
+
+function assertServerRuntime(): void {
+  if (typeof window !== "undefined") {
+    throw new CustomerRuntimeGatewayError("gateway_configuration_invalid", null, false);
+  }
+}
+
+async function readBoundedJson(response: Response): Promise<unknown> {
+  if (response.headers.get("content-type")?.split(";", 1)[0]?.trim() !== "application/json") {
+    invalidResponse();
+  }
+  const declared = response.headers.get("content-length");
+  if (declared !== null && (!/^[0-9]+$/u.test(declared) || Number(declared) > MAX_RESPONSE_BYTES)) {
+    invalidResponse();
+  }
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  if (bytes.byteLength > MAX_RESPONSE_BYTES) invalidResponse();
+  try {
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  } catch {
+    return invalidResponse();
+  }
+}

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

@@ -0,0 +1,5 @@
+export * from "./errors.js";
+export * from "./database.js";
+export * from "./mail.js";
+export * from "./storage.js";
+export type { GatewayConnection } from "./http.js";

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

@@ -0,0 +1,161 @@
+import { CustomerRuntimeGatewayError } from "./errors.js";
+import {
+  exactRecord,
+  invalidResponse,
+  postGatewayJson,
+  validateGatewayConnection,
+  type GatewayConnection,
+} from "./http.js";
+
+export interface TransactionalMailInput {
+  readonly idempotencyKey: string;
+  readonly to: string;
+  readonly subject: string;
+  readonly text: string;
+  readonly html: string;
+}
+
+export type TransactionalMailResult =
+  | {
+      readonly state: "accepted";
+      readonly requestId: string;
+      readonly messageId: string;
+    }
+  | {
+      readonly state: "uncertain";
+      readonly requestId: string;
+    };
+
+export function createTransactionalMailClient(
+  configuration: GatewayConnection & { readonly projectId: string },
+) {
+  const connection = validateGatewayConnection(configuration);
+  const projectId = requireUlid(configuration.projectId);
+  return Object.freeze({
+    async send(input: TransactionalMailInput): Promise<TransactionalMailResult> {
+      validateMailInput(input);
+      const response = await postGatewayJson(
+        connection,
+        "/v1/send",
+        {
+          project_id: projectId,
+          to: input.to,
+          subject: input.subject,
+          text: input.text,
+          html: input.html,
+        },
+        256 * 1024,
+        input.idempotencyKey,
+      );
+      if (response.status !== 202) throwMailError(response.status, response.body);
+      const raw = response.body as Record<string, unknown>;
+      const stateRecord = exactRecord(
+        response.body,
+        raw?.["state"] === "accepted"
+          ? ["state", "request_id", "message_id"]
+          : ["state", "request_id"],
+      );
+      const requestId = requireUlid(stateRecord["request_id"]);
+      if (stateRecord["state"] === "uncertain") {
+        return Object.freeze({ state: "uncertain" as const, requestId });
+      }
+      if (
+        stateRecord["state"] !== "accepted" ||
+        typeof stateRecord["message_id"] !== "string" ||
+        !/^[A-Za-z0-9._-]{1,256}$/u.test(stateRecord["message_id"])
+      ) {
+        invalidResponse();
+      }
+      return Object.freeze({
+        state: "accepted" as const,
+        requestId,
+        messageId: stateRecord["message_id"],
+      });
+    },
+  });
+}
+
+function validateMailInput(input: TransactionalMailInput): void {
+  if (
+    !validIdempotencyKey(input.idempotencyKey) ||
+    !validEmail(input.to) ||
+    !validContent(input.subject, 200, 998, false) ||
+    !validContent(input.text, 65_536, 65_536, true) ||
+    !validContent(input.html, 131_072, 131_072, true)
+  ) {
+    throw new CustomerRuntimeGatewayError("gateway_request_invalid", null, false);
+  }
+}
+
+function throwMailError(status: number, body: unknown): never {
+  const raw = body as Record<string, unknown>;
+  const record = exactRecord(
+    body,
+    raw?.["request_id"] === undefined ? ["code"] : ["code", "request_id"],
+  );
+  const code = record["code"];
+  if (record["request_id"] !== undefined) requireUlid(record["request_id"]);
+  if (status === 401 && code === "unauthorized") {
+    throw new CustomerRuntimeGatewayError("unauthorized", status, false);
+  }
+  if (status === 402 && code === "mail_send_credit_exhausted") {
+    throw new CustomerRuntimeGatewayError("mail_credit_insufficient", status, false);
+  }
+  if (status === 409 && code === "mail_send_conflict") {
+    throw new CustomerRuntimeGatewayError("mail_send_conflict", status, false);
+  }
+  if (status === 423 && code === "mail_reputation_suspended") {
+    throw new CustomerRuntimeGatewayError("mail_reputation_suspended", status, false);
+  }
+  if (status === 429 && code === "mail_send_daily_limit") {
+    throw new CustomerRuntimeGatewayError("mail_send_limit_exceeded", status, true);
+  }
+  if (status === 502 && code === "mail_rejected") {
+    throw new CustomerRuntimeGatewayError("mail_rejected", status, false);
+  }
+  if (status === 503 && typeof code === "string") {
+    throw new CustomerRuntimeGatewayError("gateway_unavailable", status, true);
+  }
+  return invalidResponse();
+}
+
+function requireUlid(value: unknown): string {
+  if (typeof value !== "string" || !/^[0-9A-HJKMNP-TV-Z]{26}$/u.test(value)) invalidResponse();
+  return value;
+}
+
+function validIdempotencyKey(value: string): boolean {
+  return /^[A-Za-z0-9._:-]{1,128}$/u.test(value);
+}
+
+function validEmail(value: string): boolean {
+  return (
+    value.length <= 254 &&
+    /^[a-z0-9](?:[a-z0-9._%+-]{0,62}[a-z0-9])?@(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/u.test(
+      value,
+    )
+  );
+}
+
+function validContent(
+  value: string,
+  maximumCharacters: number,
+  maximumBytes: number,
+  allowLineBreaks: boolean,
+): boolean {
+  const characters = [...value];
+  const invalidControl = characters.some((character) => {
+    const code = character.codePointAt(0);
+    return (
+      code === undefined ||
+      code === 127 ||
+      (code < 32 && (!allowLineBreaks || (code !== 9 && code !== 10 && code !== 13)))
+    );
+  });
+  return (
+    characters.length > 0 &&
+    characters.length <= maximumCharacters &&
+    new TextEncoder().encode(value).byteLength <= maximumBytes &&
+    !invalidControl
+  );
+}

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

@@ -0,0 +1,294 @@
+import { CustomerRuntimeGatewayError } from "./errors.js";
+import {
+  exactRecord,
+  fetchWithTimeout,
+  invalidResponse,
+  postGatewayJson,
+  validateGatewayConnection,
+  type GatewayConnection,
+} from "./http.js";
+
+export interface StorageCapability {
+  readonly operation: "GET" | "PUT";
+  readonly objectKey: string;
+  readonly url: string;
+  readonly expiresAt: string;
+  readonly expectedContentLength: number | null;
+  readonly requiredHeaders: Readonly<Record<string, string>>;
+}
+
+export interface StorageUploadInput {
+  readonly idempotencyKey: string;
+  readonly objectKey: string;
+  readonly contentType: string;
+  readonly bytes: Uint8Array;
+}
+
+export function createPrivateStorageClient(
+  configuration: GatewayConnection & {
+    readonly projectId: string;
+    readonly environmentId: string;
+    readonly capabilityFetch: (request: Request) => Promise<Response>;
+  },
+) {
+  const connection = validateGatewayConnection(configuration);
+  if (typeof configuration.capabilityFetch !== "function") {
+    throw new CustomerRuntimeGatewayError("gateway_configuration_invalid", null, false);
+  }
+  const capabilityFetch = configuration.capabilityFetch;
+  const projectId = requireUlid(configuration.projectId);
+  const environmentId = requireUlid(configuration.environmentId);
+  const authenticatedBody = Object.freeze({ projectId, environmentId });
+
+  async function reserveUpload(
+    input: Omit<StorageUploadInput, "bytes"> & { contentLength: number },
+  ) {
+    validateStorageMutation(input.idempotencyKey, input.objectKey);
+    if (
+      !Number.isSafeInteger(input.contentLength) ||
+      input.contentLength < 0 ||
+      input.contentLength > 1_073_741_824 ||
+      !validContentType(input.contentType)
+    ) {
+      invalidRequest();
+    }
+    const response = await postGatewayJson(
+      connection,
+      "/v1/uploads",
+      { ...authenticatedBody, ...input },
+      8 * 1024,
+      input.idempotencyKey,
+    );
+    if (response.status !== 200) throwStorageError(response.status, response.body);
+    const record = response.body as Record<string, unknown>;
+    if (record?.["state"] === "completed") {
+      const completed = exactRecord(response.body, ["state", "transfer_id"]);
+      return Object.freeze({
+        state: "completed" as const,
+        transferId: requireUlid(completed["transfer_id"]),
+      });
+    }
+    const ready = exactRecord(response.body, ["state", "transfer_id", "capability"]);
+    if (ready["state"] !== "ready") invalidResponse();
+    return Object.freeze({
+      state: "ready" as const,
+      transferId: requireUlid(ready["transfer_id"]),
+      capability: parseCapability(ready["capability"], "PUT", input.objectKey),
+    });
+  }
+
+  async function completeUpload(transferId: string) {
+    const response = await postGatewayJson(
+      connection,
+      "/v1/uploads/complete",
+      {
+        ...authenticatedBody,
+        transferId: requireUlid(transferId),
+      },
+      8 * 1024,
+    );
+    if (response.status !== 200 && response.status !== 202) {
+      throwStorageError(response.status, response.body);
+    }
+    const record = exactRecord(response.body, ["state", "transfer_id"]);
+    if (record["state"] !== "completed" && record["state"] !== "pending") invalidResponse();
+    return Object.freeze({
+      state: record["state"],
+      transferId: requireUlid(record["transfer_id"]),
+    });
+  }
+
+  async function createSignedRead(objectKey: string) {
+    validateObjectKey(objectKey);
+    const response = await postGatewayJson(
+      connection,
+      "/v1/downloads",
+      {
+        ...authenticatedBody,
+        objectKey,
+      },
+      8 * 1024,
+    );
+    if (response.status !== 200) throwStorageError(response.status, response.body);
+    const record = exactRecord(response.body, ["state", "capability"]);
+    if (record["state"] !== "ready") invalidResponse();
+    return parseCapability(record["capability"], "GET", objectKey);
+  }
+
+  async function deleteObject(input: { idempotencyKey: string; objectKey: string }) {
+    validateStorageMutation(input.idempotencyKey, input.objectKey);
+    const response = await postGatewayJson(
+      connection,
+      "/v1/deletions",
+      { ...authenticatedBody, objectKey: input.objectKey },
+      8 * 1024,
+      input.idempotencyKey,
+    );
+    if (response.status !== 200) throwStorageError(response.status, response.body);
+    const record = exactRecord(response.body, ["state", "deletion_id"]);
+    if (record["state"] !== "completed") invalidResponse();
+    return Object.freeze({
+      state: "completed" as const,
+      deletionId: requireUlid(record["deletion_id"]),
+    });
+  }
+
+  async function upload(input: StorageUploadInput) {
+    const bytes = Uint8Array.from(input.bytes);
+    const reservation = await reserveUpload({
+      idempotencyKey: input.idempotencyKey,
+      objectKey: input.objectKey,
+      contentType: input.contentType,
+      contentLength: bytes.byteLength,
+    });
+    if (reservation.state === "completed") return reservation;
+    const uploaded = await fetchWithTimeout(
+      capabilityFetch,
+      new Request(reservation.capability.url, {
+        method: "PUT",
+        headers: reservation.capability.requiredHeaders,
+        body: bytes,
+      }),
+      connection.timeoutMilliseconds,
+    );
+    if (uploaded.status < 200 || uploaded.status >= 300) {
+      throw new CustomerRuntimeGatewayError("storage_upload_rejected", uploaded.status, false);
+    }
+    return completeUpload(reservation.transferId);
+  }
+
+  return Object.freeze({ reserveUpload, completeUpload, createSignedRead, deleteObject, upload });
+}
+
+function parseCapability(value: unknown, operation: "GET" | "PUT", objectKey: string) {
+  const record = exactRecord(value, [
+    "operation",
+    "objectKey",
+    "url",
+    "expiresAt",
+    "expectedContentLength",
+    "requiredHeaders",
+  ]);
+  const headers = exactHeaders(record["requiredHeaders"]);
+  if (
+    record["operation"] !== operation ||
+    record["objectKey"] !== objectKey ||
+    typeof record["url"] !== "string" ||
+    !validSignedUrl(record["url"]) ||
+    typeof record["expiresAt"] !== "string" ||
+    !Number.isFinite(Date.parse(record["expiresAt"])) ||
+    (record["expectedContentLength"] !== null &&
+      (!Number.isSafeInteger(record["expectedContentLength"]) ||
+        Number(record["expectedContentLength"]) < 0 ||
+        Number(record["expectedContentLength"]) > 1_073_741_824))
+  ) {
+    invalidResponse();
+  }
+  return Object.freeze({
+    operation,
+    objectKey,
+    url: record["url"],
+    expiresAt: record["expiresAt"],
+    expectedContentLength:
+      record["expectedContentLength"] === null ? null : Number(record["expectedContentLength"]),
+    requiredHeaders: headers,
+  });
+}
+
+function exactHeaders(value: unknown): Readonly<Record<string, string>> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) invalidResponse();
+  const entries = Object.entries(value as Record<string, unknown>);
+  if (
+    entries.length > 16 ||
+    entries.some(
+      ([name, header]) =>
+        !/^[a-z0-9-]{1,64}$/u.test(name) ||
+        /^(authorization|cookie|set-cookie)$/u.test(name) ||
+        typeof header !== "string" ||
+        header.length > 1_024 ||
+        /[\r\n]/u.test(header),
+    )
+  ) {
+    invalidResponse();
+  }
+  return Object.freeze(Object.fromEntries(entries) as Record<string, string>);
+}
+
+function throwStorageError(status: number, body: unknown): never {
+  const record = exactRecord(
+    body,
+    typeof body === "object" && body !== null && "transfer_id" in body
+      ? ["code", "transfer_id"]
+      : ["code"],
+  );
+  const code = record["code"];
+  if (status === 401 && code === "unauthorized") {
+    throw new CustomerRuntimeGatewayError("unauthorized", status, false);
+  }
+  if (status === 404 && code === "object_not_found") {
+    throw new CustomerRuntimeGatewayError("storage_object_not_found", status, false);
+  }
+  if (status === 409 && code === "upload_expired") {
+    requireUlid(record["transfer_id"]);
+    throw new CustomerRuntimeGatewayError("storage_upload_expired", status, false);
+  }
+  if (status === 409 && typeof code === "string") {
+    throw new CustomerRuntimeGatewayError("storage_conflict", status, false);
+  }
+  if (status === 413 && typeof code === "string") {
+    throw new CustomerRuntimeGatewayError("storage_quota_exceeded", status, false);
+  }
+  if (status === 503 && code === "storage_gateway_unavailable") {
+    throw new CustomerRuntimeGatewayError("gateway_unavailable", status, true);
+  }
+  return invalidResponse();
+}
+
+function validateStorageMutation(idempotencyKey: string, objectKey: string): void {
+  if (!/^[A-Za-z0-9._:-]{1,128}$/u.test(idempotencyKey)) invalidRequest();
+  validateObjectKey(objectKey);
+}
+
+function validateObjectKey(value: string): void {
+  const bytes = new TextEncoder().encode(value).byteLength;
+  if (
+    bytes < 1 ||
+    bytes > 512 ||
+    value.startsWith("/") ||
+    value.endsWith("/") ||
+    value.includes("//") ||
+    !value
+      .split("/")
+      .every((segment) => /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,126}[A-Za-z0-9])?$/u.test(segment))
+  ) {
+    invalidRequest();
+  }
+}
+
+function validContentType(value: string): boolean {
+  return /^[a-z0-9][a-z0-9!#$&^_.+-]{0,63}\/[a-z0-9][a-z0-9!#$&^_.+-]{0,63}$/u.test(value);
+}
+
+function validSignedUrl(value: string): boolean {
+  try {
+    const url = new URL(value);
+    return (
+      url.protocol === "https:" &&
+      url.username === "" &&
+      url.password === "" &&
+      url.hash === "" &&
+      value.length <= 8_192
+    );
+  } catch {
+    return false;
+  }
+}
+
+function requireUlid(value: unknown): string {
+  if (typeof value !== "string" || !/^[0-9A-HJKMNP-TV-Z]{26}$/u.test(value)) invalidResponse();
+  return value;
+}
+
+function invalidRequest(): never {
+  throw new CustomerRuntimeGatewayError("gateway_request_invalid", null, false);
+}