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

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # @ontrails/http
 
+## 1.0.0-beta.41
+
+## 1.0.0-beta.40
+
+### Minor Changes
+
+- [`5adb995`](https://github.com/outfitter-dev/trails/commit/5adb99551c2dda6190d46cce7f60bb08d63c99aa): Complete the v1 hard cutover from the authored `blaze` field to
+  `implementation` across trail contracts, surface projections, tests, examples,
+  and public source-analysis helpers. Existing applications must rename authored
+  trail behavior fields and direct trail-object access before upgrading.
+
+### Patch Changes
+
+- [`9bf592d`](https://github.com/outfitter-dev/trails/commit/9bf592ddba46aa12e3f4e6ffc0f772f7a41ed3df): Declare verified first-party adapter metadata for Drizzle, HTTP/Bun, and Store/Jsonfile so shared adapter checks can dogfood real owner targets.
+
+## 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/README.md

@@ -13,7 +13,7 @@ const greet = trail('greet', {
   input: z.object({ name: z.string().describe('Who to greet') }),
   output: z.object({ message: z.string() }),
   intent: 'read',
-  blaze: (input) => Result.ok({ message: `Hello, ${input.name}!` }),
+  implementation: (input) => Result.ok({ message: `Hello, ${input.name}!` }),
 });
 
 const graph = topo('myapp', { greet });
@@ -114,7 +114,7 @@ Trail IDs map to paths: `entity.show` becomes `/entity/show`. Dots become slashe
 
 ## Resource resolution
 
-Declared resources on each trail are resolved into the context before the blaze receives input.
+Declared resources on each trail are resolved into the context before the implementation receives input.
 
 ## Filtering
 
@@ -142,7 +142,7 @@ Each route definition produced by `deriveHttpRoutes` includes:
 | `trailId` | `string` | The trail ID this route was derived from |
 | `inputSource` | `'query' \| 'body'` | Where to read input |
 | `trail` | `Trail` | The original trail definition |
-| `execute` | `(input, requestId?, abortSignal?, context?) => Promise<Result>` | Validates, layers, resolves request auth when configured, and runs the blazed trail |
+| `execute` | `(input, requestId?, abortSignal?, context?) => Promise<Result>` | Validates, layers, resolves request auth when configured, and runs the trail |
 
 For GET routes on the Hono surface, repeated query keys are passed through as arrays (`?tag=one&tag=two` -> `{ tag: ['one', 'two'] }`) while a single occurrence stays a scalar string. The adapter does not coerce singleton query values into arrays.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ontrails/http",
-  "version": "1.0.0-beta.32",
+  "version": "1.0.0-beta.41",
   "files": [
     "src/**/*.ts",
     "!src/**/__tests__/**",
@@ -25,12 +25,17 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
-    "@ontrails/core": "^1.0.0-beta.32"
+    "@ontrails/core": "^1.0.0-beta.41"
   },
   "peerDependencies": {
     "zod": "^4.3.5"
   },
   "trails": {
+    "adapters": {
+      "./bun": {
+        "target": "http"
+      }
+    },
     "adapterTargets": {
       "http": {
         "conformance": {

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,
@@ -131,7 +133,7 @@ export interface HttpRouteDefinition {
     | undefined;
   readonly webhookSource?: WebhookSource | undefined;
   /**
-   * Validate input, compose layers, and run the blazed trail.
+   * Validate input, compose layers, and run the trail implementation.
    *
    * The caller is responsible for parsing raw input from the request and
    * mapping the Result to an HTTP response. This function is framework-agnostic.
@@ -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/bun.ts

@@ -109,7 +109,7 @@ const bodylessHeadResponse = (response: Response): Response =>
 const caughtErrors = new Map<string, Error>();
 const caughtErrorInput = z.object({ errorId: z.string() });
 const caughtErrorTrail = trail('__ontrails.http.bun.error', {
-  blaze: () =>
+  implementation: () =>
     Result.err(new InternalError('Bun error fallback executed directly')),
   input: caughtErrorInput,
   intent: 'read',

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': {

package/src/testing.ts

@@ -41,21 +41,21 @@ export interface HttpAdapterConformanceCase {
 }
 
 const echoTrail = trail('echo', {
-  blaze: (input) => Result.ok({ reply: input.message }),
+  implementation: (input) => Result.ok({ reply: input.message }),
   input: z.object({ message: z.string() }),
   intent: 'read',
   output: z.object({ reply: z.string() }),
 });
 
 const tagsTrail = trail('tags', {
-  blaze: (input) => Result.ok({ tags: input.tags }),
+  implementation: (input) => Result.ok({ tags: input.tags }),
   input: z.object({ tags: z.array(z.string()) }),
   intent: 'read',
   output: z.object({ tags: z.array(z.string()) }),
 });
 
 const echoBodyTrail = trail('echo.body', {
-  blaze: (input) => Result.ok({ length: input.message.length }),
+  implementation: (input) => Result.ok({ length: input.message.length }),
   input: z.object({ message: z.string() }),
   intent: 'write',
   output: z.object({ length: z.number() }),
@@ -65,14 +65,14 @@ const genericRedactionError = (): Error =>
   new Error('database password=secret');
 
 const genericErrorTrail = trail('generic.error', {
-  blaze: () => Result.err(genericRedactionError()),
+  implementation: () => Result.err(genericRedactionError()),
   input: z.object({}),
   intent: 'read',
   output: z.object({ ok: z.boolean() }),
 });
 
 const protectedTrail = trail('permit.scope', {
-  blaze: (_input, ctx) =>
+  implementation: (_input, ctx) =>
     Result.ok({
       permitId: ctx.permit?.id,
       requestId: ctx.requestId,
@@ -87,7 +87,8 @@ const protectedTrail = trail('permit.scope', {
 });
 
 const abortingTrail = trail('abort.check', {
-  blaze: (_input, ctx) => Result.ok({ aborted: ctx.abortSignal.aborted }),
+  implementation: (_input, ctx) =>
+    Result.ok({ aborted: ctx.abortSignal.aborted }),
   input: z.object({}),
   intent: 'read',
   output: z.object({ aborted: z.boolean() }),
@@ -104,7 +105,7 @@ const paymentWebhook = webhook('webhook.payment.received', {
 });
 
 const paymentWebhookTrail = trail('payment.receive', {
-  blaze: (input) => Result.ok({ paymentId: input.paymentId }),
+  implementation: (input) => Result.ok({ paymentId: input.paymentId }),
   input: z.object({ paymentId: z.string() }),
   on: [paymentWebhook],
   output: z.object({ paymentId: z.string() }),