@hebo-ai/gateway 0.9.2 → 0.9.3

package/dist/telemetry/gen-ai.js

@@ -0,0 +1,108 @@
+import { metrics } from "@opentelemetry/api";
+import { STATUS_CODE } from "../errors/utils";
+const getMeter = () => metrics.getMeter("@hebo/gateway");
+let requestDurationHistogram;
+let timePerOutputTokenHistogram;
+let timeToFirstTokenHistogram;
+let tokenUsageHistogram;
+const getRequestDurationHistogram = () => (requestDurationHistogram ??= getMeter().createHistogram("gen_ai.server.request.duration", {
+    description: "End-to-end gateway request duration",
+    unit: "s",
+    advice: {
+        // Upstream OTel for http.server.request.duration.
+        // We preserve that sequence and extend the tail for slow service tiers up to 30min.
+        explicitBucketBoundaries: [
+            0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60, 120, 300, 600, 900, 1800,
+        ],
+    },
+}));
+const getTimeToFirstTokenHistogram = () => (timeToFirstTokenHistogram ??= getMeter().createHistogram("gen_ai.server.time_to_first_token", {
+    description: "Time from request start until the first token is generated",
+    unit: "s",
+    advice: {
+        // Upstream OTel uses the same dense sub-second sequence through 10s.
+        // We preserve that sequence and extend the tail slow service tiers up to 30 min.
+        explicitBucketBoundaries: [
+            0.001, 0.005, 0.01, 0.02, 0.04, 0.06, 0.08, 0.1, 0.25, 0.5, 0.75, 1.0, 2.5, 5, 7.5, 10, 30,
+            60, 120, 300, 600, 900, 1800,
+        ],
+    },
+}));
+const getTimePerOutputTokenHistogram = () => (timePerOutputTokenHistogram ??= getMeter().createHistogram("gen_ai.server.time_per_output_token", {
+    description: "Time per output token generated after the first token",
+    unit: "s",
+    advice: {
+        // Upstream OTel uses the same low-latency shape
+        explicitBucketBoundaries: [
+            0.001, 0.005, 0.01, 0.02, 0.04, 0.06, 0.08, 0.1, 0.25, 0.5, 0.75, 1.0, 2.5,
+        ],
+    },
+}));
+const getTokenUsageHistogram = () => (tokenUsageHistogram ??= getMeter().createHistogram("gen_ai.client.token.usage", {
+    description: "Number of tokens used in the operation, by token type",
+    unit: "{token}",
+    advice: {
+        // Upstream OTel uses powers of 4 up to 67,108,864 tokens.
+        // We keep the low-end anchors, add denser mid/high-range buckets
+        explicitBucketBoundaries: [
+            1, 4, 16, 64, 256, 1024, 2048, 4096, 8192, 16384, 32768, 65536, 131072, 262144, 524288,
+            1048576, 4194304, 16777216, 67108864,
+        ],
+    },
+}));
+export const getGenAiGeneralAttributes = (ctx, signalLevel) => {
+    if (!signalLevel || signalLevel === "off")
+        return {};
+    const requestModel = typeof ctx.body?.model === "string" ? ctx.body.model : ctx.modelId;
+    const attrs = {
+        "gen_ai.operation.name": ctx.operation,
+        "gen_ai.request.model": requestModel,
+        "gen_ai.response.model": ctx.resolvedModelId,
+        "gen_ai.provider.name": ctx.resolvedProviderId,
+    };
+    for (const [key, value] of Object.entries(ctx.otel)) {
+        if (value !== undefined)
+            attrs[key] = value;
+    }
+    return attrs;
+};
+export const recordRequestDuration = (duration, status, ctx, signalLevel) => {
+    if (!signalLevel || signalLevel === "off")
+        return;
+    const attrs = getGenAiGeneralAttributes(ctx, signalLevel);
+    if (status !== 200) {
+        attrs["error.type"] = `${status} ${STATUS_CODE(status).toLowerCase()}`;
+    }
+    getRequestDurationHistogram().record(duration / 1000, attrs);
+};
+export const recordTimeToFirstToken = (duration, metricAttrs, signalLevel) => {
+    if (!signalLevel || (signalLevel !== "recommended" && signalLevel !== "full"))
+        return;
+    getTimeToFirstTokenHistogram().record(duration / 1000, metricAttrs);
+};
+// FUTURE: record unsuccessful calls
+export const recordTimePerOutputToken = (start, ttft, tokenAttrs, metricAttrs, signalLevel) => {
+    if (!signalLevel || (signalLevel !== "recommended" && signalLevel !== "full"))
+        return;
+    const outputTokens = tokenAttrs["gen_ai.usage.output_tokens"];
+    if (typeof outputTokens !== "number" || outputTokens <= 1)
+        return;
+    getTimePerOutputTokenHistogram().record((performance.now() - start - ttft) / 1000 / (outputTokens - 1), metricAttrs);
+};
+// FUTURE: record unsuccessful calls
+export const recordTokenUsage = (tokenAttrs, metricAttrs, signalLevel) => {
+    if (!signalLevel || (signalLevel !== "recommended" && signalLevel !== "full"))
+        return;
+    const record = (value, tokenType) => {
+        if (typeof value !== "number")
+            return;
+        getTokenUsageHistogram().record(value, Object.assign({}, metricAttrs, { "gen_ai.token.type": tokenType }));
+    };
+    record(tokenAttrs["gen_ai.usage.input_tokens"], "input");
+    record(tokenAttrs["gen_ai.usage.output_tokens"], "output");
+    // FUTURE: "cached" and "reasoning" token types are not yet in the OTel standard — monitor:
+    // https://github.com/open-telemetry/semantic-conventions/issues/1959
+    // https://github.com/open-telemetry/semantic-conventions/issues/3341
+    record(tokenAttrs["gen_ai.usage.cache_read.input_tokens"], "cached");
+    record(tokenAttrs["gen_ai.usage.reasoning.output_tokens"], "reasoning");
+};

package/dist/telemetry/http.d.ts

@@ -0,0 +1,3 @@
+import { type TelemetrySignalLevel } from "../types";
+export declare const getRequestAttributes: (request: Request, signalLevel?: TelemetrySignalLevel) => {};
+export declare const getResponseAttributes: (response: Response, signalLevel?: TelemetrySignalLevel) => {};

package/dist/telemetry/http.js

@@ -0,0 +1,54 @@
+import {} from "../types";
+const headerArr = (h, k) => (h.has(k) ? [h.get(k)] : undefined);
+export const getRequestAttributes = (request, signalLevel) => {
+    if (!signalLevel || signalLevel === "off")
+        return {};
+    let url;
+    try {
+        // FUTURE: reuse URL from lifecycle
+        url = new URL(request.url);
+    }
+    catch { }
+    const attrs = {
+        "http.request.method": request.method,
+        "url.full": request.url,
+        "url.path": url?.pathname,
+        "url.scheme": url?.protocol.replace(":", ""),
+        "server.address": url?.hostname,
+        "server.port": url
+            ? url.port
+                ? Number(url.port)
+                : url.protocol === "https:"
+                    ? 443
+                    : 80
+            : undefined,
+    };
+    if (signalLevel !== "required") {
+        Object.assign(attrs, {
+            "user_agent.original": request.headers.get("user-agent") ?? undefined,
+        });
+    }
+    if (signalLevel === "full") {
+        Object.assign(attrs, {
+            // FUTURE: "url.query"
+            "http.request.header.content-type": headerArr(request.headers, "content-type"),
+            "http.request.header.content-length": headerArr(request.headers, "content-length"),
+            // FUTURE: "client.address"
+        });
+    }
+    return attrs;
+};
+export const getResponseAttributes = (response, signalLevel) => {
+    if (!signalLevel || signalLevel === "off")
+        return {};
+    const attrs = {
+        "http.response.status_code": response.status,
+    };
+    if (signalLevel === "full") {
+        Object.assign(attrs, {
+            "http.response.header.content-type": [headerArr(response.headers, "content-type")],
+            "http.response.header.content-length": [headerArr(response.headers, "content-length")],
+        });
+    }
+    return attrs;
+};

package/dist/telemetry/index.d.ts

@@ -0,0 +1 @@
+export * from "./fetch";

package/dist/telemetry/index.js

@@ -0,0 +1 @@
+export * from "./fetch";

package/dist/telemetry/memory.d.ts

@@ -0,0 +1,2 @@
+import type { TelemetrySignalLevel } from "../types";
+export declare const observeV8jsMemoryMetrics: (level?: TelemetrySignalLevel) => void;

package/dist/telemetry/memory.js

@@ -0,0 +1,43 @@
+import { metrics } from "@opentelemetry/api";
+const getMeter = () => metrics.getMeter("@hebo/gateway");
+const defaultHeapSpaceAttrs = { "v8js.heap.space.name": "total" };
+let registered = false;
+const isEnabled = (level) => level === "recommended" || level === "full";
+const observeMemory = (observe) => {
+    let usage;
+    try {
+        usage = globalThis.process?.memoryUsage?.();
+    }
+    catch {
+        return;
+    }
+    if (!usage)
+        return;
+    observe(usage.heapUsed, usage.rss);
+};
+export const observeV8jsMemoryMetrics = (level) => {
+    if (!isEnabled(level) || registered)
+        return;
+    registered = true;
+    const meter = getMeter();
+    meter
+        .createObservableGauge("v8js.memory.heap.used", {
+        description: "Used bytes in the V8 heap",
+        unit: "By",
+    })
+        .addCallback((result) => {
+        observeMemory((heapUsed) => {
+            result.observe(heapUsed, defaultHeapSpaceAttrs);
+        });
+    });
+    meter
+        .createObservableGauge("v8js.memory.heap.space.physical_size", {
+        description: "Physical bytes allocated for the V8 heap space",
+        unit: "By",
+    })
+        .addCallback((result) => {
+        observeMemory((_, rss) => {
+            result.observe(rss, defaultHeapSpaceAttrs);
+        });
+    });
+};

package/dist/telemetry/span.d.ts

@@ -0,0 +1,13 @@
+import type { Attributes, SpanOptions, Tracer } from "@opentelemetry/api";
+import type { TelemetrySignalLevel } from "../types";
+export declare const setSpanTracer: (tracer?: Tracer) => void;
+export declare const setSpanEventsEnabled: (level?: TelemetrySignalLevel) => void;
+export declare const startSpan: (name: string, options?: SpanOptions) => import("@opentelemetry/api").Span & {
+    runWithContext: <T>(fn: () => Promise<T> | T) => T | Promise<T>;
+    recordError: (_error: unknown) => void;
+    finish: () => void;
+    isExisting: boolean;
+};
+export declare const withSpan: <T>(name: string, run: () => Promise<T> | T, options?: SpanOptions) => Promise<T>;
+export declare const addSpanEvent: (name: string, attributes?: Attributes) => void;
+export declare const setSpanAttributes: (attributes?: Attributes) => void;

package/dist/telemetry/span.js

@@ -0,0 +1,60 @@
+import { INVALID_SPAN_CONTEXT, SpanKind, SpanStatusCode, context, trace } from "@opentelemetry/api";
+const DEFAULT_TRACER_NAME = "@hebo/gateway";
+let spanTracer;
+let spanEventsEnabled = false;
+const NOOP_SPAN = {
+    runWithContext: (fn) => fn(),
+    recordError: (_error) => { },
+    finish: () => { },
+    isExisting: true,
+};
+export const setSpanTracer = (tracer) => {
+    spanTracer = tracer ?? trace.getTracer(DEFAULT_TRACER_NAME);
+};
+export const setSpanEventsEnabled = (level) => {
+    spanEventsEnabled = level === "recommended" || level === "full";
+};
+export const startSpan = (name, options) => {
+    if (!spanTracer) {
+        return Object.assign(trace.wrapSpanContext(INVALID_SPAN_CONTEXT), NOOP_SPAN);
+    }
+    const parentContext = context.active();
+    const activeSpan = trace.getActiveSpan();
+    const span = spanTracer.startSpan(name, { kind: activeSpan ? SpanKind.INTERNAL : SpanKind.SERVER, ...options }, parentContext);
+    const runWithContext = (fn) => context.with(trace.setSpan(parentContext, span), fn);
+    const recordError = (error) => {
+        const err = error instanceof Error ? error : new Error(String(error));
+        span.recordException(err);
+        span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+    };
+    const finish = () => {
+        span.end();
+    };
+    return Object.assign(span, { runWithContext, recordError, finish, isExisting: !!activeSpan });
+};
+export const withSpan = async (name, run, options) => {
+    if (!spanTracer) {
+        return run();
+    }
+    const started = startSpan(name, options);
+    try {
+        return await started.runWithContext(run);
+    }
+    catch (error) {
+        started.recordError(error);
+        throw error;
+    }
+    finally {
+        started.finish();
+    }
+};
+export const addSpanEvent = (name, attributes) => {
+    if (!spanEventsEnabled)
+        return;
+    trace.getActiveSpan()?.addEvent(name, attributes);
+};
+export const setSpanAttributes = (attributes) => {
+    if (!attributes)
+        return;
+    trace.getActiveSpan()?.setAttributes(attributes);
+};

package/dist/types.d.ts

@@ -0,0 +1,231 @@
+import type { ProviderV3 } from "@ai-sdk/provider";
+import type { Attributes, Tracer } from "@opentelemetry/api";
+import type { ChatCompletions, ChatCompletionsBody, ChatCompletionsStream } from "./endpoints/chat-completions/schema";
+import type { ConversationStorage } from "./endpoints/conversations/storage/types";
+import type { Embeddings, EmbeddingsBody } from "./endpoints/embeddings/schema";
+import type { Model, ModelList } from "./endpoints/models";
+import type { Responses, ResponsesBody, ResponsesStream } from "./endpoints/responses/schema";
+import type { Logger, LoggerConfig } from "./logger";
+import type { ModelCatalog, ModelId } from "./models/types";
+import type { ProviderId, ProviderRegistry } from "./providers/types";
+export type GatewayOperation = "chat" | "embeddings" | "responses" | "models" | "conversations";
+/**
+ * Per-request context shared across handlers and hooks.
+ */
+export type GatewayContext = {
+    /**
+     * Mutable bag for passing data between hooks.
+     */
+    state: Record<string, unknown>;
+    /**
+     * OpenTelemetry attribute bag populated by hooks.
+     * Attributes set here are applied to both spans and all metric instruments.
+     */
+    otel: Attributes;
+    /**
+     * Provider registry from config.
+     */
+    providers: ProviderRegistry;
+    /**
+     * Model catalog from config.
+     */
+    models: ModelCatalog;
+    /**
+     * Incoming request for the handler.
+     */
+    request: Request;
+    /**
+     * Resolved request ID for logging and telemetry.
+     */
+    requestId: string;
+    /**
+     * Parsed body from the request.
+     */
+    body?: ChatCompletionsBody | EmbeddingsBody | ResponsesBody;
+    /**
+     * Incoming model ID.
+     */
+    modelId?: ModelId;
+    /**
+     * Resolved model ID.
+     */
+    resolvedModelId?: ModelId;
+    /**
+     * Operation type.
+     */
+    operation?: GatewayOperation;
+    /**
+     * Resolved provider instance.
+     */
+    provider?: ProviderV3;
+    /**
+     * Resolved provider ID.
+     */
+    resolvedProviderId?: ProviderId;
+    /**
+     * Result returned by the handler (pre-response).
+     */
+    result?: ChatCompletions | ChatCompletionsStream | Embeddings | Model | ModelList | Responses | ResponsesStream;
+    /**
+     * Response object returned by the handler.
+     */
+    response?: Response;
+    /**
+     * Error thrown during execution.
+     */
+    error?: unknown;
+};
+/**
+ * Hook context: all fields readonly except `state` and `otel`.
+ */
+export type HookContext = Omit<Readonly<GatewayContext>, "state" | "otel"> & {
+    state: GatewayContext["state"];
+    otel: GatewayContext["otel"];
+};
+type RequiredHookContext<K extends keyof GatewayContext> = Omit<HookContext, K> & Required<Pick<HookContext, K>>;
+export type OnRequestHookContext = RequiredHookContext<"request">;
+export type BeforeHookContext = RequiredHookContext<"request" | "operation" | "body">;
+export type ResolveModelHookContext = RequiredHookContext<"request" | "operation" | "body" | "modelId">;
+export type ResolveProviderHookContext = RequiredHookContext<"request" | "operation" | "body" | "modelId" | "resolvedModelId">;
+export type AfterHookContext = RequiredHookContext<"request" | "operation" | "body" | "modelId" | "resolvedModelId" | "provider" | "resolvedProviderId" | "result">;
+export type OnResponseHookContext = RequiredHookContext<"request" | "response">;
+export type OnErrorHookContext = RequiredHookContext<"error">;
+/**
+ * Hooks to plugin to the gateway lifecycle.
+ */
+export type GatewayHooks = {
+    /**
+     * Runs before any endpoint handler logic.
+     * @returns Optional Response to short-circuit the request.
+     */
+    onRequest?: (ctx: OnRequestHookContext) => void | Response | Promise<void | Response>;
+    /**
+     * Runs after request JSON is parsed and validated for chat completions / embeddings / responses.
+     * @returns Replacement parsed body, or undefined to keep original.
+     */
+    before?: (ctx: BeforeHookContext) => void | ChatCompletionsBody | EmbeddingsBody | ResponsesBody | Promise<void | ChatCompletionsBody | EmbeddingsBody | ResponsesBody>;
+    /**
+     * Maps a user-provided model ID or alias to a canonical ID.
+     * @returns Canonical model ID or undefined to keep original.
+     */
+    resolveModelId?: (ctx: ResolveModelHookContext) => ModelId | void | Promise<ModelId | void>;
+    /**
+     * Picks a provider instance for the request.
+     * @returns ProviderV3 to override, or undefined to use default.
+     */
+    resolveProvider?: (ctx: ResolveProviderHookContext) => ProviderV3 | void | Promise<ProviderV3 | void>;
+    /**
+     * Runs after the endpoint handler.
+     * @returns Result to replace, or undefined to keep original.
+     */
+    after?: (ctx: AfterHookContext) => void | ChatCompletions | ChatCompletionsStream | Embeddings | Model | ModelList | Responses | ResponsesStream | Promise<void | ChatCompletions | ChatCompletionsStream | Embeddings | Model | ModelList | Responses | ResponsesStream>;
+    /**
+     * Runs after the lifecycle has produced the final Response.
+     * @returns Replacement Response, or undefined to keep original.
+     */
+    onResponse?: (ctx: OnResponseHookContext) => void | Response | Promise<void | Response>;
+    /**
+     * Runs when the lifecycle catches an error.
+     * @returns Optional Response to replace the default error response.
+     */
+    onError?: (ctx: OnErrorHookContext) => void | Response | Promise<void | Response>;
+};
+export type TelemetrySignalLevel = "off" | "required" | "recommended" | "full";
+export declare const DEFAULT_CHAT_TIMEOUT_MS: number;
+export type GatewayTimeout = number | null | {
+    /**
+     * Default timeout used.
+     */
+    normal?: number | null;
+    /**
+     * Timeout used when `service_tier=flex`.
+     * Defaults to 3x `normal` when omitted.
+     */
+    flex?: number | null;
+};
+/**
+ * Main configuration object for the gateway.
+ */
+export type GatewayConfig = {
+    /**
+     * Optional base path the gateway is mounted under (e.g. "/v1/gateway").
+     */
+    basePath?: string;
+    /**
+     * Provider registry keyed by canonical provider IDs.
+     */
+    providers: ProviderRegistry;
+    /**
+     * Model catalog keyed by canonical model IDs.
+     */
+    models: ModelCatalog;
+    /**
+     * Optional lifecycle hooks for routing, auth, and response shaping.
+     */
+    hooks?: GatewayHooks;
+    /**
+     * Preferred logger configuration: custom logger or default logger settings.
+     */
+    logger?: Logger | LoggerConfig | null;
+    /**
+     * Optional conversation storage backend.
+     * Defaults to an in-memory storage if not provided.
+     */
+    storage?: ConversationStorage;
+    /**
+     * Optional AI SDK telemetry configuration.
+     */
+    telemetry?: {
+        /**
+         * Enable AI SDK OpenTelemetry instrumentation.
+         * Disabled by default.
+         */
+        enabled?: boolean;
+        /**
+         * Optional custom OpenTelemetry tracer passed to AI SDK telemetry.
+         */
+        tracer?: Tracer;
+        /**
+         * Telemetry signal levels by namespace.
+         * - off: disable the namespace
+         * - required: minimal baseline
+         * - recommended: practical defaults
+         * - full: include all available details
+         */
+        signals?: {
+            gen_ai?: TelemetrySignalLevel;
+            http?: TelemetrySignalLevel;
+            hebo?: TelemetrySignalLevel;
+        };
+    };
+    /**
+     * Optional timeout for server responses.
+     * Supports a number in milliseconds, or tiered config.
+     */
+    timeouts?: GatewayTimeout;
+    /**
+     * Maximum *decompressed* request body size in bytes for gzip/deflate-encoded requests.
+     * Plain (uncompressed) request body size limits should be configured at the
+     * framework or server level (e.g. Hono `bodyLimit` middleware, Bun `maxRequestBodySize`).
+     * Set to `0` to disable the decompressed size limit.
+     * Defaults to 10 MB (10,485,760 bytes).
+     */
+    maxBodySize?: number;
+};
+export declare const kParsed: unique symbol;
+export type GatewayConfigParsed = Omit<GatewayConfig, "storage" | "timeouts"> & {
+    storage: ConversationStorage;
+    timeouts: {
+        normal?: number;
+        flex?: number;
+    };
+    maxBodySize: number;
+    [kParsed]: true;
+};
+export interface Endpoint {
+    handler: (request: Request, state?: Record<string, unknown>) => Promise<Response>;
+}
+export interface HeboGateway<Routes extends Record<string, Endpoint>> extends Endpoint {
+    routes: Routes;
+}
+export {};

package/dist/types.js

@@ -0,0 +1,2 @@
+export const DEFAULT_CHAT_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+export const kParsed = Symbol("hebo.gateway.parsed");

package/dist/utils/body.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Default maximum decompressed body size (10 MB).
+ */
+export declare const DEFAULT_MAX_BODY_SIZE: number;
+/**
+ * Parse a request body as JSON, handling Content-Encoding decompression
+ * and enforcing a decompressed body size limit for compressed requests.
+ *
+ * For plain (uncompressed) requests, body size enforcement is expected to be
+ * handled by the parent framework (e.g. Hono's `bodyLimit` middleware, or
+ * Bun/Node server-level `maxRequestBodySize`). This utility only enforces
+ * `maxBodySize` on the *decompressed* output of gzip/deflate streams, since
+ * the framework cannot know the decompressed size ahead of time.
+ *
+ * @param request - Incoming Web API Request
+ * @param maxBodySize - Maximum decompressed body size in bytes. `0` disables the limit. Defaults to 10 MB.
+ * @returns Parsed JSON body
+ */
+export declare function parseRequestBody(request: Request, maxBodySize?: number): Promise<unknown>;

package/dist/utils/body.js

@@ -0,0 +1,99 @@
+import { GatewayError } from "../errors/gateway";
+/**
+ * Supported Content-Encoding values for request body decompression.
+ * Uses the Web Compression Streams API (`DecompressionStream`) for runtime portability.
+ */
+const SUPPORTED_ENCODINGS = new Set(["gzip", "deflate"]);
+/**
+ * Default maximum decompressed body size (10 MB).
+ */
+export const DEFAULT_MAX_BODY_SIZE = 10 * 1024 * 1024;
+/**
+ * Parse a request body as JSON, handling Content-Encoding decompression
+ * and enforcing a decompressed body size limit for compressed requests.
+ *
+ * For plain (uncompressed) requests, body size enforcement is expected to be
+ * handled by the parent framework (e.g. Hono's `bodyLimit` middleware, or
+ * Bun/Node server-level `maxRequestBodySize`). This utility only enforces
+ * `maxBodySize` on the *decompressed* output of gzip/deflate streams, since
+ * the framework cannot know the decompressed size ahead of time.
+ *
+ * @param request - Incoming Web API Request
+ * @param maxBodySize - Maximum decompressed body size in bytes. `0` disables the limit. Defaults to 10 MB.
+ * @returns Parsed JSON body
+ */
+export function parseRequestBody(request, maxBodySize = DEFAULT_MAX_BODY_SIZE) {
+    const encoding = request.headers.get("content-encoding");
+    // No encoding — delegate to framework for size enforcement, just parse JSON.
+    if (!encoding || encoding === "identity") {
+        return parsePlainBody(request);
+    }
+    // Reject unsupported encodings early.
+    if (!SUPPORTED_ENCODINGS.has(encoding)) {
+        throw new GatewayError(`Unsupported Content-Encoding: ${encoding}`, 415);
+    }
+    return parseCompressedBody(request, encoding, maxBodySize);
+}
+async function parsePlainBody(request) {
+    try {
+        return await request.json();
+    }
+    catch {
+        throw new GatewayError("Invalid JSON", 400);
+    }
+}
+async function parseCompressedBody(request, encoding, maxBodySize) {
+    if (!request.body) {
+        throw new GatewayError("Empty request body", 400);
+    }
+    let decompressedStream;
+    try {
+        decompressedStream = request.body.pipeThrough(new DecompressionStream(encoding));
+    }
+    catch {
+        throw new GatewayError("Invalid compressed body", 400);
+    }
+    // Read decompressed bytes with size enforcement.
+    const chunks = [];
+    let totalSize = 0;
+    try {
+        const reader = decompressedStream.getReader();
+        // oxlint-disable-next-line no-await-in-loop -- sequential stream reads
+        for (let r = await reader.read(); !r.done; r = await reader.read()) {
+            totalSize += r.value.byteLength;
+            if (maxBodySize > 0 && totalSize > maxBodySize) {
+                void reader.cancel();
+                throw new GatewayError(`Decompressed body too large (exceeds ${maxBodySize} byte limit)`, 413);
+            }
+            chunks.push(r.value);
+        }
+    }
+    catch (error) {
+        if (error instanceof GatewayError)
+            throw error;
+        throw new GatewayError("Invalid compressed body", 400);
+    }
+    if (totalSize === 0) {
+        throw new GatewayError("Empty request body", 400);
+    }
+    // Concatenate chunks and parse JSON.
+    try {
+        let text;
+        if (chunks.length === 1) {
+            text = new TextDecoder().decode(chunks[0]);
+        }
+        else {
+            const combined = new Uint8Array(totalSize);
+            let offset = 0;
+            for (const chunk of chunks) {
+                combined.set(chunk, offset);
+                offset += chunk.byteLength;
+            }
+            text = new TextDecoder().decode(combined);
+        }
+        return JSON.parse(text);
+    }
+    catch {
+        throw new GatewayError("Invalid JSON", 400);
+    }
+}

package/dist/utils/env.d.ts

@@ -0,0 +1,2 @@
+export declare const isProduction: () => boolean;
+export declare const isTest: () => boolean;

package/dist/utils/env.js

@@ -0,0 +1,7 @@
+// oxlint-disable-next-line no-unsafe-assignment
+const NODE_ENV = typeof process === "undefined"
+    ? // oxlint-disable-next-line no-unsafe-member-access
+        (globalThis.NODE_ENV ?? globalThis.ENV?.NODE_ENV)
+    : process.env?.["NODE_ENV"];
+export const isProduction = () => NODE_ENV === "production";
+export const isTest = () => NODE_ENV === "test";

package/dist/utils/headers.d.ts

@@ -0,0 +1,4 @@
+export declare const REQUEST_ID_HEADER = "x-request-id";
+type HeaderSource = Request | ResponseInit | undefined;
+export declare const resolveRequestId: (source: HeaderSource) => string | undefined;
+export {};