@vyriy/handler 0.7.7 → 0.7.8

package/README.md

@@ -4,7 +4,7 @@ Composable AWS Lambda handler chains and wrappers for Vyriy projects.
 
 ## Purpose
 
-This package provides ready-made Lambda handler chains for common Vyriy workloads and a small set of reusable wrappers for logging, timeouts, smoke checks, development chaos injection, context setup, and error handling.
+This package provides ready-made Lambda handler chains for common Vyriy workloads and a small set of reusable wrappers for logging, timeouts, smoke checks, development chaos injection, context setup, and error handling. It also ships a native Node HTTP chain (`httpApi`) with matching `httpWith*` wrappers for handlers that work directly with `IncomingMessage` and `ServerResponse`.
 
 It is designed for projects that want a consistent handler pipeline without repeating the same boilerplate in every Lambda entrypoint.
 
@@ -98,6 +98,30 @@ export const main = awslambda.streamifyResponse(
 );
 ```
 
+For native Node HTTP handlers, use the HTTP chain. Handlers receive `(request, response)` and own the response lifecycle, which fits transports such as MCP Streamable HTTP:
+
+```ts
+import { httpApi } from '@vyriy/handler';
+
+export const handler = httpApi(async (request, response) => {
+  response
+    .writeHead(200, {
+      'content-type': 'application/json',
+    })
+    .end(JSON.stringify({ ok: true, url: request.url }));
+});
+```
+
+Run it locally or in a container with `httpServer` from `@vyriy/server`:
+
+```ts
+import { httpServer } from '@vyriy/server';
+
+import { handler } from './handler.js';
+
+httpServer(handler);
+```
+
 Use a prebuilt queue or event handler chain:
 
 ```ts
@@ -178,6 +202,8 @@ export const handler = eventBridge(async (event) => {
 });
 ```
 
+Each chain has its own composition and factory helpers: `compose`/`factory` for Lambda handlers, `streamCompose`/`streamFactory` for response streaming handlers, and `httpCompose`/`httpFactory` for native Node HTTP handlers.
+
 Compose a custom handler pipeline from individual helpers:
 
 ```ts
@@ -232,6 +258,25 @@ export const handler = compose(
 });
 ```
 
+Compose a custom native HTTP pipeline with `httpCompose(...)` and the `httpWith*` wrappers:
+
+```ts
+import { httpCompose, httpWithCors, httpWithError, httpWithHealthcheck, httpWithLogger } from '@vyriy/handler';
+
+export const handler = httpCompose(
+  httpWithError(),
+  httpWithLogger(),
+  httpWithHealthcheck(),
+  httpWithCors(),
+)(async (request, response) => {
+  response
+    .writeHead(200, {
+      'content-type': 'application/json',
+    })
+    .end(JSON.stringify({ ok: true }));
+});
+```
+
 ## Prebuilt Chains
 
 - `api`
@@ -239,6 +284,9 @@ export const handler = compose(
 - `streamApi`
   Response streaming API Gateway chain with the same wrapper behavior as `api`. Handlers receive `(event, responseStream, context)` and write directly to the Lambda response stream.
 
+- `httpApi`
+  Native Node HTTP chain with error handling, logging, healthcheck handling, default headers, and CORS preflight handling. Handlers receive `(request, response)` and write the response themselves. Unlike `api`, the chain sets no default `content-type` because native handlers own the response body format.
+
 - `dynamodb`
   DynamoDB Streams chain with logging, timeout handling, context setup, smoke checks, and rethrown errors.
 
@@ -424,17 +472,62 @@ export const handler = withSmoke()(async () => {
 
 `withSmoke()` is used by the API, DynamoDB Streams, S3, SES receipt, schedule, SNS, and SQS chains.
 
+### Native HTTP Wrappers
+
+The `httpWith*` wrappers decorate native Node HTTP handlers and are composed with `httpCompose(...)`:
+
+- `httpWithError(options?)`
+  Catches handler failures and runs an optional side-effect `errorHandler`. When the response is still open it writes a JSON `500`; when headers were already sent it only ends the response.
+
+- `httpWithLogger(options?)`
+  Logs the incoming request method and URL, then logs either the response status code or the thrown error. Accepts the same `logger` option as `withLogger`.
+
+- `httpWithHealthcheck(options?)`
+  Writes a JSON `200` response when the request path matches the configured `path` (default `/healthcheck`). Besides `path` and `action`, it accepts an optional JSON-serializable `body` for the healthcheck response.
+
+- `httpWithHeaders(options?)`
+  Sets configured headers on the response before delegating, so handler-defined headers win on key conflicts.
+
+- `httpWithCors()`
+  Short-circuits `OPTIONS` preflight requests with a `204` response and delegates all other requests.
+
+Custom native HTTP wrappers are created with `httpFactory(...)`:
+
+```ts
+import { httpCompose, httpFactory, httpWithError } from '@vyriy/handler';
+
+const httpWithRequestId = httpFactory<{ headerName?: string }>(async (handler, args, options = {}) => {
+  const [request] = args;
+  const requestId = request.headers[options.headerName ?? 'x-request-id'];
+
+  if (requestId) {
+    console.info('Request ID:', requestId);
+  }
+
+  await handler(...args);
+});
+
+export const handler = httpCompose(
+  httpWithError(),
+  httpWithRequestId(),
+)(async (request, response) => {
+  response.writeHead(200).end('ok');
+});
+```
+
 ## Types
 
 The package also exports shared handler types:
 
 ```ts
 import type { Context, Decorator, Handler, HandlerParams, Response } from '@vyriy/handler';
+import type { HttpDecorator, HttpHandler, HttpHandlerParams } from '@vyriy/handler';
 ```
 
 ## Notes
 
 - `api` includes API-specific wrappers such as healthcheck handling, default headers, and CORS preflight handling
+- `httpApi` skips timeout, context, smoke, and chaos wrappers because they rely on the Lambda context and event shape; it also sets no default `content-type`
 - `dynamodb`, `s3`, `ses`, `schedule`, `sns`, and `sqs` use `withError()` so failures are rethrown for event-source retry behavior
 - `ses` targets SES receipt rule Lambda events for incoming email; SES event publishing notifications can still be handled through the `sns` chain when delivered via SNS
 - `withSmoke()` delegates matching to `@vyriy/smoke` and returns its API Gateway-compatible response

package/api.d.ts

@@ -1,2 +1,3 @@
 export declare const api: import("./types.js").Decorator<import("aws-lambda").APIGatewayProxyEvent, import("aws-lambda").APIGatewayProxyResult>;
 export declare const streamApi: import("./types.js").StreamDecorator<import("aws-lambda").APIGatewayProxyEvent>;
+export declare const httpApi: import("./types.js").HttpDecorator;

package/api.js

@@ -1,12 +1,12 @@
-import { compose, streamCompose } from './compose.js';
-import { streamWithApiError, withApiError } from './wrapper/error.js';
-import { streamWithLogger, withLogger } from './wrapper/logger.js';
+import { compose, httpCompose, streamCompose } from './compose.js';
+import { httpWithError, streamWithApiError, withApiError } from './wrapper/error.js';
+import { httpWithLogger, streamWithLogger, withLogger } from './wrapper/logger.js';
 import { streamWithTimeout, withTimeout } from './wrapper/timeout.js';
 import { streamWithContext, withContext } from './wrapper/context.js';
 import { streamWithSmoke, withSmoke } from './wrapper/smoke.js';
-import { streamWithHealthcheck, withHealthcheck } from './wrapper/healthcheck.js';
-import { streamWithHeaders, withHeaders } from './wrapper/headers.js';
-import { streamWithCors, withCors } from './wrapper/cors.js';
+import { httpWithHealthcheck, streamWithHealthcheck, withHealthcheck } from './wrapper/healthcheck.js';
+import { httpWithHeaders, streamWithHeaders, withHeaders } from './wrapper/headers.js';
+import { httpWithCors, streamWithCors, withCors } from './wrapper/cors.js';
 import { streamWithChaos, withChaos } from './wrapper/chaos.js';
 export const api = compose(withApiError(), withLogger(), withTimeout(), withContext(), withSmoke(), withHealthcheck(), withHeaders({
     'access-control-allow-origin': '*',
@@ -22,3 +22,9 @@ export const streamApi = streamCompose(streamWithApiError(), streamWithLogger(),
     'content-type': 'application/json',
     'x-robots-tag': 'noindex, nofollow',
 }), streamWithCors(), streamWithChaos());
+export const httpApi = httpCompose(httpWithError(), httpWithLogger(), httpWithHealthcheck(), httpWithHeaders({
+    'access-control-allow-origin': '*',
+    'access-control-allow-methods': 'GET, POST, PUT, PATCH, DELETE, OPTIONS',
+    'access-control-allow-headers': 'Content-Type, Authorization, X-Requested-With, X-Api-Key, Accept, User-Agent, X-CSRF-Token',
+    'x-robots-tag': 'noindex, nofollow',
+}), httpWithCors());

package/compose.d.ts

@@ -1,3 +1,4 @@
-import type { Compose, StreamCompose } from './types.js';
+import type { Compose, HttpCompose, StreamCompose } from './types.js';
 export declare const compose: Compose;
 export declare const streamCompose: StreamCompose;
+export declare const httpCompose: HttpCompose;

package/compose.js

@@ -1,2 +1,3 @@
 export const compose = (...fns) => fns.reduceRight((prevDecorator, nextDecorator) => (handler) => nextDecorator(prevDecorator(handler)));
 export const streamCompose = (...fns) => fns.reduceRight((prevDecorator, nextDecorator) => (handler) => nextDecorator(prevDecorator(handler)));
+export const httpCompose = (...fns) => fns.reduceRight((prevDecorator, nextDecorator) => (handler) => nextDecorator(prevDecorator(handler)));

package/factory.d.ts

@@ -1,7 +1,8 @@
 import type { Context } from 'aws-lambda';
-import type { Factory, HandlerParams, ResponseStream, StreamFactory, StreamHandlerParams } from './types.js';
+import type { Factory, HandlerParams, HttpFactory, ResponseStream, StreamFactory, StreamHandlerParams } from './types.js';
 export declare const getContext: <Event>(args: HandlerParams<Event>) => Context;
 export declare const getResponseStream: <Event>(args: StreamHandlerParams<Event>) => ResponseStream;
 export declare const getStreamContext: <Event>(args: StreamHandlerParams<Event>) => Context;
 export declare const factory: Factory;
 export declare const streamFactory: StreamFactory;
+export declare const httpFactory: HttpFactory;

package/factory.js

@@ -3,3 +3,4 @@ export const getResponseStream = (args) => args[1];
 export const getStreamContext = (args) => args[2];
 export const factory = (wrapper) => (options) => (handler) => async (event, context) => wrapper(handler, [event, context], options);
 export const streamFactory = (wrapper) => (options) => (handler) => async (event, responseStream, context) => wrapper(handler, [event, responseStream, context], options);
+export const httpFactory = (wrapper) => (options) => (handler) => async (request, response) => wrapper(handler, [request, response], options);

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@vyriy/handler",
-  "version": "0.7.7",
+  "version": "0.7.8",
   "description": "Composable AWS Lambda handler chains and wrappers for Vyriy projects",
   "type": "module",
   "dependencies": {
     "@types/aws-lambda": "^8.10.162",
-    "@vyriy/chaos": "0.7.7",
-    "@vyriy/config": "0.7.7",
-    "@vyriy/logger": "0.7.7",
-    "@vyriy/smoke": "0.7.7",
-    "@vyriy/timeout": "0.7.7"
+    "@vyriy/chaos": "0.7.8",
+    "@vyriy/config": "0.7.8",
+    "@vyriy/logger": "0.7.8",
+    "@vyriy/smoke": "0.7.8",
+    "@vyriy/timeout": "0.7.8"
   },
   "agents": "./AGENTS.md",
   "license": "MIT",

package/types.d.ts

@@ -1,4 +1,5 @@
 import type { APIGatewayProxyEvent, APIGatewayProxyResult, Context } from 'aws-lambda';
+import type { IncomingMessage, ServerResponse } from 'node:http';
 export type { Context } from 'aws-lambda';
 export type ResponseStream = {
     end: {
@@ -16,12 +17,17 @@ export type StreamHandlerParams<Event> = [event: Event, responseStream: Response
 export type Response<Result> = Promise<Result>;
 export type Handler<Event, Result> = (event: Event, context: Context) => Response<Result>;
 export type StreamHandler<Event> = (event: Event, responseStream: ResponseStream, context: Context) => Response<void>;
+export type HttpHandler = (request: IncomingMessage, response: ServerResponse) => Promise<void> | void;
+export type HttpHandlerParams = [request: IncomingMessage, response: ServerResponse];
 export type Decorator<Event, Result> = (handler: Handler<Event, Result>) => Handler<Event, Result>;
 export type StreamDecorator<Event> = (handler: StreamHandler<Event>) => StreamHandler<Event>;
+export type HttpDecorator = (handler: HttpHandler) => HttpHandler;
 export type Compose = <Event, Result>(...decorators: Array<Decorator<Event, Result>>) => Decorator<Event, Result>;
 export type StreamCompose = <Event>(...decorators: Array<StreamDecorator<Event>>) => StreamDecorator<Event>;
+export type HttpCompose = (...decorators: Array<HttpDecorator>) => HttpDecorator;
 export type Wrapper<Options> = <Event, Result>(handler: Handler<Event, Result>, args: HandlerParams<Event>, options?: Options) => Response<Result>;
 export type StreamWrapper<Options> = <Event>(handler: StreamHandler<Event>, args: StreamHandlerParams<Event>, options?: Options) => Response<void>;
+export type HttpWrapper<Options> = (handler: HttpHandler, args: HttpHandlerParams, options?: Options) => Response<void>;
 export type TypedWrapper<Event, Result, Options> = (handler: Handler<Event, Result>, args: HandlerParams<Event>, options?: Options) => Response<Result>;
 export type StreamTypedWrapper<Event, Options> = (handler: StreamHandler<Event>, args: StreamHandlerParams<Event>, options?: Options) => Response<void>;
 export type Factory = {
@@ -32,3 +38,4 @@ export type StreamFactory = {
     <Options = undefined>(wrapper: StreamWrapper<Options>): <Event>(options?: Options) => StreamDecorator<Event>;
     <Options, Event>(wrapper: StreamTypedWrapper<Event, Options>): (options?: Options) => StreamDecorator<Event>;
 };
+export type HttpFactory = <Options = undefined>(wrapper: HttpWrapper<Options>) => (options?: Options) => HttpDecorator;

package/wrapper/cors.d.ts

@@ -1,2 +1,3 @@
 export declare const withCors: (options?: unknown) => import("../types.js").Decorator<import("aws-lambda").APIGatewayProxyEvent, import("aws-lambda").APIGatewayProxyResult>;
 export declare const streamWithCors: (options?: unknown) => import("../types.js").StreamDecorator<import("aws-lambda").APIGatewayProxyEvent>;
+export declare const httpWithCors: (options?: undefined) => import("../types.js").HttpDecorator;

package/wrapper/cors.js

@@ -1,4 +1,4 @@
-import { factory, streamFactory } from '../factory.js';
+import { factory, httpFactory, streamFactory } from '../factory.js';
 import { responseStream } from './stream.js';
 export const withCors = factory(async (handler, args) => {
     const [request] = args;
@@ -18,3 +18,11 @@ export const streamWithCors = streamFactory(async (handler, args) => {
     }
     await handler(...args);
 });
+export const httpWithCors = httpFactory(async (handler, args) => {
+    const [request, response] = args;
+    if (request.method === 'OPTIONS') {
+        response.writeHead(204).end();
+        return;
+    }
+    await handler(...args);
+});

package/wrapper/error.d.ts

@@ -1,4 +1,4 @@
-import type { ApiEvent, ApiResult, Decorator, HandlerParams, StreamDecorator, StreamHandlerParams } from '../types.js';
+import type { ApiEvent, ApiResult, Decorator, HandlerParams, HttpDecorator, HttpHandlerParams, StreamDecorator, StreamHandlerParams } from '../types.js';
 export type ErrorHandler<Params extends unknown[]> = (err: unknown, args: Params) => Promise<void> | void;
 export type ApiErrorHandler<Params extends unknown[], Result> = (err: unknown, args: Params) => Promise<Result> | Result;
 export type ErrorOptions<Params extends unknown[]> = {
@@ -10,3 +10,4 @@ export type ApiErrorOptions<Params extends unknown[], Result> = {
 export declare const withError: <Event, Result>(options?: ErrorOptions<HandlerParams<Event>>) => Decorator<Event, Result>;
 export declare const withApiError: (options?: ApiErrorOptions<HandlerParams<ApiEvent>, ApiResult>) => Decorator<ApiEvent, ApiResult>;
 export declare const streamWithApiError: (options?: ApiErrorOptions<StreamHandlerParams<ApiEvent>, ApiResult | void>) => StreamDecorator<ApiEvent>;
+export declare const httpWithError: (options?: ErrorOptions<HttpHandlerParams>) => HttpDecorator;

package/wrapper/error.js

@@ -40,3 +40,23 @@ export const streamWithApiError = (options = {}) => (handler) => async (event, s
         }
     }
 };
+export const httpWithError = (options = {}) => (handler) => async (request, response) => {
+    try {
+        await handler(request, response);
+    }
+    catch (err) {
+        await options.errorHandler?.(err, [request, response]);
+        if (response.writableEnded) {
+            return;
+        }
+        if (response.headersSent) {
+            response.end();
+            return;
+        }
+        response
+            .writeHead(500, {
+            'content-type': 'application/json',
+        })
+            .end(JSON.stringify({ message: STATUS_CODES[500] }));
+    }
+};

package/wrapper/headers.d.ts

@@ -1,2 +1,3 @@
 export declare const withHeaders: (options?: Record<string, string> | undefined) => import("../types.js").Decorator<import("aws-lambda").APIGatewayProxyEvent, import("aws-lambda").APIGatewayProxyResult>;
 export declare const streamWithHeaders: (options?: Record<string, string> | undefined) => import("../types.js").StreamDecorator<import("aws-lambda").APIGatewayProxyEvent>;
+export declare const httpWithHeaders: (options?: Record<string, string> | undefined) => import("../types.js").HttpDecorator;

package/wrapper/headers.js

@@ -1,4 +1,4 @@
-import { factory, streamFactory } from '../factory.js';
+import { factory, httpFactory, streamFactory } from '../factory.js';
 import { responseStream } from './stream.js';
 const normalizeHeaders = (headers) => Object.fromEntries(Object.entries(headers ?? {}).map(([key, value]) => [key.toLowerCase(), value]));
 const mergeHeaders = (result, options) => {
@@ -16,3 +16,10 @@ export const streamWithHeaders = streamFactory(async (handler, args, options = {
     const [event, stream, context] = args;
     await handler(event, responseStream(stream, { headers: normalizeHeaders(options) }), context);
 });
+export const httpWithHeaders = httpFactory(async (handler, args, options = {}) => {
+    const [request, response] = args;
+    for (const [name, value] of Object.entries(options)) {
+        response.setHeader(name.toLowerCase(), value);
+    }
+    await handler(request, response);
+});

package/wrapper/healthcheck.d.ts

@@ -2,8 +2,12 @@ export type HealthcheckOptions = {
     path?: string;
     action?: () => Promise<void>;
 };
+export type HttpHealthcheckOptions = HealthcheckOptions & {
+    body?: unknown;
+};
 export declare const withHealthcheck: (options?: HealthcheckOptions | undefined) => import("../types.js").Decorator<import("aws-lambda").APIGatewayProxyEvent, import("aws-lambda").APIGatewayProxyResult | {
     statusCode: number;
     body: string;
 }>;
 export declare const streamWithHealthcheck: (options?: HealthcheckOptions | undefined) => import("../types.js").StreamDecorator<import("aws-lambda").APIGatewayProxyEvent>;
+export declare const httpWithHealthcheck: (options?: HttpHealthcheckOptions | undefined) => import("../types.js").HttpDecorator;

package/wrapper/healthcheck.js

@@ -1,5 +1,5 @@
 import { STATUS_CODES } from 'node:http';
-import { factory, streamFactory } from '../factory.js';
+import { factory, httpFactory, streamFactory } from '../factory.js';
 import { responseStream } from './stream.js';
 const getHealthcheckResult = async (event, options = {}) => {
     const { path = '/healthcheck', action } = options;
@@ -30,3 +30,20 @@ export const streamWithHealthcheck = streamFactory(async (handler, args, options
     }
     await handler(...args);
 });
+export const httpWithHealthcheck = httpFactory(async (handler, args, options = {}) => {
+    const { path = '/healthcheck', action, body } = options;
+    const [request, response] = args;
+    const pathname = (request.url ?? '').split('?')[0];
+    if (pathname !== path) {
+        await handler(...args);
+        return;
+    }
+    if (action) {
+        await action();
+    }
+    response
+        .writeHead(200, {
+        'content-type': 'application/json',
+    })
+        .end(JSON.stringify(body ?? { message: STATUS_CODES[200] }));
+});

package/wrapper/logger.d.ts

@@ -3,3 +3,4 @@ export type LoggerOptions = {
 };
 export declare const withLogger: <Event, Result>(options?: LoggerOptions | undefined) => import("../types.js").Decorator<Event, Result>;
 export declare const streamWithLogger: <Event>(options?: LoggerOptions | undefined) => import("../types.js").StreamDecorator<Event>;
+export declare const httpWithLogger: (options?: LoggerOptions | undefined) => import("../types.js").HttpDecorator;

package/wrapper/logger.js

@@ -1,5 +1,5 @@
 import { createLogger } from '@vyriy/logger';
-import { factory, getContext, getStreamContext, streamFactory } from '../factory.js';
+import { factory, getContext, getStreamContext, httpFactory, streamFactory } from '../factory.js';
 export const withLogger = factory(async (handler, args, options = {}) => {
     const { logger = createLogger() } = options;
     const [event] = args;
@@ -37,3 +37,29 @@ export const streamWithLogger = streamFactory(async (handler, args, options = {}
         throw error;
     }
 });
+export const httpWithLogger = httpFactory(async (handler, args, options = {}) => {
+    const { logger = createLogger() } = options;
+    const [request, response] = args;
+    logger.info('Request:', request.method, request.url);
+    const cleanup = () => {
+        response.off('close', logResult);
+        response.off('finish', logResult);
+    };
+    const logResult = () => {
+        cleanup();
+        logger.info('Result:', response.statusCode);
+    };
+    response.once('close', logResult);
+    response.once('finish', logResult);
+    try {
+        await handler(...args);
+    }
+    catch (error) {
+        cleanup();
+        if (error instanceof Error) {
+            logger.error('Error:', error.message);
+        }
+        logger.error(error);
+        throw error;
+    }
+});