unnbound-events 3.0.0-beta.0 → 3.0.0-beta.2

package/README.md

@@ -1,6 +1,6 @@
 # Unnbound Events SDK
 
-Unified HTTP and SQS queue routing with a single API. Register handlers once, handle requests from both transports. `c.request.body` is always an `ArrayBuffer` of the exact bytes received on the wire — the SDK never parses; decoding is an explicit workflow choice.
+Unified HTTP and SQS queue routing with a single API. Register handlers once, handle requests from both transports. `c.request.body` is always an `ArrayBuffer` of the exact request-content bytes after HTTP transport framing — the SDK never parses by content type or decompresses content encodings.
 
 ## Install
 
@@ -36,7 +36,7 @@ The server automatically:
 
 ## Handlers
 
-Routes receive a context object with request details. `c.request.body` is an `ArrayBuffer` containing the entity exactly as received on the wire, for **every** content type (zero-length when there is no body) — decode what you need inside the handler:
+Routes receive a context object with request details. `c.request.body` is an `ArrayBuffer` containing the exact request-content bytes after HTTP transport framing, for **every** content type (zero-length when there is no body) — decode what you need inside the handler:
 
 ```ts
 server.post('/users/:id', async (c) => {
@@ -72,6 +72,10 @@ server.post('/users/:id', async (c) => {
 });
 ```
 
+### Transport framing and content encoding
+
+`c.request.body` contains request content, not HTTP transport framing. Content encodings such as gzip are preserved, so decompress them explicitly when needed.
+
 **Response format:** `{ status?: number, body?: object | Uint8Array | ArrayBuffer, headers?: Record<string, string> }`
 
 Objects are JSON-serialized. `Uint8Array`/`ArrayBuffer` bodies are sent verbatim as binary (set `content-type` explicitly) — required for protocols like AS2 whose responses must not be JSON-mangled.
@@ -80,7 +84,9 @@ Return `undefined`, `null`, or omit properties to default to `204 No Content`.
 
 ## Upgrading from 2.0.x
 
-`c.request.body` used to vary by `content-type`. It is now always an `ArrayBuffer` of the exact bytes received.
+`c.request.body` used to vary by `content-type`. It is now always an `ArrayBuffer` of the exact request-content bytes after HTTP transport framing.
+
+Queued (SQS) messages replay through the same router, so the table below applies to queue handlers too — migrate them alongside your HTTP handlers. The bytes differ only for queued JSON, which is re-serialized through the queue envelope and so arrives as equivalent JSON rather than the publisher's original bytes; every other queued content type is byte-exact.
 
 | `content-type` | 2.0.x | Current version |
 | --- | --- | --- |
@@ -92,9 +98,10 @@ Return `undefined`, `null`, or omit properties to default to `204 No Content`.
 
 Handlers for the first four must decode explicitly — see [Handlers](#handlers) for the per-type recipes. Handlers that already received bytes (XML, EDI, CSV, binary) are unaffected.
 
-Two things to check when upgrading an existing workflow:
+Three things to check when upgrading an existing workflow:
 
 - A malformed JSON body used to arrive as `undefined`. It now arrives as raw bytes and `JSON.parse` throws — handle it where you decode.
+- A missing body used to arrive as `undefined`, so `if (!c.request.body)` guards fired. Over HTTP it is now a zero-length `ArrayBuffer`, which is truthy, and those guards silently stop firing. Check `c.request.body.byteLength` instead. Queued delivery is the exception: a bodyless async request replays as the four bytes `null`, because the queue envelope stores `null` and it is re-serialized on the way in.
 - `tsc` catches direct property access on the body, but not a body passed straight to a logger or serializer. Those compile clean and emit `{}` at runtime. Audit every `server.post` / `server.put` handler before deploying.
 
 ## Middleware

package/dist/lib/adapters/extended-sqs-client.d.ts

@@ -7,12 +7,7 @@ export interface S3Pointer {
 }
 export type S3PointerMessage = ['software.amazon.payloadoffloading.PayloadS3Pointer', S3Pointer];
 type SQSClientConfig = ConstructorParameters<typeof SQSClient>[0];
-/**
- * Internal SQS envelope before it re-enters the HTTP router. Inline bodies
- * remain decoded JSON values until QueueAdapter serializes them into request
- * bytes, so this must not claim the public IncomingRequest body contract.
- * This distinction changes only the type, not SQS delivery behavior.
- */
+/** Queue envelopes hold decoded values until replay, so body is not yet an ArrayBuffer. */
 interface SqsEnvelopeRequest extends Omit<IncomingRequest, 'body'> {
     body: unknown;
 }

package/dist/lib/event.d.ts

@@ -6,7 +6,7 @@ export interface IncomingRequest {
     path: string;
     headers: Record<string, string>;
     query: Record<string, any>;
-    /** Exact request bytes; empty for bodyless requests. */
+    /** Exact request-content bytes after HTTP transport framing; empty for bodyless requests. */
     body: ArrayBuffer;
 }
 export interface MatchedIncomingRequest extends IncomingRequest {

package/dist/lib/routing/endpoint.d.ts

@@ -1,5 +1,5 @@
 import type { Context } from 'hono';
-import type { EventHandlerResult, StrictEventHandlerResult } from '../event';
+import type { EventHandlerResult } from '../event';
 import { type MiddlewareHandler } from './middleware';
 import type { EventEnvironment, EventVariables, MaybePromise } from './types';
 export type Handler<I, R = EventHandlerResult> = (input: I) => MaybePromise<R>;
@@ -8,12 +8,10 @@ export interface Endpoint<I> {
     (path: string, middleware: MiddlewareHandler<I>, handler: Handler<I>): MaybePromise<void>;
 }
 export type EndpointArgs<I> = [path: string, handler: Handler<I>] | [path: string, middleware: MiddlewareHandler<I>, handler: Handler<I>];
-export declare const buildEndpointArguments: (...args: EndpointArgs<EventVariables<{}>>) => (string | Handler<Context<EventEnvironment<{}>, any, {}>, Response> | MiddlewareHandler<Context<EventEnvironment<{}>, any, {}>>)[];
+export declare const buildEndpointArguments: (...args: EndpointArgs<EventVariables<{}>>) => (string | Handler<Context<EventEnvironment<{}>, any, {}>, Response> | import("hono").MiddlewareHandler<EventEnvironment<{}>>)[];
 export declare const parseEndpointArguments: (...args: EndpointArgs<EventVariables<{}>>) => {
     path: string;
     middlewares: MiddlewareHandler<EventVariables<{}>>[];
     handler: Handler<EventVariables<{}>, EventHandlerResult>;
 };
 export declare const patchEndpoint: <V extends object>(handler: Handler<EventVariables<V>>) => Handler<Context<EventEnvironment<V>>, Response>;
-export declare const respondWith: (context: Context, result: StrictEventHandlerResult) => (Response & import("hono").TypedResponse<never, -1 | 100 | 102 | 103 | 200 | 201 | 202 | 203 | 206 | 207 | 208 | 226 | 300 | 301 | 302 | 303 | 305 | 306 | 307 | 308 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511, "json">) | (Response & import("hono").TypedResponse<null, -1 | 100 | 101 | 102 | 103 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 226 | 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511, "body">) | (Response & import("hono").TypedResponse<ArrayBuffer, -1 | 100 | 102 | 103 | 200 | 201 | 202 | 203 | 206 | 207 | 208 | 226 | 300 | 301 | 302 | 303 | 305 | 306 | 307 | 308 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511, "body">);
-export declare const attachTraceHeaders: (headers?: Record<string, string>) => Record<string, string> | undefined;

package/dist/lib/routing/endpoint.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.attachTraceHeaders = exports.respondWith = exports.patchEndpoint = exports.parseEndpointArguments = exports.buildEndpointArguments = void 0;
+exports.patchEndpoint = exports.parseEndpointArguments = exports.buildEndpointArguments = void 0;
 const unnbound_logger_sdk_1 = require("unnbound-logger-sdk");
 const utils_1 = require("../utils");
 const middleware_1 = require("./middleware");
+const response_1 = require("./response");
 const buildEndpointArguments = (...args) => {
     const { path, middlewares, handler } = (0, exports.parseEndpointArguments)(...args);
     const patchedHandler = (0, exports.patchEndpoint)(handler);
@@ -23,33 +24,9 @@ const patchEndpoint = (handler) => {
         state.request.params = { ...state.request.params, ...context.req.param() };
         const result = await (0, unnbound_logger_sdk_1.startSpan)('Event request', async () => {
             const result = await handler(state);
-            return { status: result?.status ?? 204, headers: result?.headers, body: result?.body };
+            return { status: (0, response_1.resolveStatus)(result), headers: result?.headers, body: result?.body };
         }, (o) => (0, utils_1.buildIncomingPayload)(state, o));
-        return (0, exports.respondWith)(context, result);
+        return (0, response_1.respondWith)(context, result);
     };
 };
 exports.patchEndpoint = patchEndpoint;
-const respondWith = (context, result) => {
-    const headers = (0, exports.attachTraceHeaders)(result.headers);
-    if (!result.body)
-        return context.body(null, result.status, headers);
-    // Signed protocol responses such as AS2 MDNs must remain byte-exact.
-    if (result.body instanceof Uint8Array || result.body instanceof ArrayBuffer) {
-        const bytes = result.body instanceof ArrayBuffer ? result.body : Uint8Array.from(result.body).buffer;
-        return context.body(bytes, result.status, headers);
-    }
-    return context.json(result.body, result.status, headers);
-};
-exports.respondWith = respondWith;
-const attachTraceHeaders = (headers) => {
-    // storage can be undefined when CJS/ESM interop breaks re-exports (e.g. tsx in dev mode)
-    const { traceId, messageId } = unnbound_logger_sdk_1.storage?.getStore() ?? {};
-    if (!traceId || !messageId)
-        return headers;
-    return {
-        ...headers,
-        [unnbound_logger_sdk_1.defaultTraceHeaderKey]: headers?.[unnbound_logger_sdk_1.defaultTraceHeaderKey] ?? traceId,
-        [unnbound_logger_sdk_1.defaultMessageHeaderKey]: headers?.[unnbound_logger_sdk_1.defaultMessageHeaderKey] ?? messageId,
-    };
-};
-exports.attachTraceHeaders = attachTraceHeaders;

package/dist/lib/routing/middleware.d.ts

@@ -1,12 +1,13 @@
-import type { Context, Next } from 'hono';
+import type { MiddlewareHandler as HonoMiddlewareHandler, Next } from 'hono';
+import type { EventHandlerResult } from '../event';
 import type { EventEnvironment, EventVariables, MaybePromise } from './types';
-export type MiddlewareHandler<I> = (input: I, next: Next) => MaybePromise<void>;
+export type MiddlewareHandler<I> = (input: I, next: Next) => MaybePromise<EventHandlerResult | void>;
 export interface Middleware<I> {
     (...middlewares: MiddlewareHandler<I>[]): MaybePromise<void>;
     (path: string, ...middlewares: MiddlewareHandler<I>[]): MaybePromise<void>;
 }
 export type MiddlewareArgs<I> = [...middlewares: MiddlewareHandler<I>[]] | [path: string, ...middlewares: MiddlewareHandler<I>[]];
-export declare const patchMiddleware: (handler: MiddlewareHandler<EventVariables<{}>>) => MiddlewareHandler<Context<EventEnvironment<{}>>>;
+export declare const patchMiddleware: (handler: MiddlewareHandler<EventVariables<{}>>) => HonoMiddlewareHandler<EventEnvironment<{}>>;
 export declare const parseMiddlewareArguments: (...args: MiddlewareArgs<EventVariables<{}>>) => {
     path: string;
     middlewares: MiddlewareHandler<EventVariables<{}>>[];
@@ -14,4 +15,4 @@ export declare const parseMiddlewareArguments: (...args: MiddlewareArgs<EventVar
     path: undefined;
     middlewares: MiddlewareHandler<EventVariables<{}>>[];
 };
-export declare const buildMiddlewareArguments: (...args: MiddlewareArgs<EventVariables<{}>>) => MiddlewareHandler<Context<EventEnvironment<{}>, any, {}>>[] | readonly [string, ...MiddlewareHandler<Context<EventEnvironment<{}>, any, {}>>[]];
+export declare const buildMiddlewareArguments: (...args: MiddlewareArgs<EventVariables<{}>>) => HonoMiddlewareHandler<EventEnvironment<{}>>[] | readonly [string, ...HonoMiddlewareHandler<EventEnvironment<{}>>[]];

package/dist/lib/routing/middleware.js

@@ -1,12 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildMiddlewareArguments = exports.parseMiddlewareArguments = exports.patchMiddleware = void 0;
+const unnbound_logger_sdk_1 = require("unnbound-logger-sdk");
+const utils_1 = require("../utils");
+const response_1 = require("./response");
 const patchMiddleware = (handler) => {
-    return (context, next) => {
+    return async (context, next) => {
         const state = context.get('state');
         // We have to recalculate the params because middleware path might contain url params
         state.request.params = { ...state.request.params, ...context.req.param() };
-        return handler(state, next);
+        const result = await handler(state, next);
+        // Auth and validation middleware must be able to fail closed with the same
+        // response contract as endpoint handlers.
+        if (result == null)
+            return;
+        // Short-circuiting skips patchEndpoint, so nothing else emits the request
+        // span. Without this, denied requests are absent from workflow traces.
+        const traced = await (0, unnbound_logger_sdk_1.startSpan)('Event request', async () => ({ status: (0, response_1.resolveStatus)(result), headers: result.headers, body: result.body }), (o) => (0, utils_1.buildIncomingPayload)(state, o));
+        return (0, response_1.respondWith)(context, traced);
     };
 };
 exports.patchMiddleware = patchMiddleware;

package/dist/lib/routing/response.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from 'hono';
+import type { EventHandlerResult, StrictEventHandlerResult } from '../event';
+export declare const isContentlessStatus: (status: number) => boolean;
+export declare const resolveStatus: (result?: EventHandlerResult) => import("hono/utils/http-status").StatusCode;
+export declare const respondWith: (context: Context, result: StrictEventHandlerResult) => (Response & import("hono").TypedResponse<never, -1 | 100 | 102 | 103 | 200 | 201 | 202 | 203 | 206 | 207 | 208 | 226 | 300 | 301 | 302 | 303 | 305 | 306 | 307 | 308 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511, "json">) | (Response & import("hono").TypedResponse<null, -1 | 100 | 101 | 102 | 103 | 200 | 201 | 202 | 203 | 204 | 205 | 206 | 207 | 208 | 226 | 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511, "body">) | (Response & import("hono").TypedResponse<ArrayBuffer, -1 | 100 | 102 | 103 | 200 | 201 | 202 | 203 | 206 | 207 | 208 | 226 | 300 | 301 | 302 | 303 | 305 | 306 | 307 | 308 | 400 | 401 | 402 | 403 | 404 | 405 | 406 | 407 | 408 | 409 | 410 | 411 | 412 | 413 | 414 | 415 | 416 | 417 | 418 | 421 | 422 | 423 | 424 | 425 | 426 | 428 | 429 | 431 | 451 | 500 | 501 | 502 | 503 | 504 | 505 | 506 | 507 | 508 | 510 | 511, "body">);
+export declare const attachTraceHeaders: (headers?: Record<string, string>) => Record<string, string> | undefined;

package/dist/lib/routing/response.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachTraceHeaders = exports.respondWith = exports.resolveStatus = exports.isContentlessStatus = void 0;
+const unnbound_logger_sdk_1 = require("unnbound-logger-sdk");
+// Response rejects bodies on these statuses; dropping one prevents a 500.
+const CONTENTLESS_STATUSES = new Set([204, 205, 304]);
+const isContentlessStatus = (status) => CONTENTLESS_STATUSES.has(status);
+exports.isContentlessStatus = isContentlessStatus;
+const resolveStatus = (result) => result?.status ?? (result?.body ? 200 : 204);
+exports.resolveStatus = resolveStatus;
+const respondWith = (context, result) => {
+    const headers = (0, exports.attachTraceHeaders)(result.headers);
+    if (!result.body || CONTENTLESS_STATUSES.has(result.status)) {
+        return context.body(null, result.status, headers);
+    }
+    // Signed protocol responses such as AS2 MDNs must remain byte-exact.
+    if (result.body instanceof Uint8Array || result.body instanceof ArrayBuffer) {
+        const bytes = result.body instanceof ArrayBuffer ? result.body : Uint8Array.from(result.body).buffer;
+        return context.body(bytes, result.status, headers);
+    }
+    return context.json(result.body, result.status, headers);
+};
+exports.respondWith = respondWith;
+const attachTraceHeaders = (headers) => {
+    // storage can be undefined when CJS/ESM interop breaks re-exports (e.g. tsx in dev mode)
+    const { traceId, messageId } = unnbound_logger_sdk_1.storage?.getStore() ?? {};
+    if (!traceId || !messageId)
+        return headers;
+    return {
+        ...headers,
+        [unnbound_logger_sdk_1.defaultTraceHeaderKey]: headers?.[unnbound_logger_sdk_1.defaultTraceHeaderKey] ?? traceId,
+        [unnbound_logger_sdk_1.defaultMessageHeaderKey]: headers?.[unnbound_logger_sdk_1.defaultMessageHeaderKey] ?? messageId,
+    };
+};
+exports.attachTraceHeaders = attachTraceHeaders;

package/dist/lib/server.js

@@ -8,6 +8,7 @@ const queue_adapter_1 = require("./adapters/queue-adapter");
 const error_1 = require("./error");
 const endpoint_1 = require("./routing/endpoint");
 const middleware_1 = require("./routing/middleware");
+const response_1 = require("./routing/response");
 const utils_1 = require("./utils");
 class HttpQueueServer {
     logger;
@@ -31,7 +32,7 @@ class HttpQueueServer {
         this.app.onError((err, c) => {
             const error = error_1.ServerError.fromError(err);
             this.logger.error({ err: error.toError() }, error.message);
-            return (0, endpoint_1.respondWith)(c, error.toJson());
+            return (0, response_1.respondWith)(c, error.toJson());
         });
         this.http = new http_adapter_1.HttpAdapter({ app: this.app, logger: this.logger, ...options.http });
         this.queueEnabled = shouldEnableQueue(options.queue);

package/dist/lib/utils.js

@@ -6,6 +6,7 @@ const trace_1 = require("unnbound-logger-sdk/dist/trace");
 const types_1 = require("unnbound-logger-sdk/dist/types");
 const utils_1 = require("unnbound-logger-sdk/dist/utils");
 const error_1 = require("./error");
+const response_1 = require("./routing/response");
 const normalizeHeaders = (headers) => {
     return Object.fromEntries(Object.entries(headers).map(([key, value]) => [
         key,
@@ -115,16 +116,18 @@ const buildResponsePayload = (result) => {
     const declaredHeaders = result?.headers
         ? Object.fromEntries(Object.entries((0, exports.normalizeHeaders)(result.headers)).map(([name, value]) => [name.toLowerCase(), value]))
         : undefined;
-    // Byte responses go out with exactly the declared headers (no content-type
-    // unless the handler set one); everything else is JSON-serialized on the
-    // wire. The trace mirrors that, and the declared content-type drives the
-    // display decode so byte responses labeled JSON/XML/text trace readably.
-    const isByteBody = result?.body instanceof Uint8Array || result?.body instanceof ArrayBuffer;
+    // Binary responses keep declared headers; JSON gets the SDK default.
+    // The declared content type also controls trace decoding.
     const traceHeaders = headersForTrace(declaredHeaders ?? {});
+    const status = (0, response_1.resolveStatus)(result);
+    // Mirror the wire: respondWith drops the body on contentless statuses, so the
+    // trace must not claim one — nor a content type for a body never sent.
+    const body = (0, response_1.isContentlessStatus)(status) ? undefined : result?.body;
+    const isByteBody = body instanceof Uint8Array || body instanceof ArrayBuffer;
     return {
-        status: result?.status ?? 204,
-        headers: isByteBody ? traceHeaders : { 'content-type': 'application/json; charset=utf-8', ...traceHeaders },
-        body: result?.body ? describeBody(result.body, declaredHeaders?.['content-type']) : undefined,
+        status,
+        headers: body && !isByteBody ? { 'content-type': 'application/json; charset=utf-8', ...traceHeaders } : traceHeaders,
+        body: body ? describeBody(body, declaredHeaders?.['content-type']) : undefined,
     };
 };
 const buildIncomingPayload = (event, result) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "unnbound-events",
   "description": "Unified events SDK to handle HTTP routes and queued messages with a single routing API.",
-  "version": "3.0.0-beta.0",
+  "version": "3.0.0-beta.2",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {