@ontrails/hono 1.0.0-beta.15 → 1.0.0-beta.17

package/src/surface.ts

@@ -1,5 +1,5 @@
 /**
- * Hono connector for Trails HTTP routes.
+ * Hono adapter for Trails HTTP routes.
  *
  * Takes framework-agnostic HttpRouteDefinition[] and wires them into a
  * Hono application, handling request parsing, response mapping, and errors.
@@ -10,9 +10,14 @@
  * ```
  */
 
-import { isTrailsError, mapTransportError } from '@ontrails/core';
+import {
+  isTrailsError,
+  projectErrorDiagnostics,
+  projectPublicSurfaceError,
+  ValidationError,
+} from '@ontrails/core';
 import type {
-  Intent,
+  BaseSurfaceOptions,
   Layer,
   ResourceOverrideMap,
   Topo,
@@ -22,33 +27,38 @@ import { Hono } from 'hono';
 import type { Context as HonoContext } from 'hono';
 import type { ContentfulStatusCode } from 'hono/utils/http-status';
 import { deriveHttpRoutes } from '@ontrails/http';
-import type { HttpMethod, HttpRouteDefinition } from '@ontrails/http';
+import type {
+  HttpExecutionContext,
+  HttpMethod,
+  HttpRouteDefinition,
+  ResolveHttpPermit,
+} from '@ontrails/http';
 
 // ---------------------------------------------------------------------------
 // Options
 // ---------------------------------------------------------------------------
 
-export interface CreateAppOptions {
+export interface CreateAppOptions extends BaseSurfaceOptions {
   readonly basePath?: string | undefined;
-  /** Config values for resources that declare a `config` schema, keyed by resource ID. */
-  readonly configValues?:
-    | Readonly<Record<string, Record<string, unknown>>>
-    | undefined;
   readonly createContext?:
     | (() => TrailContextInit | Promise<TrailContextInit>)
     | undefined;
-  readonly exclude?: readonly string[] | undefined;
   readonly hostname?: string | undefined;
-  readonly include?: readonly string[] | undefined;
-  readonly intent?: readonly Intent[] | undefined;
   readonly layers?: readonly Layer[] | undefined;
+  /** Maximum JSON request body size in bytes. Defaults to 1 MiB. */
+  readonly maxJsonBodyBytes?: number | undefined;
   readonly name?: string | undefined;
   readonly port?: number | undefined;
   readonly resources?: ResourceOverrideMap | undefined;
-  /** Set to `false` to skip topo validation at startup. Defaults to `true`. */
-  readonly validate?: boolean | undefined;
+  readonly resolvePermit?: ResolveHttpPermit | undefined;
+}
+
+interface RuntimeOptions {
+  readonly maxJsonBodyBytes: number;
 }
 
+const DEFAULT_MAX_JSON_BODY_BYTES = 1024 * 1024;
+
 export interface SurfaceHttpResult {
   readonly close: () => Promise<void>;
   readonly url: string;
@@ -63,7 +73,7 @@ export interface SurfaceHttpResult {
  *
  * A single `?tag=one` stays a scalar string, while repeated keys like
  * `?tag=one&tag=two` become arrays. Schema validation owns whether that shape
- * is accepted; the connector does not coerce singleton values into arrays.
+ * is accepted; the adapter does not coerce singleton values into arrays.
  */
 const parseQueryParams = (c: HonoContext): Record<string, unknown> => {
   const result: Record<string, unknown> = {};
@@ -85,32 +95,226 @@ const parseQueryParams = (c: HonoContext): Record<string, unknown> => {
 /** Sentinel indicating a JSON parse failure. */
 const JSON_PARSE_ERROR = Symbol('JSON_PARSE_ERROR');
 
+/** Sentinel indicating a JSON body rejected before parsing. */
+const JSON_BODY_TOO_LARGE = Symbol('JSON_BODY_TOO_LARGE');
+
+/** Sentinel indicating malformed body metadata. */
+const JSON_BODY_INVALID_CONTENT_LENGTH = Symbol(
+  'JSON_BODY_INVALID_CONTENT_LENGTH'
+);
+
+interface JsonObject {
+  readonly [key: string]: JsonValue;
+}
+
+type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly JsonValue[]
+  | JsonObject;
+type JsonBodyReadResult =
+  | JsonValue
+  | typeof JSON_BODY_INVALID_CONTENT_LENGTH
+  | typeof JSON_PARSE_ERROR
+  | typeof JSON_BODY_TOO_LARGE;
+type JsonBodyTextReadResult = string | typeof JSON_BODY_TOO_LARGE;
+type InputReadResult = Record<string, unknown> | JsonBodyReadResult;
+
+const CONTENT_LENGTH_DECIMAL_PATTERN = /^\d+$/;
+
 /** Return true when the request has no body content. */
+type ParsedContentLength =
+  | number
+  | typeof JSON_BODY_INVALID_CONTENT_LENGTH
+  | undefined;
+
+const parseContentLength = (
+  contentLength: string | undefined
+): ParsedContentLength => {
+  if (contentLength === undefined) {
+    return undefined;
+  }
+  if (!CONTENT_LENGTH_DECIMAL_PATTERN.test(contentLength)) {
+    return JSON_BODY_INVALID_CONTENT_LENGTH;
+  }
+  const size = Number(contentLength);
+  return Number.isSafeInteger(size) ? size : Number.MAX_SAFE_INTEGER;
+};
+
 const isEmptyBody = (c: HonoContext): boolean => {
-  const contentLength = c.req.header('Content-Length');
+  const contentLength = parseContentLength(c.req.header('Content-Length'));
+  if (contentLength === JSON_BODY_INVALID_CONTENT_LENGTH) {
+    return false;
+  }
   if (contentLength !== undefined) {
-    return Number.parseInt(contentLength, 10) === 0;
+    return contentLength === 0;
   }
   // No Content-Length header — treat as empty when Content-Type is also absent.
   return c.req.header('Content-Type') === undefined;
 };
 
+const resolveMaxJsonBodyBytes = (value: number | undefined): number => {
+  const maxJsonBodyBytes = value ?? DEFAULT_MAX_JSON_BODY_BYTES;
+
+  if (!Number.isFinite(maxJsonBodyBytes) || maxJsonBodyBytes < 1) {
+    throw new ValidationError(
+      'maxJsonBodyBytes must be a positive finite number'
+    );
+  }
+
+  return maxJsonBodyBytes;
+};
+
+const hasOversizedContentLength = (
+  c: HonoContext,
+  maxJsonBodyBytes: number
+): boolean => {
+  const contentLength = c.req.header('Content-Length');
+  if (contentLength === undefined) {
+    return false;
+  }
+  const size = parseContentLength(contentLength);
+  if (size === JSON_BODY_INVALID_CONTENT_LENGTH) {
+    return false;
+  }
+  return size !== undefined && size > maxJsonBodyBytes;
+};
+
+const measureBodyTextBytes = (text: string): number => new Blob([text]).size;
+
+const validateCachedBodyText = (
+  text: string,
+  maxJsonBodyBytes: number
+): JsonBodyTextReadResult =>
+  measureBodyTextBytes(text) > maxJsonBodyBytes ? JSON_BODY_TOO_LARGE : text;
+
+const readCachedBodyText = async (
+  c: HonoContext,
+  maxJsonBodyBytes: number
+): Promise<JsonBodyTextReadResult> =>
+  validateCachedBodyText(await c.req.text(), maxJsonBodyBytes);
+
+const readBodyText = async (
+  c: HonoContext,
+  maxJsonBodyBytes: number
+): Promise<string | typeof JSON_BODY_TOO_LARGE> => {
+  if (c.req.raw.bodyUsed) {
+    return await readCachedBodyText(c, maxJsonBodyBytes);
+  }
+
+  const { body } = c.req.raw;
+  if (body === null) {
+    return '';
+  }
+
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let totalBytes = 0;
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      if (value === undefined) {
+        continue;
+      }
+      totalBytes += value.byteLength;
+      if (totalBytes > maxJsonBodyBytes) {
+        await reader.cancel();
+        return JSON_BODY_TOO_LARGE;
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock();
+  }
+
+  const bytes = new Uint8Array(totalBytes);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+
+  return new TextDecoder().decode(bytes);
+};
+
+const readJsonBody = async (
+  c: HonoContext,
+  maxJsonBodyBytes: number
+): Promise<JsonBodyReadResult> => {
+  if (
+    parseContentLength(c.req.header('Content-Length')) ===
+    JSON_BODY_INVALID_CONTENT_LENGTH
+  ) {
+    return JSON_BODY_INVALID_CONTENT_LENGTH;
+  }
+
+  if (hasOversizedContentLength(c, maxJsonBodyBytes)) {
+    return JSON_BODY_TOO_LARGE;
+  }
+
+  const text = await readBodyText(c, maxJsonBodyBytes);
+  if (text === JSON_BODY_TOO_LARGE) {
+    return JSON_BODY_TOO_LARGE;
+  }
+
+  try {
+    return JSON.parse(text) as JsonValue;
+  } catch {
+    return JSON_PARSE_ERROR;
+  }
+};
+
+const parseJsonBodyText = (text: string): JsonBodyReadResult => {
+  try {
+    return JSON.parse(text) as JsonValue;
+  } catch {
+    return JSON_PARSE_ERROR;
+  }
+};
+
+const parseWebhookBodyText = (
+  c: HonoContext,
+  text: string
+): JsonBodyReadResult =>
+  isEmptyBody(c) || text.length === 0 ? {} : parseJsonBodyText(text);
+
+const readWebhookBodyText = async (
+  c: HonoContext,
+  maxJsonBodyBytes: number
+): Promise<
+  string | typeof JSON_BODY_INVALID_CONTENT_LENGTH | typeof JSON_BODY_TOO_LARGE
+> => {
+  if (
+    parseContentLength(c.req.header('Content-Length')) ===
+    JSON_BODY_INVALID_CONTENT_LENGTH
+  ) {
+    return JSON_BODY_INVALID_CONTENT_LENGTH;
+  }
+  if (hasOversizedContentLength(c, maxJsonBodyBytes)) {
+    return JSON_BODY_TOO_LARGE;
+  }
+  return await readBodyText(c, maxJsonBodyBytes);
+};
+
 /** Read input from request based on input source. */
 const readInput = async (
   c: HonoContext,
-  inputSource: 'query' | 'body'
-): Promise<unknown> => {
+  inputSource: 'query' | 'body',
+  options: RuntimeOptions
+): Promise<InputReadResult> => {
   if (inputSource === 'query') {
     return parseQueryParams(c);
   }
   if (isEmptyBody(c)) {
     return {};
   }
-  try {
-    return await c.req.json();
-  } catch {
-    return JSON_PARSE_ERROR;
-  }
+  return await readJsonBody(c, options.maxJsonBodyBytes);
 };
 
 // ---------------------------------------------------------------------------
@@ -121,30 +325,44 @@ const readInput = async (
 const mapErrorResponse = (
   error: Error
 ): { body: Record<string, unknown>; status: ContentfulStatusCode } => {
-  if (isTrailsError(error)) {
-    return {
-      body: {
-        error: {
-          category: error.category,
-          code: error.name,
-          message: error.message,
-        },
-      },
-      status: mapTransportError('http', error) as ContentfulStatusCode,
-    };
-  }
+  const projection = projectPublicSurfaceError('http', error);
   return {
     body: {
       error: {
-        category: 'internal',
-        code: 'InternalError',
-        message: error.message,
+        category: projection.category,
+        code: projection.name,
+        message: projection.message,
       },
     },
-    status: 500,
+    status: projection.code as ContentfulStatusCode,
   };
 };
 
+const LOG_UNSAFE_LABEL_CHARACTERS = /[^\w:.-]/g;
+const MAX_DIAGNOSTIC_LABEL_VALUE_LENGTH = 128;
+
+const sanitizeDiagnosticLabelValue = (value: string): string =>
+  value
+    .replace(LOG_UNSAFE_LABEL_CHARACTERS, '_')
+    .slice(0, MAX_DIAGNOSTIC_LABEL_VALUE_LENGTH);
+
+const reportInternalDiagnostics = (error: Error, c: HonoContext): void => {
+  if (isTrailsError(error)) {
+    return;
+  }
+
+  const requestId = c.req.header('X-Request-ID');
+  const safeRequestId =
+    requestId === undefined
+      ? undefined
+      : sanitizeDiagnosticLabelValue(requestId);
+  const label =
+    safeRequestId === undefined
+      ? '[ontrails:hono] Internal error'
+      : `[ontrails:hono] Internal error (${safeRequestId})`;
+  console.error(label, projectErrorDiagnostics(error));
+};
+
 // ---------------------------------------------------------------------------
 // Route registration
 // ---------------------------------------------------------------------------
@@ -157,43 +375,193 @@ const mapResultToResponse = (
   if (result.isOk()) {
     return c.json({ data: result.value }, 200);
   }
-  const { body, status } = mapErrorResponse(
-    result.error ?? new Error('Unknown error')
-  );
+  const error = result.error ?? new Error('Unknown error');
+  reportInternalDiagnostics(error, c);
+  const { body, status } = mapErrorResponse(error);
   return c.json(body, status);
 };
 
 /** Convert a caught unknown value to an error response. */
 const handleCaughtError = (error: unknown, c: HonoContext): Response => {
   const err = error instanceof Error ? error : new Error(String(error));
+  reportInternalDiagnostics(err, c);
   const { body, status } = mapErrorResponse(err);
   return c.json(body, status);
 };
 
+const invalidJsonResponse = (c: HonoContext): Response =>
+  c.json(
+    {
+      error: {
+        category: 'validation',
+        code: 'ValidationError',
+        message: 'Invalid JSON in request body',
+      },
+    },
+    400
+  );
+
+const invalidContentLengthResponse = (c: HonoContext): Response =>
+  c.json(
+    {
+      error: {
+        category: 'validation',
+        code: 'ValidationError',
+        message: 'Invalid Content-Length header',
+      },
+    },
+    400
+  );
+
+const oversizedJsonBodyResponse = (
+  c: HonoContext,
+  options: RuntimeOptions
+): Response =>
+  c.json(
+    {
+      error: {
+        category: 'validation',
+        code: 'ValidationError',
+        message: `JSON request body exceeds ${options.maxJsonBodyBytes} bytes`,
+      },
+    },
+    413
+  );
+
+const collectHeaders = (c: HonoContext): Record<string, string> => {
+  const headers: Record<string, string> = {};
+  for (const [key, value] of c.req.raw.headers) {
+    headers[key] = value;
+  }
+  return headers;
+};
+
+const createHttpExecutionContext = (c: HonoContext): HttpExecutionContext => ({
+  headers: c.req.raw.headers,
+});
+
+const createWebhookVerifyRequest = (
+  c: HonoContext,
+  body: string
+): {
+  readonly body: string;
+  readonly headers: Record<string, string>;
+  readonly method: string;
+  readonly path: string;
+} => ({
+  body,
+  headers: collectHeaders(c),
+  method: c.req.method,
+  path: new URL(c.req.url).pathname,
+});
+
+const recordInvalidWebhook = async (
+  route: HttpRouteDefinition,
+  errorCategory = 'validation'
+): Promise<void> => {
+  await route.recordWebhookInvalid?.(errorCategory);
+};
+
+const errorCategoryForWebhookFailure = (error: Error | undefined): string =>
+  error !== undefined && isTrailsError(error) ? error.category : 'internal';
+
+const handleWebhookRoute = async (
+  route: HttpRouteDefinition,
+  options: RuntimeOptions,
+  c: HonoContext
+): Promise<Response> => {
+  const rawBody = await readWebhookBodyText(c, options.maxJsonBodyBytes);
+
+  if (rawBody === JSON_BODY_INVALID_CONTENT_LENGTH) {
+    await recordInvalidWebhook(route);
+    return invalidContentLengthResponse(c);
+  }
+
+  if (rawBody === JSON_BODY_TOO_LARGE) {
+    await recordInvalidWebhook(route);
+    return oversizedJsonBodyResponse(c, options);
+  }
+
+  const verified = await route.verifyWebhook?.(
+    createWebhookVerifyRequest(c, rawBody)
+  );
+  if (verified?.isErr()) {
+    await recordInvalidWebhook(
+      route,
+      errorCategoryForWebhookFailure(verified.error)
+    );
+    return mapResultToResponse(verified, c);
+  }
+
+  const jsonBody = parseWebhookBodyText(c, rawBody);
+  if (jsonBody === JSON_PARSE_ERROR) {
+    await recordInvalidWebhook(route);
+    return invalidJsonResponse(c);
+  }
+
+  const parsed = route.parseWebhookInput?.(jsonBody);
+  if (parsed === undefined) {
+    await recordInvalidWebhook(route);
+    return mapResultToResponse(
+      {
+        error: new ValidationError('Webhook route is missing parse handler'),
+        isOk: () => false,
+      },
+      c
+    );
+  }
+  if (parsed.isErr()) {
+    await recordInvalidWebhook(route);
+    return mapResultToResponse(parsed, c);
+  }
+
+  const requestId = c.req.header('X-Request-ID') ?? undefined;
+  const { signal: abortSignal } = c.req.raw;
+  const result = await route.execute(
+    parsed.value,
+    requestId,
+    abortSignal,
+    createHttpExecutionContext(c)
+  );
+  return mapResultToResponse(result, c);
+};
+
 /** Create a Hono handler from a route definition. */
 const createHonoHandler =
-  (route: HttpRouteDefinition) =>
+  (route: HttpRouteDefinition, options: RuntimeOptions) =>
   async (c: HonoContext): Promise<Response> => {
-    const rawInput = await readInput(c, route.inputSource);
+    if (route.inputSource === 'webhook') {
+      try {
+        return await handleWebhookRoute(route, options, c);
+      } catch (error: unknown) {
+        return handleCaughtError(error, c);
+      }
+    }
+
+    const rawInput = await readInput(c, route.inputSource, options);
 
     if (rawInput === JSON_PARSE_ERROR) {
-      return c.json(
-        {
-          error: {
-            category: 'validation',
-            code: 'ValidationError',
-            message: 'Invalid JSON in request body',
-          },
-        },
-        400
-      );
+      return invalidJsonResponse(c);
+    }
+
+    if (rawInput === JSON_BODY_INVALID_CONTENT_LENGTH) {
+      return invalidContentLengthResponse(c);
+    }
+
+    if (rawInput === JSON_BODY_TOO_LARGE) {
+      return oversizedJsonBodyResponse(c, options);
     }
 
     const requestId = c.req.header('X-Request-ID') ?? undefined;
     const { signal: abortSignal } = c.req.raw;
 
     try {
-      const result = await route.execute(rawInput, requestId, abortSignal);
+      const result = await route.execute(
+        rawInput,
+        requestId,
+        abortSignal,
+        createHttpExecutionContext(c)
+      );
       return mapResultToResponse(result, c);
     } catch (error: unknown) {
       return handleCaughtError(error, c);
@@ -215,14 +583,24 @@ const routeRegistrars: Record<
   GET: (hono, path, handler) => {
     hono.get(path, handler);
   },
+  PATCH: (hono, path, handler) => {
+    hono.patch(path, handler);
+  },
   POST: (hono, path, handler) => {
     hono.post(path, handler);
   },
+  PUT: (hono, path, handler) => {
+    hono.put(path, handler);
+  },
 };
 
-const registerRoutes = (hono: Hono, routes: HttpRouteDefinition[]): void => {
+const registerRoutes = (
+  hono: Hono,
+  routes: HttpRouteDefinition[],
+  options: RuntimeOptions
+): void => {
   for (const route of routes) {
-    const handler = createHonoHandler(route);
+    const handler = createHonoHandler(route, options);
     routeRegistrars[route.method](hono, route.path, handler);
   }
 };
@@ -233,18 +611,7 @@ const registerRoutes = (hono: Hono, routes: HttpRouteDefinition[]): void => {
 
 const registerErrorHandler = (hono: Hono): void => {
   // oxlint-disable-next-line prefer-await-to-callbacks -- Hono's onError API requires a callback
-  hono.onError((err, c) =>
-    c.json(
-      {
-        error: {
-          category: 'internal',
-          code: 'InternalError',
-          message: err.message,
-        },
-      },
-      500
-    )
-  );
+  hono.onError((err, c) => handleCaughtError(err, c));
 };
 
 // ---------------------------------------------------------------------------
@@ -257,12 +624,27 @@ const registerErrorHandler = (hono: Hono): void => {
 
 /**
  * Build HTTP routes from a topo and register them on a Hono app.
+ *
+ * @remarks This is a host materialization boundary. Derivation failures are
+ * thrown for HTTP bootstrap code after `deriveHttpRoutes` has already
+ * represented the framework error as a Result.
+ *
+ * @example
+ * ```ts
+ * import { createApp } from '@ontrails/hono';
+ *
+ * const app = createApp(graph, { basePath: '/api' });
+ * Bun.serve({ fetch: app.fetch, port: 3000 });
+ * ```
  */
 export const createApp = (
   graph: Topo,
   options: CreateAppOptions = {}
 ): Hono => {
   const hono = new Hono();
+  const runtimeOptions = {
+    maxJsonBodyBytes: resolveMaxJsonBodyBytes(options.maxJsonBodyBytes),
+  };
 
   registerErrorHandler(hono);
 
@@ -274,6 +656,7 @@ export const createApp = (
     include: options.include,
     intent: options.intent,
     layers: options.layers,
+    resolvePermit: options.resolvePermit,
     resources: options.resources,
     validate: options.validate,
   });
@@ -282,7 +665,7 @@ export const createApp = (
     throw routesResult.error;
   }
 
-  registerRoutes(hono, routesResult.value);
+  registerRoutes(hono, routesResult.value, runtimeOptions);
   return hono;
 };
 
@@ -313,6 +696,14 @@ const startServer = (
  *
  * @remarks Always starts a Bun server. Use `createApp(graph)` for an
  * unserved Hono app that you can wire into your own server.
+ *
+ * @example
+ * ```ts
+ * import { surface } from '@ontrails/hono';
+ *
+ * const server = await surface(graph, { port: 3000 });
+ * console.log(server.url);
+ * ```
  */
 export const surface = async (
   graph: Topo,

package/.turbo/turbo-build.log

@@ -1 +0,0 @@
-$ tsc -b

package/.turbo/turbo-lint.log

@@ -1,3 +0,0 @@
-$ oxlint ./src
-Found 0 warnings and 0 errors.
-Finished in 69ms on 3 files with 93 rules using 24 threads.

package/.turbo/turbo-typecheck.log

@@ -1 +0,0 @@
-$ tsc --noEmit

package/dist/index.d.ts

@@ -1,2 +0,0 @@
-export { createApp, surface, type CreateAppOptions, type SurfaceHttpResult, } from './surface.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,OAAO,EACP,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,GACvB,MAAM,cAAc,CAAC"}