@hile/http-over-micro 1.0.1

package/AI.md

@@ -0,0 +1,350 @@
+# AI Guide For @hile/http-over-micro
+
+
+
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
+
+
+
+Purpose: Preserve HTTP method, headers, status, JSON bodies, and binary streams across Registry-discovered Hile Micro calls.
+
+
+
+Use this file when an AI agent installs the npm package and needs package-local examples, package selection rules, boundaries, and verification steps.
+
+
+
+## Package Selection
+
+
+
+| User asks for | Use | Also read |
+|---|---|---|
+| Preserve HTTP semantics across a Micro call | `@hile/http-over-micro` | `packages/http-over-micro.md`, `packages/messaging-micro.md` |
+
+
+
+# HTTP Over Micro
+
+Package: `@hile/http-over-micro`.
+
+## Use When
+
+Use this package when one HTTP ingress must project a request to a Registry-discovered Hile microservice while preserving HTTP method, duplicate headers, query values, status, cookies, redirects, JSON bodies, and streamed file bodies.
+
+The package defines the transport contract only. The public listener and its authentication, authorization, route selection, header policy, and final Koa response remain owned by the gateway.
+
+## Do Not Use When
+
+- Do not use it for ordinary in-process HTTP controllers that do not cross a Micro boundary.
+- Do not use it as a durable queue or retry layer.
+- Do not use it for RSC Flight, MCP, WebSocket upgrades, HTTP trailers, or informational `1xx` responses; those protocols keep their own transports.
+- Do not put business logic in the gateway merely because the gateway performs the HTTP projection.
+
+## Install
+
+```bash
+pnpm add @hile/http-over-micro @hile/micro zod
+```
+
+## Imports
+
+```ts
+import {
+  callHttpOverMicro,
+  defineHttpOverMicroMessage,
+} from '@hile/http-over-micro'
+import { z } from 'zod'
+```
+
+## Copy-Paste Example
+
+Provider message:
+
+```ts
+// src/messages/posts/[slug].msg.ts
+import { defineHttpOverMicroMessage } from '@hile/http-over-micro'
+import { z } from 'zod'
+
+export default defineHttpOverMicroMessage({
+  method: 'POST',
+  schema: {
+    headers: z.object({ authorization: z.string().startsWith('Bearer ') }),
+    query: z.object({ draft: z.enum(['true', 'false']).default('false') }),
+    params: z.object({ slug: z.string().min(1) }),
+    body: z.object({ title: z.string().min(1), content: z.string() }),
+  },
+}, async ({ request, params, invocation }) => {
+  // Call a model here; the example only shows the transport result.
+  return {
+    status: 201,
+    headers: {
+      location: `/posts/${params.slug}`,
+      'set-cookie': ['flash=created; Path=/; HttpOnly', 'draft=; Max-Age=0; Path=/'],
+    },
+    body: {
+      created: true,
+      draft: request.query.draft === 'true',
+      requestId: invocation.context.values.requestId,
+    },
+  }
+})
+```
+
+Gateway-side call:
+
+```ts
+const response = await callHttpOverMicro(
+  app,
+  'cn.zlooks.blog.server',
+  '/posts/hello',
+  {
+    method: ctx.method,
+    headers: ctx.headers,
+    query: Object.entries(ctx.query).flatMap(([name, value]) =>
+      Array.isArray(value) ? value.map(item => [name, item] as const) : [[name, String(value)] as const],
+    ),
+    body: ctx.request.body,
+  },
+  { context: executionContext },
+)
+
+ctx.status = response.status
+for (const [name, value] of response.headers) ctx.append(name, value)
+return response.body
+```
+
+Pass only gateway-approved end-to-end request headers. The sample assumes a body parser has already produced `ctx.request.body`; use the untouched incoming `Readable` instead for raw uploads.
+
+## More Examples
+
+### Upload and download without a transport switch
+
+The caller supplies a normal JSON value or an `AsyncIterable`, `Uint8Array`, or `ArrayBuffer`. `callHttpOverMicro()` snapshots JSON values into the request envelope and automatically moves binary or iterable bodies into Micro request input.
+
+```ts
+import { createReadStream } from 'node:fs'
+
+const response = await callHttpOverMicro(app, 'files.server', '/files', {
+  method: 'PUT',
+  headers: { 'content-type': 'application/octet-stream' },
+  body: createReadStream('/tmp/archive.tar'),
+}, { context })
+
+if (response.bodyKind === 'stream') {
+  for await (const chunk of response.body) consumeDownloadedChunk(chunk)
+}
+```
+
+Provider:
+
+```ts
+import { Readable } from 'node:stream'
+
+export default defineHttpOverMicroMessage({ method: ['GET', 'PUT'] }, async ({ request }) => {
+  if (request.method === 'PUT') {
+    if (!(request.body instanceof Readable)) {
+      return { status: 400, body: { error: 'stream required' } }
+    }
+    await saveUpload(request.body)
+    return { status: 204 }
+  }
+
+  return {
+    status: 200,
+    headers: { 'content-type': 'application/octet-stream' },
+    body: openDownloadStream(),
+  }
+})
+```
+
+Streaming request bodies are non-replayable. Leave retries unset or set `retries: 0`; an explicit nonzero value fails before dispatch.
+
+### Response metadata before response bytes
+
+Every HTTP-over-Micro call uses one Micro response stream. Its first chunk is a response head; body chunks follow only when `body.kind` is `stream`:
+
+```ts
+type RequestEnvelope = {
+  protocol: '@hile/http-over-micro'
+  version: 1
+  type: 'request'
+  method: string
+  headers: Array<[string, string]>
+  query: Array<[string, string]>
+  body: { kind: 'empty' } | { kind: 'inline'; value: unknown } | { kind: 'stream' }
+}
+
+type ResponseHead = {
+  protocol: '@hile/http-over-micro'
+  version: 1
+  type: 'response'
+  status: number
+  headers: Array<[string, string]>
+  body: { kind: 'empty' } | { kind: 'inline'; value: unknown } | { kind: 'stream' }
+}
+```
+
+Header tuples deliberately preserve order and duplicate fields such as `Set-Cookie`. Header names are canonical lowercase on the wire. Query tuples preserve repeated query values without inventing an object serialization rule.
+
+### Zod parses, not merely checks
+
+`schema.headers`, `schema.query`, `schema.params`, and `schema.body` each receive the logical value seen by the handler. Schema transforms and coercions are returned to the handler.
+
+For a streamed request, `schema.body` receives the `Readable`. Use a Zod custom or union schema only when that endpoint intentionally accepts a stream; a JSON-object body schema rejects the stream naturally.
+
+## Compose With
+
+- Use `@hile/http` or `@hile/http-next` for the one public HTTP listener and file-system Controller.
+- Use `@hile/micro` for Registry discovery, context propagation, cancellation, timeouts, and credit-based input/output flow control.
+- Use `@hile/model` behind the provider handler for reusable business behavior.
+- Use the gateway's own policy to select which headers and cookies may cross the boundary; this package preserves selected values but does not authorize them.
+
+## Runtime And Lifecycle Notes
+
+- `defineHttpOverMicroMessage()` returns a normal `defineMicroMessage()` definition and is loaded or registered through the standard Micro message loader.
+- The Micro route remains the file/message path. HTTP method is protocol data and one definition may accept one method or a method list. Unsupported methods return `405` plus `Allow` without invoking the handler.
+- Inline bodies use JSON serialization semantics and default to a 1 MiB bound. Override `limits.maxInlineBodyBytes` explicitly on both ends when a deployment requires another limit; use streams for files and large byte bodies.
+- Final response statuses are `200..599`. `HEAD`, `204`, `205`, and `304` responses reject bodies. `1xx`, protocol upgrades, and trailers are intentionally out of scope.
+- Destroying the returned streamed body cancels the underlying Micro response. `signal`, total timeout, idle timeout, and stream window are passed to `Application.stream()`.
+- Credit-based backpressure bounds buffered chunks, not the total number of transferred bytes. The HTTP ingress and provider handler must each enforce their endpoint-specific upload/download byte limit while consuming a stream.
+- The caller owns the returned response stream and must consume or destroy it. The package fully consumes empty and inline responses before resolving.
+- Cookies and `Location` are opaque response headers. The public gateway remains responsible for cookie ownership, security attributes, redirect policy, and hop-by-hop header removal.
+- Treat `namespace` and `url` as routing authority. A public gateway must resolve them through its validated provider catalog or an equivalent allow policy; never dispatch an arbitrary client-supplied namespace directly.
+
+## Anti-Patterns
+
+- Do not handcraft the request envelope or consume the response-head frame yourself; use `callHttpOverMicro()`.
+- Do not call `Application.call()` for this protocol. A response may need headers followed by a body stream, so the package intentionally uses `Application.stream()` for every result.
+- Do not encode files as Base64 inside an inline JSON body.
+- Do not collapse response headers into a plain object when duplicate `Set-Cookie` values matter.
+- Do not enable retries for an upload stream.
+- Do not forward every inbound header, raw cookie, or identity credential merely because the protocol can carry it.
+
+## Verification Checklist
+
+- Unit tests cover inline, empty, malformed, method-mismatch, and Zod-coercion cases.
+- A real Registry-discovered WebSocket test carries request and response streams at the same time.
+- Duplicate response headers survive in order.
+- Invalid request metadata fails with HTTP status `400`; invalid upstream response metadata fails locally with `502`.
+- Inline bodies are bounded and JSON-serializable; files use stream bodies.
+- Cancellation, timeout, idle timeout, and backpressure remain owned by `@hile/micro` and `@hile/message-modem`.
+
+
+
+# Related Recipes
+
+
+
+# Micro RPC With Message Loader
+
+## Complete Example
+
+Provider handler:
+
+```ts
+// src/messages/charge.msg.ts
+import { defineMicroMessage } from '@hile/micro'
+
+export default defineMicroMessage(async ({ data, invocation }) => {
+  return { charged: true, input: data, requestId: invocation.context.values.requestId }
+})
+```
+
+Provider boot:
+
+```ts
+// src/services/app.boot.ts
+import { defineService } from '@hile/core'
+import { Application } from '@hile/micro'
+
+export default defineService('billing.micro', async (shutdown) => {
+  const app = new Application({
+    namespace: 'billing',
+    registry: { host: '127.0.0.1', port: 9876 },
+    advertiseHost: '127.0.0.1',
+  })
+
+  await app.load(new URL('../messages', import.meta.url).pathname)
+  const stop = await app.listen(9101)
+  shutdown(stop)
+  return app
+})
+```
+
+Consumer:
+
+```ts
+import { randomUUID } from 'node:crypto'
+import { createExecutionContext } from '@hile/context'
+
+const context = createExecutionContext({ requestId: randomUUID(), tenantId: 't1' })
+const result = await app.call('billing', '/charge', {
+  tenantId: 't1',
+  amount: 100,
+}, { context })
+```
+
+## File Layout
+
+```text
+provider/
+  src/messages/charge.msg.ts
+  src/services/app.boot.ts
+consumer/
+  src/models/payments/pay.model.ts
+```
+
+## User Intent
+
+Use this recipe when services communicate over Hile registry-backed RPC.
+
+## Packages To Use
+
+- `@hile/micro`
+- `@hile/context` for the required explicit execution context carrier
+- `@hile/redis-idempotency` for retryable side effects
+
+## Implementation Steps
+
+1. Start a Registry with `hile registry`.
+2. Start providers with stable namespaces.
+3. Default-export `defineMicroMessage()` handlers and load them through `app.load()`.
+4. Create context at ingress and call providers with `await app.call(namespace, url, data, { context })`.
+5. Use `app.stream()` only for async-generator handlers.
+6. For streamed request bodies, consume `input` in the `defineMicroMessage()` handler and pass the source through `options.input`; pass the stream as `data` only when no structured metadata is needed.
+
+## Failure And Cleanup Behavior
+
+- `Application.call()` may retry; side-effecting handlers need idempotency.
+- A streamed request body is non-replayable. Its retry default is `0`, and an explicit nonzero retry count is rejected before discovery.
+- Request input and response output have independent credit-based backpressure and may be active together.
+- Registry disconnect triggers reconnect; apps re-declare topics and subscriptions.
+- Circuit breaker excludes failing nodes for cooldown.
+
+## Verification Checklist
+
+- Registry is reachable.
+- Provider namespace matches consumer call.
+- Handlers default-export `defineMicroMessage()` and consume explicit invocation context when needed.
+- Consumer code awaits `app.call(..., { context })` directly.
+- Streamed request handlers consume `input: Readable`, preserve structured metadata in `data`, and do not enable retries.
+
+
+
+# Global Guardrails
+
+
+
+## Never Generate These Patterns
+
+- Do not call `loadService()` at module top level; it starts resources during import.
+- Do not default-export plain functions from `*.boot.*` files; `hile start` expects a Hile service.
+- Do not set `ctx.body` and also return a controller value.
+- Do not assume `@hile/http` Zod validation mutates or coerces `ctx.query`, `ctx.params`, or `ctx.request.body`.
+- Do not put reusable business logic only in controllers, pages, queue workers, or message handlers.
+- Do not use old message examples that append a secondary response getter; current request APIs return promises directly.
+- Do not invent service-specific HTTP-in-Micro envelopes or Base64 file bodies; use `@hile/http-over-micro` and its request/response streams.
+- Do not claim exactly-once delivery or execution from Redis locks, queues, idempotency, or rate limits.
+- Do not use queue `jobId` as the only side-effect idempotency boundary.
+- Do not log the entire async context by default.

package/README.md

@@ -0,0 +1,176 @@
+# @hile/http-over-micro
+
+<!-- Generated by scripts/build-ai-context.mjs from docs/ai. Do not edit by hand. -->
+
+Preserve HTTP method, headers, status, JSON bodies, and binary streams across Registry-discovered Hile Micro calls.
+
+This README is intentionally short and example-first. The complete AI-facing guide ships in `AI.md` in this package.
+
+## When To Use
+
+Use this package when one HTTP ingress must project a request to a Registry-discovered Hile microservice while preserving HTTP method, duplicate headers, query values, status, cookies, redirects, JSON bodies, and streamed file bodies.
+
+The package defines the transport contract only. The public listener and its authentication, authorization, route selection, header policy, and final Koa response remain owned by the gateway.
+
+## Install
+
+```bash
+pnpm add @hile/http-over-micro @hile/micro zod
+```
+
+## Copy-Paste Example
+
+Provider message:
+
+```ts
+// src/messages/posts/[slug].msg.ts
+import { defineHttpOverMicroMessage } from '@hile/http-over-micro'
+import { z } from 'zod'
+
+export default defineHttpOverMicroMessage({
+  method: 'POST',
+  schema: {
+    headers: z.object({ authorization: z.string().startsWith('Bearer ') }),
+    query: z.object({ draft: z.enum(['true', 'false']).default('false') }),
+    params: z.object({ slug: z.string().min(1) }),
+    body: z.object({ title: z.string().min(1), content: z.string() }),
+  },
+}, async ({ request, params, invocation }) => {
+  // Call a model here; the example only shows the transport result.
+  return {
+    status: 201,
+    headers: {
+      location: `/posts/${params.slug}`,
+      'set-cookie': ['flash=created; Path=/; HttpOnly', 'draft=; Max-Age=0; Path=/'],
+    },
+    body: {
+      created: true,
+      draft: request.query.draft === 'true',
+      requestId: invocation.context.values.requestId,
+    },
+  }
+})
+```
+
+Gateway-side call:
+
+```ts
+const response = await callHttpOverMicro(
+  app,
+  'cn.zlooks.blog.server',
+  '/posts/hello',
+  {
+    method: ctx.method,
+    headers: ctx.headers,
+    query: Object.entries(ctx.query).flatMap(([name, value]) =>
+      Array.isArray(value) ? value.map(item => [name, item] as const) : [[name, String(value)] as const],
+    ),
+    body: ctx.request.body,
+  },
+  { context: executionContext },
+)
+
+ctx.status = response.status
+for (const [name, value] of response.headers) ctx.append(name, value)
+return response.body
+```
+
+Pass only gateway-approved end-to-end request headers. The sample assumes a body parser has already produced `ctx.request.body`; use the untouched incoming `Readable` instead for raw uploads.
+
+## Upload and download without a transport switch
+
+The caller supplies a normal JSON value or an `AsyncIterable`, `Uint8Array`, or `ArrayBuffer`. `callHttpOverMicro()` snapshots JSON values into the request envelope and automatically moves binary or iterable bodies into Micro request input.
+
+```ts
+import { createReadStream } from 'node:fs'
+
+const response = await callHttpOverMicro(app, 'files.server', '/files', {
+  method: 'PUT',
+  headers: { 'content-type': 'application/octet-stream' },
+  body: createReadStream('/tmp/archive.tar'),
+}, { context })
+
+if (response.bodyKind === 'stream') {
+  for await (const chunk of response.body) consumeDownloadedChunk(chunk)
+}
+```
+
+Provider:
+
+```ts
+import { Readable } from 'node:stream'
+
+export default defineHttpOverMicroMessage({ method: ['GET', 'PUT'] }, async ({ request }) => {
+  if (request.method === 'PUT') {
+    if (!(request.body instanceof Readable)) {
+      return { status: 400, body: { error: 'stream required' } }
+    }
+    await saveUpload(request.body)
+    return { status: 204 }
+  }
+
+  return {
+    status: 200,
+    headers: { 'content-type': 'application/octet-stream' },
+    body: openDownloadStream(),
+  }
+})
+```
+
+Streaming request bodies are non-replayable. Leave retries unset or set `retries: 0`; an explicit nonzero value fails before dispatch.
+
+## Response metadata before response bytes
+
+Every HTTP-over-Micro call uses one Micro response stream. Its first chunk is a response head; body chunks follow only when `body.kind` is `stream`:
+
+```ts
+type RequestEnvelope = {
+  protocol: '@hile/http-over-micro'
+  version: 1
+  type: 'request'
+  method: string
+  headers: Array<[string, string]>
+  query: Array<[string, string]>
+  body: { kind: 'empty' } | { kind: 'inline'; value: unknown } | { kind: 'stream' }
+}
+
+type ResponseHead = {
+  protocol: '@hile/http-over-micro'
+  version: 1
+  type: 'response'
+  status: number
+  headers: Array<[string, string]>
+  body: { kind: 'empty' } | { kind: 'inline'; value: unknown } | { kind: 'stream' }
+}
+```
+
+Header tuples deliberately preserve order and duplicate fields such as `Set-Cookie`. Header names are canonical lowercase on the wire. Query tuples preserve repeated query values without inventing an object serialization rule.
+
+## Boundaries
+
+- Do not use it for ordinary in-process HTTP controllers that do not cross a Micro boundary.
+- Do not use it as a durable queue or retry layer.
+- Do not use it for RSC Flight, MCP, WebSocket upgrades, HTTP trailers, or informational `1xx` responses; those protocols keep their own transports.
+- Do not put business logic in the gateway merely because the gateway performs the HTTP projection.
+
+- Do not handcraft the request envelope or consume the response-head frame yourself; use `callHttpOverMicro()`.
+- Do not call `Application.call()` for this protocol. A response may need headers followed by a body stream, so the package intentionally uses `Application.stream()` for every result.
+- Do not encode files as Base64 inside an inline JSON body.
+- Do not collapse response headers into a plain object when duplicate `Set-Cookie` values matter.
+- Do not enable retries for an upload stream.
+- Do not forward every inbound header, raw cookie, or identity credential merely because the protocol can carry it.
+
+## Verify
+
+- Unit tests cover inline, empty, malformed, method-mismatch, and Zod-coercion cases.
+- A real Registry-discovered WebSocket test carries request and response streams at the same time.
+- Duplicate response headers survive in order.
+- Invalid request metadata fails with HTTP status `400`; invalid upstream response metadata fails locally with `502`.
+- Inline bodies are bounded and JSON-serializable; files use stream bodies.
+- Cancellation, timeout, idle timeout, and backpressure remain owned by `@hile/micro` and `@hile/message-modem`.
+
+## More Context
+
+- `AI.md` in this package: full package-local AI guide.
+- Root `llms-full.txt`: full monorepo AI context.
+- Root `references/`: source files copied from `docs/ai`.

package/dist/client.d.ts

@@ -0,0 +1,33 @@
+import { Readable } from 'node:stream';
+import { type MessageInput } from '@hile/message-modem';
+import type { ApplicationStreamOptions } from '@hile/micro';
+import { type HttpFieldEntry, type HttpFieldInput } from './fields.js';
+import { type HttpOverMicroLimits } from './protocol.js';
+export interface HttpOverMicroApplication {
+    stream(namespace: string, url: string, data: unknown, options: ApplicationStreamOptions): Promise<Readable>;
+}
+export interface HttpOverMicroRequest<TBody = unknown> {
+    method: string;
+    headers?: HttpFieldInput;
+    query?: HttpFieldInput;
+    body?: TBody | MessageInput;
+}
+export type HttpOverMicroCallOptions = Omit<ApplicationStreamOptions, 'input'> & {
+    limits?: HttpOverMicroLimits;
+};
+type ResponseBase = {
+    status: number;
+    headers: readonly HttpFieldEntry[];
+};
+export type HttpOverMicroResponse<T = unknown> = (ResponseBase & {
+    bodyKind: 'empty';
+    body: undefined;
+}) | (ResponseBase & {
+    bodyKind: 'inline';
+    body: T;
+}) | (ResponseBase & {
+    bodyKind: 'stream';
+    body: Readable;
+});
+export declare function callHttpOverMicro<TResponse = unknown, TRequest = unknown>(application: HttpOverMicroApplication, namespace: string, url: string, request: HttpOverMicroRequest<TRequest>, options: HttpOverMicroCallOptions): Promise<HttpOverMicroResponse<TResponse>>;
+export {};

package/dist/client.js

@@ -0,0 +1,133 @@
+import { isMessageInput } from '@hile/message-modem';
+import { HttpOverMicroError } from './errors.js';
+import { normalizeHttpHeaders, normalizeHttpQuery, } from './fields.js';
+import { HTTP_OVER_MICRO_PROTOCOL, HTTP_OVER_MICRO_VERSION, httpOverMicroRequestEnvelopeSchema, httpOverMicroResponseHeadSchema, httpResponseMustBeEmpty, normalizeHttpMethod, resolveInlineBodyLimit, snapshotInlineBody, } from './protocol.js';
+const END = Symbol('http-over-micro-end');
+async function readNext(stream) {
+    const immediate = stream.read();
+    if (immediate !== null)
+        return immediate;
+    if (stream.readableEnded)
+        return END;
+    if (stream.destroyed)
+        throw stream.errored ?? new Error('Micro response stream closed');
+    return await new Promise((resolve, reject) => {
+        const cleanup = () => {
+            stream.off('readable', onReadable);
+            stream.off('end', onEnd);
+            stream.off('error', onError);
+            stream.off('close', onClose);
+        };
+        const onReadable = () => {
+            const value = stream.read();
+            if (value === null)
+                return;
+            cleanup();
+            resolve(value);
+        };
+        const onEnd = () => {
+            cleanup();
+            resolve(END);
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        const onClose = () => {
+            cleanup();
+            if (stream.readableEnded) {
+                resolve(END);
+                return;
+            }
+            reject(stream.errored ?? new Error('Micro response stream closed'));
+        };
+        stream.on('readable', onReadable);
+        stream.once('end', onEnd);
+        stream.once('error', onError);
+        stream.once('close', onClose);
+        // Close the read-before-listen race if a chunk arrived while handlers were attached.
+        onReadable();
+    });
+}
+function invalidResponse(message, cause) {
+    return new HttpOverMicroError('INVALID_RESPONSE', 502, message, { cause });
+}
+function invalidRequest(message, cause) {
+    return new HttpOverMicroError('INVALID_REQUEST', 400, message, { cause });
+}
+function closeInvalidStream(stream) {
+    if (!stream.destroyed)
+        stream.destroy();
+}
+export async function callHttpOverMicro(application, namespace, url, request, options) {
+    if (!request || typeof request !== 'object') {
+        throw invalidRequest('HTTP-over-Micro request must be an object');
+    }
+    const maxInlineBodyBytes = resolveInlineBodyLimit(options.limits?.maxInlineBodyBytes);
+    const input = isMessageInput(request.body) ? request.body : undefined;
+    if (input && options.retries !== undefined && options.retries !== 0) {
+        throw new TypeError('Streamed HTTP request bodies are non-replayable and require retries: 0');
+    }
+    let envelope;
+    try {
+        envelope = {
+            protocol: HTTP_OVER_MICRO_PROTOCOL,
+            version: HTTP_OVER_MICRO_VERSION,
+            type: 'request',
+            method: normalizeHttpMethod(request.method),
+            headers: normalizeHttpHeaders(request.headers),
+            query: normalizeHttpQuery(request.query),
+            body: input
+                ? { kind: 'stream' }
+                : request.body === undefined
+                    ? { kind: 'empty' }
+                    : { kind: 'inline', value: snapshotInlineBody(request.body, maxInlineBodyBytes, 'request') },
+        };
+    }
+    catch (cause) {
+        if (cause instanceof HttpOverMicroError)
+            throw cause;
+        throw invalidRequest('Invalid HTTP-over-Micro request metadata', cause);
+    }
+    const checkedEnvelope = httpOverMicroRequestEnvelopeSchema.safeParse(envelope);
+    if (!checkedEnvelope.success) {
+        throw invalidRequest('Invalid HTTP-over-Micro request', checkedEnvelope.error);
+    }
+    const { limits: _limits, ...streamOptions } = options;
+    const stream = await application.stream(namespace, url, checkedEnvelope.data, input
+        ? { ...streamOptions, input }
+        : streamOptions);
+    const first = await readNext(stream);
+    if (first === END)
+        throw invalidResponse('HTTP-over-Micro response ended before its response head');
+    const parsedHead = httpOverMicroResponseHeadSchema.safeParse(first);
+    if (!parsedHead.success) {
+        closeInvalidStream(stream);
+        throw invalidResponse('Invalid HTTP-over-Micro response head', parsedHead.error);
+    }
+    const base = { status: parsedHead.data.status, headers: parsedHead.data.headers };
+    if (parsedHead.data.body.kind !== 'empty'
+        && httpResponseMustBeEmpty(checkedEnvelope.data.method, parsedHead.data.status)) {
+        closeInvalidStream(stream);
+        throw invalidResponse(`HTTP ${checkedEnvelope.data.method} response with status ${parsedHead.data.status} must not include a body`);
+    }
+    if (parsedHead.data.body.kind === 'stream') {
+        return { ...base, bodyKind: 'stream', body: stream };
+    }
+    const trailing = await readNext(stream);
+    if (trailing !== END) {
+        closeInvalidStream(stream);
+        throw invalidResponse('Inline HTTP-over-Micro response contains trailing stream frames');
+    }
+    if (parsedHead.data.body.kind === 'empty') {
+        return { ...base, bodyKind: 'empty', body: undefined };
+    }
+    let body;
+    try {
+        body = snapshotInlineBody(parsedHead.data.body.value, maxInlineBodyBytes, 'response');
+    }
+    catch (cause) {
+        throw invalidResponse('Invalid HTTP-over-Micro inline response body', cause);
+    }
+    return { ...base, bodyKind: 'inline', body: body };
+}

package/dist/errors.d.ts

@@ -0,0 +1,14 @@
+import { Exception } from '@hile/message-modem';
+export type HttpOverMicroErrorCode = 'INVALID_DEFINITION' | 'INVALID_REQUEST' | 'INVALID_RESPONSE';
+/**
+ * A protocol-boundary failure. `status` survives the Micro transport so an
+ * HTTP gateway can distinguish invalid client input from an invalid upstream.
+ */
+export declare class HttpOverMicroError extends Exception {
+    readonly code: HttpOverMicroErrorCode;
+    readonly name = "HttpOverMicroError";
+    readonly cause?: unknown;
+    constructor(code: HttpOverMicroErrorCode, status: number, message: string, options?: {
+        cause?: unknown;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,15 @@
+import { Exception } from '@hile/message-modem';
+/**
+ * A protocol-boundary failure. `status` survives the Micro transport so an
+ * HTTP gateway can distinguish invalid client input from an invalid upstream.
+ */
+export class HttpOverMicroError extends Exception {
+    code;
+    name = 'HttpOverMicroError';
+    cause;
+    constructor(code, status, message, options) {
+        super(status, message);
+        this.code = code;
+        this.cause = options?.cause;
+    }
+}

package/dist/fields.d.ts

@@ -0,0 +1,10 @@
+export type HttpFieldEntry = readonly [name: string, value: string];
+export declare const MAX_HTTP_FIELD_ENTRIES = 256;
+export type HttpFieldInput = Readonly<Record<string, string | readonly string[] | undefined>> | Iterable<HttpFieldEntry>;
+export type HttpFieldValues = Readonly<Record<string, string | readonly string[]>>;
+/** Normalizes header names to lowercase while preserving duplicate values. */
+export declare function normalizeHttpHeaders(input?: HttpFieldInput): Array<[string, string]>;
+/** Preserves query-key casing and duplicate values. */
+export declare function normalizeHttpQuery(input?: HttpFieldInput): Array<[string, string]>;
+/** Converts duplicate entries to string arrays without losing their order. */
+export declare function httpFieldsToRecord(entries: readonly HttpFieldEntry[]): HttpFieldValues;

package/dist/fields.js

@@ -0,0 +1,66 @@
+export const MAX_HTTP_FIELD_ENTRIES = 256;
+function isIterable(value) {
+    return Symbol.iterator in value && typeof value[Symbol.iterator] === 'function';
+}
+function appendEntry(entries, name, value, normalizeName) {
+    if (entries.length >= MAX_HTTP_FIELD_ENTRIES) {
+        throw new TypeError(`HTTP fields must not contain more than ${MAX_HTTP_FIELD_ENTRIES} entries`);
+    }
+    if (typeof name !== 'string' || typeof value !== 'string') {
+        throw new TypeError('HTTP field names and values must be strings');
+    }
+    entries.push([normalizeName ? name.toLowerCase() : name, value]);
+}
+function normalizeEntries(input, normalizeName) {
+    if (input === undefined)
+        return [];
+    if (!input || typeof input !== 'object') {
+        throw new TypeError('HTTP fields must be a record or an iterable of string pairs');
+    }
+    const entries = [];
+    if (isIterable(input)) {
+        for (const pair of input) {
+            if (!Array.isArray(pair) || pair.length !== 2) {
+                throw new TypeError('HTTP field iterables must contain [name, value] pairs');
+            }
+            appendEntry(entries, pair[0], pair[1], normalizeName);
+        }
+        return entries;
+    }
+    for (const [name, value] of Object.entries(input)) {
+        if (value === undefined)
+            continue;
+        if (typeof value === 'string') {
+            appendEntry(entries, name, value, normalizeName);
+            continue;
+        }
+        if (!Array.isArray(value)) {
+            throw new TypeError('HTTP field record values must be strings or string arrays');
+        }
+        for (const item of value)
+            appendEntry(entries, name, item, normalizeName);
+    }
+    return entries;
+}
+/** Normalizes header names to lowercase while preserving duplicate values. */
+export function normalizeHttpHeaders(input) {
+    return normalizeEntries(input, true);
+}
+/** Preserves query-key casing and duplicate values. */
+export function normalizeHttpQuery(input) {
+    return normalizeEntries(input, false);
+}
+/** Converts duplicate entries to string arrays without losing their order. */
+export function httpFieldsToRecord(entries) {
+    const output = Object.create(null);
+    for (const [name, value] of entries) {
+        const current = output[name];
+        if (current === undefined)
+            output[name] = value;
+        else if (typeof current === 'string')
+            output[name] = [current, value];
+        else
+            output[name] = [...current, value];
+    }
+    return output;
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { callHttpOverMicro, type HttpOverMicroApplication, type HttpOverMicroCallOptions, type HttpOverMicroRequest, type HttpOverMicroResponse, } from './client.js';
+export { HttpOverMicroError, type HttpOverMicroErrorCode } from './errors.js';
+export { MAX_HTTP_FIELD_ENTRIES, httpFieldsToRecord, normalizeHttpHeaders, normalizeHttpQuery, type HttpFieldEntry, type HttpFieldInput, type HttpFieldValues, } from './fields.js';
+export { DEFAULT_MAX_INLINE_BODY_BYTES, HTTP_OVER_MICRO_PROTOCOL, HTTP_OVER_MICRO_VERSION, httpOverMicroRequestEnvelopeSchema, httpOverMicroResponseHeadSchema, type HttpOverMicroBodyDescriptor, type HttpOverMicroLimits, type HttpOverMicroRequestEnvelope, type HttpOverMicroResponseHead, } from './protocol.js';
+export { defineHttpOverMicroMessage, type HttpOverMicroHandler, type HttpOverMicroHandlerContext, type HttpOverMicroHandlerResponse, type HttpOverMicroMessageConfig, type HttpOverMicroSchemas, } from './server.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { callHttpOverMicro, } from './client.js';
+export { HttpOverMicroError } from './errors.js';
+export { MAX_HTTP_FIELD_ENTRIES, httpFieldsToRecord, normalizeHttpHeaders, normalizeHttpQuery, } from './fields.js';
+export { DEFAULT_MAX_INLINE_BODY_BYTES, HTTP_OVER_MICRO_PROTOCOL, HTTP_OVER_MICRO_VERSION, httpOverMicroRequestEnvelopeSchema, httpOverMicroResponseHeadSchema, } from './protocol.js';
+export { defineHttpOverMicroMessage, } from './server.js';

package/dist/protocol.d.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+import { type HttpFieldEntry } from './fields.js';
+export declare const HTTP_OVER_MICRO_PROTOCOL: "@hile/http-over-micro";
+export declare const HTTP_OVER_MICRO_VERSION: 1;
+export declare const DEFAULT_MAX_INLINE_BODY_BYTES: number;
+export interface HttpOverMicroLimits {
+    maxInlineBodyBytes?: number;
+}
+export type HttpOverMicroBodyDescriptor<T = unknown> = {
+    kind: 'empty';
+} | {
+    kind: 'inline';
+    value: T;
+} | {
+    kind: 'stream';
+};
+export interface HttpOverMicroRequestEnvelope<T = unknown> {
+    protocol: typeof HTTP_OVER_MICRO_PROTOCOL;
+    version: typeof HTTP_OVER_MICRO_VERSION;
+    type: 'request';
+    method: string;
+    headers: readonly HttpFieldEntry[];
+    query: readonly HttpFieldEntry[];
+    body: HttpOverMicroBodyDescriptor<T>;
+}
+export interface HttpOverMicroResponseHead<T = unknown> {
+    protocol: typeof HTTP_OVER_MICRO_PROTOCOL;
+    version: typeof HTTP_OVER_MICRO_VERSION;
+    type: 'response';
+    status: number;
+    headers: readonly HttpFieldEntry[];
+    body: HttpOverMicroBodyDescriptor<T>;
+}
+export declare const httpOverMicroRequestEnvelopeSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<"@hile/http-over-micro">;
+    version: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"request">;
+    method: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    headers: z.ZodArray<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
+    query: z.ZodArray<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
+    body: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"empty">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"inline">;
+        value: z.ZodUnknown;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"stream">;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>;
+export declare const httpOverMicroResponseHeadSchema: z.ZodObject<{
+    protocol: z.ZodLiteral<"@hile/http-over-micro">;
+    version: z.ZodLiteral<1>;
+    type: z.ZodLiteral<"response">;
+    status: z.ZodNumber;
+    headers: z.ZodArray<z.ZodTuple<[z.ZodString, z.ZodString], null>>;
+    body: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"empty">;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"inline">;
+        value: z.ZodUnknown;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"stream">;
+    }, z.core.$strict>], "kind">;
+}, z.core.$strict>;
+export declare function normalizeHttpMethod(value: string): string;
+export declare function resolveInlineBodyLimit(value?: number): number;
+export declare function httpResponseMustBeEmpty(method: string, status: number): boolean;
+export declare function snapshotInlineBody(value: unknown, maxBytes: number, subject: 'request' | 'response'): unknown;

package/dist/protocol.js

@@ -0,0 +1,96 @@
+import { Buffer } from 'node:buffer';
+import { z } from 'zod';
+import { HttpOverMicroError } from './errors.js';
+import { MAX_HTTP_FIELD_ENTRIES } from './fields.js';
+export const HTTP_OVER_MICRO_PROTOCOL = '@hile/http-over-micro';
+export const HTTP_OVER_MICRO_VERSION = 1;
+export const DEFAULT_MAX_INLINE_BODY_BYTES = 1024 * 1024;
+const MAX_METHOD_LENGTH = 64;
+const MAX_FIELD_NAME_LENGTH = 256;
+const MAX_FIELD_VALUE_LENGTH = 16 * 1024;
+const MAX_FIELDS_BYTES = 64 * 1024;
+const HTTP_TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+const methodSchema = z.string()
+    .min(1)
+    .max(MAX_METHOD_LENGTH)
+    .regex(HTTP_TOKEN)
+    .transform(value => value.toUpperCase());
+const headerEntrySchema = z.tuple([
+    z.string().min(1).max(MAX_FIELD_NAME_LENGTH).regex(HTTP_TOKEN)
+        .refine(value => value === value.toLowerCase(), 'Header names must be lowercase'),
+    z.string().max(MAX_FIELD_VALUE_LENGTH).refine(value => !/[\r\n\0]/.test(value), 'Invalid header value'),
+]);
+const queryEntrySchema = z.tuple([
+    z.string().max(MAX_FIELD_NAME_LENGTH).refine(value => !value.includes('\0'), 'Invalid query name'),
+    z.string().max(MAX_FIELD_VALUE_LENGTH).refine(value => !value.includes('\0'), 'Invalid query value'),
+]);
+function boundedEntries(schema) {
+    return z.array(schema).max(MAX_HTTP_FIELD_ENTRIES).superRefine((entries, context) => {
+        let bytes = 0;
+        for (const [name, value] of entries) {
+            bytes += Buffer.byteLength(name) + Buffer.byteLength(value);
+            if (bytes > MAX_FIELDS_BYTES) {
+                context.addIssue({ code: 'custom', message: `HTTP fields must not exceed ${MAX_FIELDS_BYTES} bytes` });
+                return;
+            }
+        }
+    });
+}
+const bodyDescriptorSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('empty') }).strict(),
+    z.object({ kind: z.literal('inline'), value: z.unknown() }).strict()
+        .refine(body => body.value !== undefined, 'Inline body value must not be undefined'),
+    z.object({ kind: z.literal('stream') }).strict(),
+]);
+export const httpOverMicroRequestEnvelopeSchema = z.object({
+    protocol: z.literal(HTTP_OVER_MICRO_PROTOCOL),
+    version: z.literal(HTTP_OVER_MICRO_VERSION),
+    type: z.literal('request'),
+    method: methodSchema,
+    headers: boundedEntries(headerEntrySchema),
+    query: boundedEntries(queryEntrySchema),
+    body: bodyDescriptorSchema,
+}).strict();
+export const httpOverMicroResponseHeadSchema = z.object({
+    protocol: z.literal(HTTP_OVER_MICRO_PROTOCOL),
+    version: z.literal(HTTP_OVER_MICRO_VERSION),
+    type: z.literal('response'),
+    status: z.number().int().min(200).max(599),
+    headers: boundedEntries(headerEntrySchema),
+    body: bodyDescriptorSchema,
+}).strict();
+export function normalizeHttpMethod(value) {
+    const parsed = methodSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new HttpOverMicroError('INVALID_REQUEST', 400, 'Invalid HTTP method', { cause: parsed.error });
+    }
+    return parsed.data;
+}
+export function resolveInlineBodyLimit(value) {
+    if (value === undefined)
+        return DEFAULT_MAX_INLINE_BODY_BYTES;
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new TypeError('maxInlineBodyBytes must be a positive safe integer');
+    }
+    return value;
+}
+export function httpResponseMustBeEmpty(method, status) {
+    return method === 'HEAD' || status === 204 || status === 205 || status === 304;
+}
+export function snapshotInlineBody(value, maxBytes, subject) {
+    let serialized;
+    try {
+        serialized = JSON.stringify(value);
+    }
+    catch (cause) {
+        throw new HttpOverMicroError(subject === 'request' ? 'INVALID_REQUEST' : 'INVALID_RESPONSE', subject === 'request' ? 400 : 500, `${subject === 'request' ? 'Request' : 'Response'} inline body must be JSON-serializable`, { cause });
+    }
+    if (serialized === undefined) {
+        throw new HttpOverMicroError(subject === 'request' ? 'INVALID_REQUEST' : 'INVALID_RESPONSE', subject === 'request' ? 400 : 500, `${subject === 'request' ? 'Request' : 'Response'} inline body must be JSON-serializable`);
+    }
+    const bytes = Buffer.byteLength(serialized);
+    if (bytes > maxBytes) {
+        throw new HttpOverMicroError(subject === 'request' ? 'INVALID_REQUEST' : 'INVALID_RESPONSE', subject === 'request' ? 413 : 500, `${subject === 'request' ? 'Request' : 'Response'} inline body exceeds ${maxBytes} bytes`);
+    }
+    return JSON.parse(serialized);
+}

package/dist/server.d.ts

@@ -0,0 +1,41 @@
+import { Readable } from 'node:stream';
+import { type MessageInput } from '@hile/message-modem';
+import { type Client, type MicroMessageHandlerExtras, type MicroMessageMetadata } from '@hile/micro';
+import type { MessageRegisterProps } from '@hile/message-loader';
+import type { z } from 'zod';
+import { type HttpFieldInput, type HttpFieldValues } from './fields.js';
+import { type HttpOverMicroRequestEnvelope, type HttpOverMicroLimits } from './protocol.js';
+export interface HttpOverMicroSchemas {
+    headers?: z.ZodType;
+    query?: z.ZodType;
+    params?: z.ZodType;
+    body?: z.ZodType;
+}
+type SchemaOutput<TSchema, TFallback> = TSchema extends z.ZodType ? z.output<TSchema> : TFallback;
+export interface HttpOverMicroMessageConfig<TSchemas extends HttpOverMicroSchemas = HttpOverMicroSchemas> {
+    method: string | readonly string[];
+    schema?: TSchemas;
+    limits?: HttpOverMicroLimits;
+}
+export interface HttpOverMicroHandlerResponse<TBody = unknown> {
+    status?: number;
+    headers?: HttpFieldInput;
+    body?: TBody | MessageInput;
+}
+export interface HttpOverMicroHandlerContext<TSchemas extends HttpOverMicroSchemas = HttpOverMicroSchemas> {
+    request: {
+        method: string;
+        headers: SchemaOutput<TSchemas['headers'], HttpFieldValues>;
+        query: SchemaOutput<TSchemas['query'], HttpFieldValues>;
+        body: SchemaOutput<TSchemas['body'], unknown | Readable | undefined>;
+    };
+    params: SchemaOutput<TSchemas['params'], Record<string, string>>;
+    url: string;
+    client: Client;
+    metadata?: MicroMessageMetadata;
+    signal?: AbortSignal;
+    invocation: MicroMessageHandlerExtras['invocation'];
+}
+export type HttpOverMicroHandler<TSchemas extends HttpOverMicroSchemas = HttpOverMicroSchemas> = (context: HttpOverMicroHandlerContext<TSchemas>) => HttpOverMicroHandlerResponse | Promise<HttpOverMicroHandlerResponse>;
+export declare function defineHttpOverMicroMessage<const TSchemas extends HttpOverMicroSchemas = HttpOverMicroSchemas>(config: HttpOverMicroMessageConfig<TSchemas>, handler: HttpOverMicroHandler<TSchemas>): MessageRegisterProps<HttpOverMicroRequestEnvelope, MicroMessageHandlerExtras>;
+export {};

package/dist/server.js

@@ -0,0 +1,163 @@
+import { isMessageInput } from '@hile/message-modem';
+import { defineMicroMessage, } from '@hile/micro';
+import { HttpOverMicroError } from './errors.js';
+import { httpFieldsToRecord, normalizeHttpHeaders, } from './fields.js';
+import { HTTP_OVER_MICRO_PROTOCOL, HTTP_OVER_MICRO_VERSION, httpOverMicroRequestEnvelopeSchema, httpOverMicroResponseHeadSchema, httpResponseMustBeEmpty, normalizeHttpMethod, resolveInlineBodyLimit, snapshotInlineBody, } from './protocol.js';
+function invalidRequest(message, cause) {
+    return new HttpOverMicroError('INVALID_REQUEST', 400, message, { cause });
+}
+function invalidResponse(message, cause) {
+    return new HttpOverMicroError('INVALID_RESPONSE', 500, message, { cause });
+}
+async function parseWithSchema(schema, value, field) {
+    if (!schema)
+        return value;
+    const parsed = await schema.safeParseAsync(value);
+    if (!parsed.success)
+        throw invalidRequest(`Invalid HTTP request ${field}`, parsed.error);
+    return parsed.data;
+}
+function normalizeAllowedMethods(method) {
+    try {
+        let source;
+        if (typeof method === 'string')
+            source = [method];
+        else if (Array.isArray(method))
+            source = method;
+        else
+            throw new TypeError('method must be a string or string array');
+        if (source.length === 0)
+            throw new TypeError('At least one HTTP method is required');
+        return Object.freeze([...new Set(source.map(normalizeHttpMethod))]);
+    }
+    catch (cause) {
+        throw new HttpOverMicroError('INVALID_DEFINITION', 500, 'HTTP-over-Micro methods are invalid', { cause });
+    }
+}
+function validateSchemas(schemas) {
+    if (schemas === undefined)
+        return;
+    if (!schemas || typeof schemas !== 'object' || Array.isArray(schemas)) {
+        throw new HttpOverMicroError('INVALID_DEFINITION', 500, 'HTTP-over-Micro schema must be an object');
+    }
+    for (const field of ['headers', 'query', 'params', 'body']) {
+        const schema = schemas[field];
+        if (schema !== undefined && typeof schema.safeParseAsync !== 'function') {
+            throw new HttpOverMicroError('INVALID_DEFINITION', 500, `HTTP-over-Micro ${field} schema must be a Zod schema`);
+        }
+    }
+}
+async function* iterateBody(body) {
+    if (body instanceof ArrayBuffer) {
+        yield new Uint8Array(body);
+        return;
+    }
+    if (body instanceof Uint8Array) {
+        yield body;
+        return;
+    }
+    for await (const chunk of body) {
+        if (chunk === null || chunk === undefined)
+            throw invalidResponse('HTTP response stream emitted an empty chunk');
+        yield chunk;
+    }
+}
+function createHead(status, headers, body) {
+    let candidate;
+    try {
+        candidate = {
+            protocol: HTTP_OVER_MICRO_PROTOCOL,
+            version: HTTP_OVER_MICRO_VERSION,
+            type: 'response',
+            status,
+            headers: normalizeHttpHeaders(headers),
+            body,
+        };
+    }
+    catch (cause) {
+        throw invalidResponse('Invalid HTTP response headers', cause);
+    }
+    const parsed = httpOverMicroResponseHeadSchema.safeParse(candidate);
+    if (!parsed.success)
+        throw invalidResponse('Invalid HTTP response metadata', parsed.error);
+    return parsed.data;
+}
+export function defineHttpOverMicroMessage(config, handler) {
+    if (!config || typeof config !== 'object') {
+        throw new HttpOverMicroError('INVALID_DEFINITION', 500, 'HTTP-over-Micro config is required');
+    }
+    if (typeof handler !== 'function') {
+        throw new HttpOverMicroError('INVALID_DEFINITION', 500, 'HTTP-over-Micro handler is required');
+    }
+    const methods = normalizeAllowedMethods(config.method);
+    const methodSet = new Set(methods);
+    let maxInlineBodyBytes;
+    try {
+        maxInlineBodyBytes = resolveInlineBodyLimit(config.limits?.maxInlineBodyBytes);
+    }
+    catch (cause) {
+        throw new HttpOverMicroError('INVALID_DEFINITION', 500, 'HTTP-over-Micro limits are invalid', { cause });
+    }
+    const schemas = config.schema;
+    validateSchemas(schemas);
+    return defineMicroMessage(async function* ({ data, input, params, url, client, metadata, signal, invocation, }) {
+        const parsedEnvelope = httpOverMicroRequestEnvelopeSchema.safeParse(data);
+        if (!parsedEnvelope.success) {
+            throw invalidRequest('Invalid HTTP-over-Micro request envelope', parsedEnvelope.error);
+        }
+        const envelope = parsedEnvelope.data;
+        if (!methodSet.has(envelope.method)) {
+            yield createHead(405, { allow: methods.join(', ') }, { kind: 'empty' });
+            return;
+        }
+        let body;
+        if (envelope.body.kind === 'stream') {
+            if (!input)
+                throw invalidRequest('HTTP request declares a stream body but no Micro input was received');
+            body = input;
+        }
+        else {
+            if (input)
+                throw invalidRequest('HTTP request sent Micro input without declaring a stream body');
+            body = envelope.body.kind === 'inline' ? envelope.body.value : undefined;
+        }
+        const request = {
+            method: envelope.method,
+            headers: await parseWithSchema(schemas?.headers, httpFieldsToRecord(envelope.headers), 'headers'),
+            query: await parseWithSchema(schemas?.query, httpFieldsToRecord(envelope.query), 'query'),
+            body: await parseWithSchema(schemas?.body, body, 'body'),
+        };
+        const parsedParams = (await parseWithSchema(schemas?.params, params ?? {}, 'params'));
+        const response = await handler({
+            request,
+            params: parsedParams,
+            url,
+            client,
+            metadata,
+            signal,
+            invocation,
+        });
+        if (!response || typeof response !== 'object' || Array.isArray(response)) {
+            throw invalidResponse('HTTP-over-Micro handler must return a response object');
+        }
+        const status = response.status ?? 200;
+        if (!Number.isInteger(status) || status < 200 || status > 599) {
+            throw invalidResponse('HTTP response status must be an integer from 200 through 599');
+        }
+        const responseBody = response.body;
+        if (responseBody !== undefined && httpResponseMustBeEmpty(envelope.method, status)) {
+            throw invalidResponse(`HTTP ${envelope.method} response with status ${status} must not include a body`);
+        }
+        if (responseBody === undefined) {
+            yield createHead(status, response.headers, { kind: 'empty' });
+            return;
+        }
+        if (isMessageInput(responseBody)) {
+            yield createHead(status, response.headers, { kind: 'stream' });
+            yield* iterateBody(responseBody);
+            return;
+        }
+        const inlineBody = snapshotInlineBody(responseBody, maxInlineBodyBytes, 'response');
+        yield createHead(status, response.headers, { kind: 'inline', value: inlineBody });
+    });
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@hile/http-over-micro",
+  "description": "Preserve HTTP semantics across Hile Micro calls with validated metadata and bidirectional streaming",
+  "version": "1.0.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -b && fix-esm-import-path --preserve-import-type ./dist",
+    "dev": "tsc -b --watch",
+    "test": "vitest run"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "README.md",
+    "AI.md"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@hile/message-loader": "^4.0.5",
+    "@hile/message-modem": "^4.0.4",
+    "@hile/micro": "^4.0.5",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@hile/context": "^4.0.3",
+    "@types/node": "^26.2.0",
+    "fix-esm-import-path": "^1.10.3",
+    "vitest": "^4.0.18"
+  },
+  "gitHead": "c57b2c5a3c017ae56d4a862a089b2af01368c3ba"
+}