@vyriy/server 0.2.0 → 0.3.0

package/AGENTS.md

@@ -0,0 +1,65 @@
+# Vyriy Package Agent Guide
+
+This package belongs to the Vyriy toolkit. Keep changes calm, explicit, reusable, and easy to reason about.
+
+## Architecture
+
+- Prefer simple modules over clever frameworks or hidden conventions.
+- Keep package boundaries explicit and avoid project-specific coupling.
+- Extract only proven reusable behavior.
+- Keep public APIs small, typed, documented, and stable.
+- Prefer SSR-friendly and SSG-friendly code paths.
+- Keep integrations replaceable and avoid hard coupling to a CMS or runtime host.
+- Prefer AWS serverless-compatible assumptions when infrastructure concerns appear.
+
+## File Shape
+
+- Prefer one exported runtime method, component, or helper per production file when it stays readable.
+- Prefer one matching test file per production file, for example `feature.ts` and `feature.test.ts`.
+- Use focused folders when behavior naturally splits into several related files.
+- Keep `index.ts` as a public re-export surface only. Do not place implementation logic in it.
+- Use `.js` relative import and export specifiers in TypeScript source where package style requires it.
+- Add `types.ts` when public shared types are part of the package contract.
+- Keep constants near the code that owns them unless they are shared or clarify repeated behavior.
+
+## Public Surface
+
+- Every new public export should be re-exported from `index.ts`.
+- Add or update `index.test.ts` when the public export surface changes.
+- Add JSDoc for public exports when behavior, parameters, return values, or usage expectations need explanation.
+- Do not hand-maintain source package `exports` maps unless the package has a real custom publishing need.
+
+## Tests
+
+- Tests use Jest and `@jest/globals`.
+- Cover public behavior and meaningful edge cases.
+- Prefer behavior-focused tests over private implementation lock-in.
+- When mocking modules, install mocks before loading the module under test.
+- Use focused validation when changing package behavior:
+
+```bash
+yarn jest packages/<package> --runInBand --coverage=false
+```
+
+## Documentation
+
+- Keep `README.md` concise and usage-oriented.
+- Start package READMEs with `# @vyriy/<package>`.
+- Document real public exports, supported options, and examples that actually work.
+- Keep `doc.mdx` as the Storybook/docs wrapper for the README when the package participates in docs.
+- For component packages, include Storybook coverage for supported states and common usage.
+
+## Components
+
+- Prefer lightweight React 19+ components with TypeScript.
+- Keep components SSR-friendly and avoid browser globals during render.
+- Prefer composable props and Bootstrap-compatible ergonomics where practical.
+- Put each public component in its own file with a matching test.
+- Add Storybook stories when a component has visual states, variants, or interaction states.
+
+## Change Discipline
+
+- Keep changes scoped to the requested behavior.
+- Avoid unrelated refactors and metadata churn.
+- Sync implementation, tests, README, `doc.mdx`, and public re-exports together.
+- Prefer the option that is simpler to explain, easier to evolve, and calmer to maintain.

package/README.md

@@ -32,4 +32,58 @@ server(async () => ({
 }));
 ```
 
+Run a Lambda response streaming handler locally:
+
+```ts
+import { api, streamify } from '@vyriy/handler';
+import { server } from '@vyriy/server';
+
+server(
+  streamify(
+    api(async (event, responseStream) => {
+      responseStream.setContentType?.('text/plain');
+      responseStream.write(`Path: ${event.path}\n`);
+      responseStream.end('Done');
+    }),
+  ),
+);
+```
+
+Keep the AWS-specific `awslambda.streamifyResponse(handler)` wrapper in a separate Lambda entrypoint.
+
+Serve static files through `@vyriy/router` prefix routes:
+
+```ts
+import { createRouter } from '@vyriy/router';
+import { staticFiles } from '@vyriy/server/static';
+
+const router = createRouter().prefix('/static', staticFiles('./public'));
+```
+
+Serve a static directory directly when the server only needs files:
+
+```ts
+import { server, staticFiles } from '@vyriy/server';
+
+server(
+  staticFiles('./public', {
+    fallback: 'index.html',
+    fallbackStatusCode: 200,
+  }),
+);
+```
+
+By default, missing static files fall back to `404.html` from the same directory with status `404` when that file exists.
+For static apps that should fall back to `index.html`, configure the fallback explicitly:
+
+```ts
+const router = createRouter().prefix(
+  '/static',
+  staticFiles('./public', {
+    fallback: 'index.html',
+    fallbackStatusCode: 200,
+  }),
+);
+```
+
 The server listens on `PORT` from `@vyriy/env`. The default port is `3000`.

package/index.d.ts

@@ -1,2 +1,3 @@
 export { server } from './server.js';
+export { staticFiles } from './static.js';
 export type * from './types.js';

package/index.js

@@ -1 +1,2 @@
 export { server } from './server.js';
+export { staticFiles } from './static.js';

package/listener.d.ts

@@ -1,2 +1,2 @@
-import type { LambdaHandler, NativeRequestListener } from './types.js';
-export declare const listener: (handler: LambdaHandler) => NativeRequestListener;
+import type { NativeRequestListener, ServerHandler } from './types.js';
+export declare const listener: (handler: ServerHandler) => NativeRequestListener;

package/listener.js

@@ -1,10 +1,19 @@
 import { mapParams } from './params.js';
 import { error, result } from './result.js';
+const isStreamHandler = (handler) => handler.length >= 3;
+const createResponseStream = (response) => {
+    response.setContentType = (contentType) => response.setHeader?.('content-type', contentType) ?? response;
+    return response;
+};
 export const listener = (handler) => async (request, response) => {
     try {
         const { context, event } = await mapParams(request);
+        if (isStreamHandler(handler)) {
+            await handler(event, createResponseStream(response), context);
+            return;
+        }
         const value = await handler(event, context);
-        result(response, value);
+        await result(response, value);
     }
     catch {
         error(response);

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "@vyriy/server",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Small HTTP server adapter for Lambda-style Vyriy handlers",
   "type": "module",
   "main": "./index.js",
   "dependencies": {
     "@types/aws-lambda": "^8.10.161",
-    "@vyriy/env": "0.2.0",
-    "@vyriy/error": "0.2.0",
-    "@vyriy/handler": "0.2.0",
-    "@vyriy/logger": "0.2.0"
+    "@vyriy/env": "0.3.0",
+    "@vyriy/error": "0.3.0",
+    "@vyriy/handler": "0.3.0",
+    "@vyriy/logger": "0.3.0",
+    "@vyriy/router": "0.3.0"
   },
+  "agents": "./AGENTS.md",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -113,6 +115,16 @@
       "types": "./shutdown.d.ts",
       "import": "./shutdown.js",
       "default": "./shutdown.js"
+    },
+    "./static": {
+      "types": "./static.d.ts",
+      "import": "./static.js",
+      "default": "./static.js"
+    },
+    "./static.js": {
+      "types": "./static.d.ts",
+      "import": "./static.js",
+      "default": "./static.js"
     }
   }
 }

package/result.js

@@ -1,19 +1,22 @@
 import { STATUS_CODES } from 'node:http';
+const notFound = (response) => {
+    response
+        .writeHead(404, {
+        'content-type': 'application/json',
+    })
+        .end(JSON.stringify({ message: STATUS_CODES[404] }));
+};
 export const result = (response, value) => {
     if (!value) {
-        response
-            .writeHead(404, {
-            'content-type': 'application/json',
-        })
-            .end(JSON.stringify({ message: STATUS_CODES[404] }));
+        notFound(response);
         return;
     }
-    const { body, headers, multiValueHeaders, statusCode } = value;
+    const { body, headers, isBase64Encoded, multiValueHeaders, statusCode } = value;
     response.writeHead(statusCode, {
         ...headers,
         ...multiValueHeaders,
     });
-    response.end(body);
+    response.end(isBase64Encoded ? Buffer.from(body, 'base64') : body);
 };
 export const error = (response) => {
     response

package/static.d.ts

@@ -0,0 +1,8 @@
+import type { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
+import type { Handler } from '@vyriy/router';
+export type StaticFilesOptions = {
+    fallback?: false | string;
+    fallbackStatusCode?: number;
+};
+export type StaticFilesHandler = Handler & ((event: APIGatewayProxyEvent) => Promise<APIGatewayProxyResult>);
+export declare const staticFiles: (directory: string, options?: StaticFilesOptions) => StaticFilesHandler;

package/static.js

@@ -0,0 +1,120 @@
+import { STATUS_CODES } from 'node:http';
+import { readFile, stat } from 'node:fs/promises';
+import { extname, resolve, sep } from 'node:path';
+const CONTENT_TYPES = {
+    '.css': 'text/css; charset=utf-8',
+    '.gif': 'image/gif',
+    '.html': 'text/html; charset=utf-8',
+    '.ico': 'image/x-icon',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.js': 'text/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.mjs': 'text/javascript; charset=utf-8',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml; charset=utf-8',
+    '.txt': 'text/plain; charset=utf-8',
+    '.webp': 'image/webp',
+};
+const getContentType = (filePath) => CONTENT_TYPES[extname(filePath).toLowerCase()] ?? 'application/octet-stream';
+const notFound = () => ({
+    body: JSON.stringify({
+        message: STATUS_CODES[404],
+    }),
+    headers: {
+        'content-type': 'application/json',
+    },
+    statusCode: 404,
+});
+const methodNotAllowed = () => ({
+    body: JSON.stringify({
+        message: STATUS_CODES[405],
+    }),
+    headers: {
+        allow: 'GET, HEAD',
+        'content-type': 'application/json',
+    },
+    statusCode: 405,
+});
+const getFilePath = (directory, relativePath) => {
+    const rootPath = resolve(directory);
+    const filePath = resolve(rootPath, relativePath.replace(/^\/+/, '') || 'index.html');
+    if (filePath !== rootPath && !filePath.startsWith(`${rootPath}${sep}`)) {
+        return undefined;
+    }
+    return filePath;
+};
+const readFileResponse = async (filePath, method, statusCode = 200) => {
+    const file = await stat(filePath);
+    if (!file.isFile()) {
+        return undefined;
+    }
+    const headers = {
+        'content-length': String(file.size),
+        'content-type': getContentType(filePath),
+    };
+    if (method === 'HEAD') {
+        return {
+            body: '',
+            headers,
+            statusCode,
+        };
+    }
+    return {
+        body: (await readFile(filePath)).toString('base64'),
+        headers,
+        isBase64Encoded: true,
+        statusCode,
+    };
+};
+const readFallbackResponse = async (directory, method, options) => {
+    if (options.fallback === false) {
+        return undefined;
+    }
+    const fallbackPath = getFilePath(directory, options.fallback);
+    if (!fallbackPath) {
+        return undefined;
+    }
+    try {
+        return await readFileResponse(fallbackPath, method, options.fallbackStatusCode);
+    }
+    catch {
+        return undefined;
+    }
+};
+const isRouterParams = (value) => 'event' in value;
+const getRequest = (value) => {
+    if (isRouterParams(value)) {
+        return {
+            event: value.event,
+            relativePath: value.pathParameters?.proxy ?? '',
+        };
+    }
+    return {
+        event: value,
+        relativePath: value.path.replace(/^\/+/, ''),
+    };
+};
+export const staticFiles = (directory, options = {}) => async (params) => {
+    const { event, relativePath } = getRequest(params);
+    const normalizedOptions = {
+        fallback: '404.html',
+        fallbackStatusCode: 404,
+        ...options,
+    };
+    if (event.httpMethod !== 'GET' && event.httpMethod !== 'HEAD') {
+        return methodNotAllowed();
+    }
+    const filePath = getFilePath(directory, relativePath);
+    if (!filePath) {
+        return (await readFallbackResponse(directory, event.httpMethod, normalizedOptions)) ?? notFound();
+    }
+    try {
+        return ((await readFileResponse(filePath, event.httpMethod)) ??
+            (await readFallbackResponse(directory, event.httpMethod, normalizedOptions)) ??
+            notFound());
+    }
+    catch {
+        return (await readFallbackResponse(directory, event.httpMethod, normalizedOptions)) ?? notFound();
+    }
+};

package/types.d.ts

@@ -1,11 +1,13 @@
 import type { APIGatewayProxyEvent, APIGatewayProxyResult, Context } from 'aws-lambda';
-import type { Handler } from '@vyriy/handler';
+import type { ResponseStream } from '@vyriy/handler';
 import type { IncomingHttpHeaders, OutgoingHttpHeaders, Server as HttpServer } from 'node:http';
 export type { Context } from 'aws-lambda';
 export type Headers = OutgoingHttpHeaders;
 export type LambdaEvent = APIGatewayProxyEvent;
 export type LambdaResult = APIGatewayProxyResult;
-export type LambdaHandler = Handler<LambdaEvent, LambdaResult>;
+export type LambdaHandler = (event: LambdaEvent, context: Context) => Promise<LambdaResult>;
+export type LambdaStreamHandler = (event: LambdaEvent, responseStream: ResponseStream, context: Context) => Promise<LambdaResult | void>;
+export type ServerHandler = LambdaHandler | LambdaStreamHandler;
 export type RequestMessage = {
     headers: IncomingHttpHeaders;
     method?: string;
@@ -18,8 +20,12 @@ export type RequestMessage = {
 export type ResponseMessage = {
     end: {
         (): ResponseMessage;
-        (chunk: string): ResponseMessage;
+        (chunk: string | Buffer | Uint8Array): ResponseMessage;
     };
+    writableEnded?: boolean;
+    setContentType?: (contentType: string) => ResponseMessage;
+    setHeader?(name: string, value: number | string | readonly string[]): ResponseMessage;
+    write(chunk: string | Buffer | Uint8Array): boolean;
     writeHead(statusCode: number, headers?: OutgoingHttpHeaders): ResponseMessage;
 };
 export type ErrorEventTarget = {
@@ -34,6 +40,6 @@ export type MapParams = (request: RequestMessage) => Promise<{
 export type Server = HttpServer<typeof import('node:http').IncomingMessage, typeof import('node:http').ServerResponse>;
 export type Listen = (server: Server) => Server;
 export type NormalizeHeaders = (headers: IncomingHttpHeaders) => Record<string, string | undefined>;
-export type WriteResult<Response extends ResponseMessage = ResponseMessage> = (response: Response, result: LambdaResult | void) => void;
+export type WriteResult<Response extends ResponseMessage = ResponseMessage> = (response: Response, result: LambdaResult | void) => Promise<void> | void;
 export type WriteError<Response extends ResponseMessage = ResponseMessage> = (response: Response) => void;
-export type CreateServer = (handler: LambdaHandler) => Server;
+export type CreateServer = (handler: ServerHandler) => Server;