@ontrails/http 1.0.0-beta.32 → 1.0.0-beta.39

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @ontrails/http
 
+## 1.0.0-beta.39
+
+### Patch Changes
+
+- [`6517f67`](https://github.com/outfitter-dev/trails/commit/6517f67b9dcc9d0ab64b1c7201b5d326905498e4): The OpenAPI projection now documents BlobRef routes as binary responses (`content: { '*/*': { schema: { type: 'string', format: 'binary' } } }`) instead of a JSON data envelope, matching the raw bytes the runtime serves with the blob's declared mimeType. Error responses keep the JSON error envelope. Both the fetch handler and the OpenAPI projection now share one BlobRef output recognition helper.
+- [`ab5c767`](https://github.com/outfitter-dev/trails/commit/ab5c7670446baa89cc10241686d51c16d0215e04): Serve `BlobRef` trail outputs as bytes on HTTP (TRL-1192). When a trail's output schema is `blobRefSchema`, the route handler streams the blob's data with `Content-Type` from its `mimeType` and a `Content-Length` from its `size` — for both `Uint8Array` and `ReadableStream` payloads — instead of wrapping the value in the JSON envelope. Error results keep the JSON error envelope, and non-blob trails are unchanged. Apps no longer need to hand-mount raw-byte routes beside the derived surface.
+- [`b9e82a3`](https://github.com/outfitter-dev/trails/commit/b9e82a33546356c93fbc302fb934a83f19f1c2c5): Webhook ingress v2 (TRL-1194, absorbing TRL-1174 and TRL-1175): store-verified, per-endpoint webhook ingress becomes framework-expressible. `webhook()` accepts dynamic path segments (`path: '/hooks/:endpoint'`) whose values are delivered as envelope fields, opt-in `rawBody: true` delivery (a non-JSON body is no longer a surface-level failure — the trail owns payload interpretation), an allowlisted `headers` list delivered lowercased, and `resources` that make `verify` resource-capable: the HTTP surface resolves the declared resources into a context for the verifier and releases them afterwards, so signature checks can reach stores holding per-endpoint secrets. Envelope-mode ingress responds 202 Accepted; classic static webhooks keep their exact-match, JSON-gated, 200 behavior. Core exports `parseWebhookPathParams`, `matchWebhookPath`, `webhookPathPatternsOverlap`, and `createResources`. The `webhook-route-collision` Warden rule now also flags dynamic patterns that overlap other webhook or derived routes, not just exact method/path duplicates.
+
+## 1.0.0-beta.38
+
+## 1.0.0-beta.37
+
+## 1.0.0-beta.36
+
+## 1.0.0-beta.35
+
+## 1.0.0-beta.34
+
+## 1.0.0-beta.33
+
 ## 1.0.0-beta.32
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/http",
-  "version": "1.0.0-beta.32",
+  "version": "1.0.0-beta.39",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",
@@ -25,7 +25,7 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.32"
+    "@ontrails/core": "^1.0.0-beta.39"
   },
   "peerDependencies": {
     "zod": "^4.3.5"

package/src/blob-output.ts

@@ -0,0 +1,31 @@
+/**
+ * Shared recognition for BlobRef trail output schemas.
+ *
+ * The runtime handler (`fetch.ts`) and the OpenAPI projection
+ * (`openapi.ts`) must agree on which routes serve raw bytes, so both
+ * read the same authored fact: the BlobRef marker meta on the trail's
+ * output schema.
+ */
+
+import { BLOB_REF_SCHEMA_META_KEY } from '@ontrails/core';
+
+/**
+ * True when a trail output schema carries the BlobRef marker meta — the
+ * authored fact that selects byte streaming over the JSON envelope on
+ * the HTTP surface and a binary response body in the OpenAPI projection.
+ */
+export const isBlobOutputSchema = (output: unknown): boolean => {
+  if (typeof output !== 'object' || output === null) {
+    return false;
+  }
+  const maybeMeta = (output as { meta?: () => unknown }).meta;
+  if (typeof maybeMeta !== 'function') {
+    return false;
+  }
+  const meta = maybeMeta.call(output);
+  return (
+    typeof meta === 'object' &&
+    meta !== null &&
+    (meta as Record<string, unknown>)[BLOB_REF_SCHEMA_META_KEY] === true
+  );
+};

package/src/build.ts

@@ -12,6 +12,8 @@ import {
   ValidationError,
   buildActivationProvenanceTraceAttrs,
   collectAttachedTypedLayers,
+  createResources,
+  createTrailContext,
   deriveSurfaceTrailVersionProjections,
   executeTrail,
   filterSurfaceTrails,
@@ -1038,6 +1040,44 @@ type MergeableWebhookRoute = HttpRouteDefinition & {
   readonly [WEBHOOK_INVALID_RECORDERS]?: readonly WebhookInvalidConsumerRecorder[];
 };
 
+/**
+ * Wrap a webhook source's `verify` for the route boundary.
+ *
+ * Sources that declare `resources` get a resource-capable context: the
+ * declared resources are resolved (honoring surface overrides and config
+ * values) for the duration of the verification and released afterwards,
+ * so signature checks can reach stores holding per-endpoint secrets.
+ */
+const createWebhookVerifier =
+  (
+    source: WebhookSource,
+    options: DeriveHttpRoutesOptions
+  ): ((request: WebhookVerifyRequest) => Promise<Result<void, Error>>) =>
+  async (request) => {
+    const declared = source.resources ?? [];
+    if (source.verify === undefined || declared.length === 0) {
+      return await verifyWebhookRequest(source, request);
+    }
+
+    const seed = options.createContext
+      ? await options.createContext()
+      : undefined;
+    const scope = await createResources(
+      { resources: declared },
+      createTrailContext(seed),
+      options.resources,
+      options.configValues
+    );
+    if (scope.isErr()) {
+      return scope;
+    }
+    try {
+      return await verifyWebhookRequest(source, request, scope.value.ctx);
+    } finally {
+      scope.value.release();
+    }
+  };
+
 const buildWebhookRoute = (
   graph: Topo,
   trail: Trail<unknown, unknown, unknown>,
@@ -1089,7 +1129,7 @@ const buildWebhookRoute = (
     ),
     trail,
     trailId: trail.id,
-    verifyWebhook: (request) => verifyWebhookRequest(source.value, request),
+    verifyWebhook: createWebhookVerifier(source.value, options),
     ...(versions === undefined ? {} : { versions }),
     webhookSource: source.value,
   };
@@ -1142,6 +1182,20 @@ const hasMatchingWebhookParse = (
   right: HttpRouteDefinition
 ): boolean => left.webhookSource?.parse === right.webhookSource?.parse;
 
+/**
+ * Envelope facts must agree before merging: the merged route delivers one
+ * envelope shape, so diverging `rawBody`/`headers` declarations would
+ * silently drop a consumer's declared fields.
+ */
+const hasMatchingWebhookEnvelope = (
+  left: HttpRouteDefinition,
+  right: HttpRouteDefinition
+): boolean =>
+  (left.webhookSource?.rawBody === true) ===
+    (right.webhookSource?.rawBody === true) &&
+  JSON.stringify(left.webhookSource?.headers ?? null) ===
+    JSON.stringify(right.webhookSource?.headers ?? null);
+
 const webhookConsumers = (
   route: MergeableWebhookRoute
 ): readonly WebhookConsumerExecute[] | undefined => route[WEBHOOK_CONSUMERS];
@@ -1180,6 +1234,14 @@ const mergeWebhookRoutes = (
       kind: 'parse-mismatch',
     };
   }
+  if (!hasMatchingWebhookEnvelope(existing, route)) {
+    return {
+      error: new ValidationError(
+        `HTTP route collision: trails "${existing.trailId}" and "${route.trailId}" share webhook source "${existing.webhookSource?.id}" on ${route.method} ${route.path} but declare mismatched rawBody/headers envelope facts. Reuse the same WebhookSource object so both consumers receive one envelope shape.`
+      ),
+      kind: 'parse-mismatch',
+    };
+  }
 
   const existingConsumers = webhookConsumers(existing as MergeableWebhookRoute);
   const incomingConsumers = webhookConsumers(route as MergeableWebhookRoute);

package/src/fetch.ts

@@ -1,13 +1,17 @@
 import {
   CancelledError,
+  isBlobRef,
   isTrailsError,
+  matchWebhookPath,
   NotFoundError,
+  parseWebhookPathParams,
   projectErrorDiagnostics,
   projectPublicSurfaceError,
   ValidationError,
 } from '@ontrails/core';
-import type { Topo } from '@ontrails/core';
+import type { BlobRef, Topo } from '@ontrails/core';
 
+import { isBlobOutputSchema } from './blob-output.js';
 import { deriveHttpRoutes } from './build.js';
 import type { DeriveHttpRoutesOptions, HttpRouteDefinition } from './build.js';
 
@@ -337,11 +341,41 @@ interface ResultLike {
   readonly value?: unknown;
 }
 
+/**
+ * True when the route's trail declares a BlobRef output schema — the
+ * authored fact that selects byte streaming over the JSON envelope.
+ */
+const rendersBlobOutput = (route: HttpRouteDefinition): boolean =>
+  isBlobOutputSchema(route.trail.output);
+
+/**
+ * Narrow blob bytes for `Response`. `BlobRef.data` is typed `Uint8Array`
+ * (ArrayBufferLike backing) while `BodyInit` wants a plain-ArrayBuffer
+ * view; blob producers construct views over plain buffers, so narrowing
+ * here avoids copying the bytes.
+ */
+const blobBody = (data: BlobRef['data']): BodyInit =>
+  data instanceof ReadableStream ? data : (data as Uint8Array<ArrayBuffer>);
+
+/** Stream a BlobRef's bytes with its declared content type and length. */
+const blobResponse = (blob: BlobRef): Response =>
+  new Response(blobBody(blob.data), {
+    headers: {
+      'Content-Length': String(blob.size),
+      'Content-Type': blob.mimeType,
+    },
+    status: 200,
+  });
+
 const mapResultToResponse = (
   result: ResultLike,
-  request: Request
+  request: Request,
+  options?: { readonly rendersBlob?: boolean }
 ): Response => {
   if (result.isOk()) {
+    if (options?.rendersBlob === true && isBlobRef(result.value)) {
+      return blobResponse(result.value);
+    }
     return json({ data: result.value }, 200);
   }
   const error = result.error ?? new Error('Unknown error');
@@ -429,11 +463,76 @@ const recordInvalidWebhook = async (
 const errorCategoryForWebhookFailure = (error: Error | undefined): string =>
   error !== undefined && isTrailsError(error) ? error.category : 'internal';
 
+/**
+ * True when the route's webhook source opts into ingress-envelope
+ * delivery: dynamic path segments, raw body, or allowlisted headers.
+ */
+const usesWebhookEnvelope = (route: HttpRouteDefinition): boolean => {
+  const source = route.webhookSource;
+  return (
+    source !== undefined &&
+    (source.rawBody === true ||
+      source.headers !== undefined ||
+      parseWebhookPathParams(source.path).length > 0)
+  );
+};
+
+const pickAllowlistedHeaders = (
+  headers: Headers,
+  allowlist: readonly string[]
+): Record<string, string> => {
+  const allowed = new Set(allowlist.map((name) => name.toLowerCase()));
+  const kept: Record<string, string> = {};
+  for (const [name, value] of headers) {
+    const normalized = name.toLowerCase();
+    if (allowed.has(normalized)) {
+      kept[normalized] = value;
+    }
+  }
+  return kept;
+};
+
+/**
+ * Assemble the delivered webhook value.
+ *
+ * Classic webhooks deliver the parsed JSON body directly. Envelope-mode
+ * webhooks deliver `{ ...pathParams, body?, headers?, rawBody? }` — the
+ * schema-declared boundary shape TRL-1194 lifts from the hand-mounted
+ * ingress routes.
+ */
+const buildWebhookDeliveredValue = (
+  route: HttpRouteDefinition,
+  request: Request,
+  rawBody: string,
+  jsonBody: unknown,
+  pathParams: Readonly<Record<string, string>> | undefined
+): unknown => {
+  const source = route.webhookSource;
+  if (source === undefined || !usesWebhookEnvelope(route)) {
+    return jsonBody;
+  }
+  return {
+    ...(jsonBody === undefined ? {} : { body: jsonBody }),
+    ...(source.headers === undefined
+      ? {}
+      : { headers: pickAllowlistedHeaders(request.headers, source.headers) }),
+    ...(source.rawBody === true ? { rawBody } : {}),
+    ...pathParams,
+  };
+};
+
 const handleWebhookRoute = async (
   route: HttpRouteDefinition,
   options: RuntimeOptions,
   request: Request
 ): Promise<Response> => {
+  const envelope = usesWebhookEnvelope(route);
+  // Self-derive dynamic segment values from the route's own pattern so
+  // every adapter (fetch dispatcher, Bun routes, Hono) gets pattern
+  // support without threading params through handler signatures.
+  const pathParams = envelope
+    ? matchWebhookPath(route.path, new URL(request.url).pathname)
+    : undefined;
   const rawBody = await readWebhookBodyText(request, options.maxJsonBodyBytes);
 
   if (rawBody === JSON_BODY_INVALID_CONTENT_LENGTH) {
@@ -458,12 +557,22 @@ const handleWebhookRoute = async (
   }
 
   const jsonBody = parseWebhookBodyText(request, rawBody);
-  if (jsonBody === JSON_PARSE_ERROR) {
+  // With rawBody delivery the trail owns payload interpretation, so a
+  // non-JSON body is not a surface-level failure.
+  if (jsonBody === JSON_PARSE_ERROR && route.webhookSource?.rawBody !== true) {
     await recordInvalidWebhook(route);
     return invalidJsonResponse();
   }
 
-  const parsed = route.parseWebhookInput?.(jsonBody);
+  const delivered = buildWebhookDeliveredValue(
+    route,
+    request,
+    rawBody,
+    jsonBody === JSON_PARSE_ERROR ? undefined : jsonBody,
+    pathParams
+  );
+
+  const parsed = route.parseWebhookInput?.(delivered);
   if (parsed === undefined) {
     await recordInvalidWebhook(route, 'internal');
     return mapResultToResponse(
@@ -483,6 +592,11 @@ const handleWebhookRoute = async (
   const result = await route.execute(parsed.value, requestId, request.signal, {
     headers: request.headers,
   });
+  // Envelope-mode ingress acknowledges accepted work with 202, matching
+  // the accepted-for-processing semantics of webhook receivers.
+  if (envelope && result.isOk()) {
+    return json({ data: result.value }, 202);
+  }
   return mapResultToResponse(result, request);
 };
 
@@ -511,6 +625,7 @@ export const createRouteHandler = (
   const runtimeOptions = {
     maxJsonBodyBytes: resolveMaxJsonBodyBytes(options.maxJsonBodyBytes),
   };
+  const rendersBlob = rendersBlobOutput(route);
 
   return async (request) => {
     try {
@@ -540,7 +655,7 @@ export const createRouteHandler = (
       const result = await route.execute(rawInput, requestId, request.signal, {
         headers: request.headers,
       });
-      return mapResultToResponse(result, request);
+      return mapResultToResponse(result, request, { rendersBlob });
     } catch (error: unknown) {
       return handleCaughtError(error, request);
     }
@@ -581,22 +696,45 @@ export const createFetchHandler = (
     throw routesResult.error;
   }
 
-  const routeHandlers = new Map<
-    string,
-    (request: Request) => Promise<Response>
-  >();
+  type BoundRouteHandler = (request: Request) => Promise<Response>;
+
+  const routeHandlers = new Map<string, BoundRouteHandler>();
+  const patternRoutes: {
+    readonly handler: BoundRouteHandler;
+    readonly method: string;
+    readonly pattern: string;
+  }[] = [];
   for (const route of routesResult.value) {
-    routeHandlers.set(
-      routeKey(route.method, route.path),
-      createRouteHandler(route, {
-        maxJsonBodyBytes: options.maxJsonBodyBytes,
-      })
-    );
+    const handler = createRouteHandler(route, {
+      maxJsonBodyBytes: options.maxJsonBodyBytes,
+    });
+    if (parseWebhookPathParams(route.path).length > 0) {
+      patternRoutes.push({
+        handler,
+        method: route.method.toUpperCase(),
+        pattern: route.path,
+      });
+      continue;
+    }
+    routeHandlers.set(routeKey(route.method, route.path), handler);
   }
 
   return async (request) => {
     const path = new URL(request.url).pathname;
     const handler = routeHandlers.get(routeKey(request.method, path));
-    return handler === undefined ? notFoundResponse(request) : handler(request);
+    if (handler !== undefined) {
+      return handler(request);
+    }
+    // Exact routes win; dynamic-segment routes match in registration order.
+    const method = request.method.toUpperCase();
+    for (const candidate of patternRoutes) {
+      if (candidate.method !== method) {
+        continue;
+      }
+      if (matchWebhookPath(candidate.pattern, path) !== undefined) {
+        return candidate.handler(request);
+      }
+    }
+    return notFoundResponse(request);
   };
 };

package/src/openapi.ts

@@ -19,6 +19,7 @@ import type {
   Trail,
 } from '@ontrails/core';
 
+import { isBlobOutputSchema } from './blob-output.js';
 import { deriveHttpOperationMethod } from './method.js';
 
 type JsonSchema = Readonly<Record<string, unknown>>;
@@ -214,6 +215,21 @@ const buildSuccessResponse = (
   if (!t.output) {
     return { '200': { description: 'Success' } };
   }
+  if (isBlobOutputSchema(t.output)) {
+    // BlobRef routes stream raw bytes at runtime (`fetch.ts` serves the
+    // blob's declared mimeType and Content-Length), so the spec documents
+    // a binary body instead of the JSON data envelope. The concrete
+    // Content-Type is per-blob runtime data, hence the `*/*` range.
+    return {
+      '200': {
+        content: {
+          '*/*': { schema: { format: 'binary', type: 'string' } },
+        },
+        description:
+          "Binary content: raw blob bytes served with the blob's declared mimeType",
+      },
+    };
+  }
   const outputSchema = toJsonSchema(t.output);
   return {
     '200': {