@devxcrew/framework 0.1.9 → 0.1.11

package/README.md

@@ -1,162 +1,92 @@
-# framework
+# @devxcrew/framework
 
-Own reusable configuration validation and native HTTP primitives.
+Shared Node and TypeScript runtime for Codexsun apps. It provides module lifecycle, HTTP, validation, logging, health, security, and a browser API client. Business rules stay in each app module. Platform Core owns identity, roles, and tenancy.
 
-Use the sibling workspace layout. Shared framework and UI keep their existing public exports and
-build contracts.
+## Install
 
-## Run
-
-Use Node 26.10 or newer and the package manifest requirements. Clone the sibling tools and
-mcp-governance repositories along with this repository.
+Use Node 26.10 or newer.
 
 ```powershell
-npm install
-npm run check
+npm install @devxcrew/framework
 ```
 
-Cxsun runs npm run build:framework using its compiler to build this package.
+Import server exports from `@devxcrew/framework`. Import the browser client from `@devxcrew/framework/client`.
+
+## Owner modules and routes
+
+Each app module exposes a public provider contract. The app composition root connects providers and passes their routes to `createApiRouter`. Keep Zod schemas, controllers, services, and persistence inside the owner module.
+
+```ts
+import {
+  composeModules,
+  createApiRouter,
+  createApplicationServer,
+  createModuleToken,
+  defineModuleProvider,
+  type ApiRoute,
+} from "@devxcrew/framework";
+
+const statusToken = createModuleToken<{ routes: ApiRoute[] }>("status");
+const status = defineModuleProvider({
+  token: statusToken,
+  dependencies: [],
+  create: (): { routes: ApiRoute[] } => ({
+    routes: [
+      {
+        method: "GET",
+        path: "/api/v1/status",
+        handler(_request, response) {
+          response.setHeader("Content-Type", "application/json");
+          response.end(JSON.stringify({ data: { ready: true } }));
+        },
+      },
+    ],
+  }),
+});
+
+const modules = composeModules([status]);
+await modules.start();
+const server = createApplicationServer({
+  config: {
+    name: "example",
+    port: 3000,
+    url: "http://localhost:3000",
+    host: "localhost",
+    mode: "development",
+  },
+  frontendDirectory: "dist/web",
+  apiHandler: createApiRouter([modules.get(statusToken)]),
+});
+server.listen(3000);
+```
 
-## Repository records
+`createApiRouter` matches methods and paths. Static paths take priority over `:id` paths. Owners validate route IDs, query strings, and JSON bodies. The router does not implement CRUD or business rules.
 
-- `AGENTS.md`: repository instructions and ownership rules.
-- `agent/SKILLS.md`: repository capabilities.
-- `agent/TASK.md`: current task and status.
-- `agent/PLAN.md`: next steps.
-- `agent/CHANGELOG.md`: versioned changes and validation results.
+`composeModules` also supports the older string-based `ModuleProvider` contract. New modules can use tokens for typed dependencies and runtime token checks.
 
-## Shared guidance
+## HTTP and validation
 
-Retrieve shared documentation and rules only from `https://mcp.codexsun.com/mcp` using `npm run mcp:connect`.
-A successful authenticated connection is required before repository work. Stop and report connection failures.
-Do not use local guides or cached instructions as fallback. Instruction retrieval does not authorize actions.
+- `readJsonBody` limits bytes and returns `unknown`. Validate it with an owner Zod schema through `parseWithSchema`.
+- Validation failures return HTTP 422 with `message` and `errors`. The older `error.fields` shape remains during migration.
+- `parseListQuery` checks page size and allowed sort fields. Owner schemas check business filters.
+- Owners return resource data as `{ data }` and lists as `{ data, meta, links }`.
+- `createApiClient` reads JSON responses and safe field errors. It does not add authentication or retry writes.
 
-Retrieve shared documentation and rules only from `https://mcp.codexsun.com/mcp` using `npm run mcp:connect`.
-A successful authenticated connection is required before repository work. Stop and report connection failures.
-Do not use local guides or cached instructions as fallback. Instruction retrieval does not authorize actions.
+## Operations
 
-Configure these values with `.env.example`:
+- `createApplicationServer` sets basic security headers. Configure exact CORS origins, trusted proxy addresses, and rate limits for each app.
+- The built-in rate limiter is local to one process. Set `rateLimit.store` to an app-owned atomic shared store when deployment uses multiple instances. Store failures return 503.
+- Set `logger` for request logs. Set `onRequestComplete` to pass request data to a metrics or tracing adapter. Neither receives URL query values.
+- Set `readiness` to a sync or async check. The server bounds it with `readinessTimeoutMs`. `createAsyncHealthProvider` bounds named async dependency checks.
+- API handlers and module start and stop hooks have configurable deadlines. Owners must honor cancellation and release resources.
 
-- `MCP_SERVER_URL`
-- `MCP_SERVER_SECRET`
-- `APP_ID`
-- `APP_USER`
+## Work on this repository
 
-Keep the secret in ignored `.env` files.
+Connect to live governance before repository work. Stop if the authenticated connection fails. Do not use local or cached guidance as a fallback.
 
 ```powershell
 npm run mcp:connect
-npm run mcp:verify
+npm run release:check
 ```
 
-Use `mcp:connect` to retrieve instructions. Use `mcp:verify` for a strict connection test.
-Connection failures do not block application work. Editor registration uses the central connection
-template and depends on the editor.
-
-## Maintenance
-
-```powershell
-npm run version-bump -- --dry-run
-npm run version-bump -- --title "Release title" --note "Change details"
-npm run check:versions
-npm run fix:line-endings
-npm run lines:check
-npm run github:now -- --dry-run
-```
-
-Version bumps align `package.json`, `package-lock.json`, and `agent/CHANGELOG.md`. Record changes
-and validation before committing.
-
-Commit subjects use `#<patch> - <release title>`. For example:
-`#5 - Central governance and repository agent layout`.
-
-Review the changed files before an authorized `npm run github:now`. Do not bump again when the
-release version is already prepared.
-
-## Tools source and publication
-
-Workspace maintenance delegates to `shared/tools`. The installed npm package remains pinned at
-`0.1.3` until agent changelog support is published.
-
-GitHub source releases use `github:now`. Npm publication requires separate authorization.
-
-## npm package
-
-Framework publishes compiled ESM JavaScript and TypeScript declarations. Run npm run build before local development consumption.
-
-Run `npm run release:check`, then `npm publish --access public` from this repository.
-Only public exports are supported. App manifests use npm versions.
-
-## Public runtime contracts
-
-`composeModules` registers owner providers in dependency order. Factories receive only their declared dependencies.
-`start` runs lifecycle hooks. Failed startup calls stop hooks in reverse order, including the failed module.
-`stop` attempts every cleanup hook and reports cleanup failures together.
-
-`createApplicationServer` keeps the existing static and development behavior.
-Optional `apiHandler` receives the request, response, and request context for `/api` paths.
-The handler owns routing and independent Zod validation before service execution.
-Unexpected handler failures return a safe JSON error with a generated request ID.
-Optional `readiness` exposes `/health/ready`. Readiness reports the consumer's actual dependency state.
-Receive and header timeouts are configurable positive millisecond values. They do not bound handler execution.
-
-`readJsonBody` checks content type and limits bytes. Its result is unknown until the owner validates it.
-`parseListQuery` validates pagination and allowlisted sort fields. Owners validate domain filters independently.
-`HttpError` carries safe transport errors and optional field messages. Do not place secrets in these messages.
-`createRequestContext` supplies a server-generated request ID and an abort signal.
-Identity, tenant scope, transactions, and domain rules remain with their owner providers.
-
-## Owner providers
-
-Use `parseWithSchema` or `createValidationProvider().parse` to validate untrusted server input with a Zod schema.
-Validation failures throw `HttpError` with status 422 and safe field messages. Keep schemas and domain rules in the application module.
-
-Use `createLogger` for JSON logs. Set the minimum level and pass a sink for a logging adapter.
-Child loggers keep request context. The logger masks values under secret-like field names, bearer tokens, URL credentials, and common secret query parameters.
-
-Use `createHealthProvider` with named, synchronous dependency checks.
-`isReady()` returns false when any check fails. `snapshot()` reports check names and results. Expose that detail only through an authorized operations route.
-
-`createApplicationServer` applies `X-Content-Type-Options`, `X-Frame-Options`, and `Referrer-Policy` by default.
-Set `security.allowedOrigins` to enable exact-origin CORS. A configured allowlist rejects requests with other Origin values.
-Set `security.headers` for application-specific headers. Configure HSTS only when the public connection uses HTTPS.
-Set `security.trustedProxyAddresses` to exact proxy IP addresses before trusting `X-Forwarded-For`.
-Set `security.rateLimit` to enable an in-memory fixed-window limit by client address. It applies to all requests in one process.
-Use a shared rate-limit service when multiple app processes must share a limit.
-
-Import the browser-safe client from `@devxcrew/framework/client`.
-`createApiClient` accepts a base URL, optional common headers, and an optional Fetch implementation.
-Its `request` method passes cancellation through, returns JSON responses, and throws `ApiClientError` for non-success responses.
-The client reads only the Framework safe error envelope. It does not add authentication or retry mutations.
-
-Provider factories must only compose values. Acquire connections and other resources inside start hooks so failed startup can release them.
-Stop during startup is rejected. Concurrent stop calls share one cleanup operation.
-Oversized streamed JSON is drained without destroying the response socket, allowing a safe 413 response.
-
-## Handler and shutdown deadlines
-
-Set `handlerTimeoutMs` on `createApplicationServer` to bound API response time. The default is 30000 milliseconds.
-Request contexts expose `deadlineAt` and `signal`. At the deadline, the server aborts the signal.
-It returns a safe 504 before response headers or destroys an incomplete streamed response.
-Handlers must honor cancellation and check response state before writing late results.
-A deadline cannot stop synchronous JavaScript or forcibly cancel an uncooperative dependency.
-
-Set `shutdownTimeoutMs` in the second argument of `composeModules`. The default total budget is 30000 milliseconds.
-Stop attempts every hook in reverse dependency order. The budget bounds awaited asynchronous cleanup.
-A timed-out hook can continue running. State becomes `failed`, and stop rejects with cleanup failures.
-Consumers must report failed cleanup and apply their process termination policy.
-
-## Startup deadline
-
-Set startupTimeoutMs in composeModules options. The default total startup budget is 30000 milliseconds.
-Start hooks receive the owner provider and an AbortSignal. Timeout aborts the signal and rolls back started modules.
-An uncooperative hook can continue. Owners must honor cancellation before acquiring or retaining resources.
-
-## Consumer transaction and cancellation contract
-
-Framework owns request deadlines and cancellation signals. The module that owns a mutation owns its database transaction.
-A module validates authorization and input before persistence. It checks cancellation before a write and before committing.
-Cancellation after a successful commit does not roll back committed data. A client must reload before retrying an uncertain mutation.
-Existing identity updates use expectedVersion for stale-write detection. Token completion uses a single database claim.
-Do not retry POST mutations automatically. Add an idempotency key only when a real consumer requires repeatable retries.
-Synchronous identity operations need no generic event bus or queue. External delivery stays outside a database transaction.
+Keep secrets in ignored environment files. Commit and publish through the repository release workflow only when authorized.

package/dist/http/server.d.ts

@@ -2,13 +2,25 @@ import { type RequestListener } from "node:http";
 import type { ApplicationConfig } from "../runtime/config.js";
 import { createRequestContext } from "../modules/http/http.provider.js";
 import { type HttpSecurityOptions } from "../modules/http/http-security.provider.js";
+import type { Logger } from "../modules/logger/logger.provider.js";
+export interface RequestCompletion {
+    requestId: string;
+    method: string;
+    path: string;
+    statusCode: number;
+    durationMs: number;
+    aborted: boolean;
+}
 export interface ApplicationServerOptions {
     config: ApplicationConfig;
     frontendDirectory: string;
     developmentHandler?: RequestListener;
     apiHandler?: (request: import("node:http").IncomingMessage, response: import("node:http").ServerResponse, context: ReturnType<typeof createRequestContext>) => void | Promise<void>;
-    readiness?: () => boolean;
+    readiness?: () => boolean | Promise<boolean>;
+    readinessTimeoutMs?: number;
     security?: HttpSecurityOptions;
+    logger?: Logger;
+    onRequestComplete?: (event: RequestCompletion) => void;
     requestTimeoutMs?: number;
     headersTimeoutMs?: number;
     handlerTimeoutMs?: number;

package/dist/http/server.js

@@ -15,61 +15,134 @@ const contentTypes = {
 };
 export function createApplicationServer(options) {
     const handlerTimeoutMs = positiveTimeout(options.handlerTimeoutMs ?? 30_000);
+    const readinessTimeoutMs = positiveTimeout(options.readinessTimeoutMs ?? 2_000);
     const security = createHttpSecurityProvider(options.security);
     const server = createServer((request, response) => {
-        if (security.handle(request, response))
-            return;
-        if (options.readiness && request.url === "/health/ready") {
-            if (request.method !== "GET" && request.method !== "HEAD") {
-                response.writeHead(405, { Allow: "GET, HEAD" });
-                response.end();
-                return;
-            }
-            let ready = false;
-            try {
-                ready = options.readiness();
-            }
-            catch {
-                ready = false;
-            }
-            response.writeHead(ready ? 200 : 503, {
-                "Content-Type": "application/json",
-                "Cache-Control": "no-store",
-            });
-            response.end(request.method === "HEAD" ? undefined : JSON.stringify({ ready }));
-            return;
-        }
-        if (options.apiHandler && /^\/api(?:\/|\?|$)/.test(request.url ?? "")) {
-            const context = createRequestContext(request, Date.now() + handlerTimeoutMs);
-            const deadline = setTimeout(() => {
-                const error = new HttpError(504, "request_timeout", "Request deadline exceeded.");
-                context.abort(error);
-                if (!response.writableEnded && !response.destroyed)
-                    writeJsonError(response, error, context.requestId);
-            }, handlerTimeoutMs);
-            response.once("finish", () => clearTimeout(deadline));
-            response.once("close", () => clearTimeout(deadline));
-            response.setHeader("X-Request-ID", context.requestId);
-            response.once("close", () => {
-                if (!response.writableFinished)
-                    request.emit("aborted");
-            });
-            void Promise.resolve()
-                .then(() => options.apiHandler(request, response, context))
-                .catch((error) => {
-                if (!response.writableEnded && !response.destroyed)
-                    writeJsonError(response, error, context.requestId);
-            });
-            return;
-        }
-        if (options.developmentHandler)
-            return options.developmentHandler(request, response);
-        void serveFrontend(options.frontendDirectory, request.url || "/", request.method || "GET", response);
+        const isApi = /^\/api(?:\/|\?|$)/.test(request.url ?? "");
+        const context = createRequestContext(request);
+        response.setHeader("X-Request-ID", context.requestId);
+        reportRequest(request, response, context.requestId, options);
+        void security
+            .handleAsync(request, response)
+            .then((handled) => {
+            if (!handled && !response.destroyed)
+                serveRequest(request, response, context, isApi, options, handlerTimeoutMs, readinessTimeoutMs);
+        })
+            .catch(() => {
+            if (!response.writableEnded && !response.destroyed)
+                writeJsonError(response, new HttpError(503, "security_unavailable", "Request checks are unavailable."), context.requestId);
+        });
     });
     server.requestTimeout = positiveTimeout(options.requestTimeoutMs ?? 30_000);
     server.headersTimeout = positiveTimeout(options.headersTimeoutMs ?? 10_000);
     return server;
 }
+function serveRequest(request, response, context, isApi, options, handlerTimeoutMs, readinessTimeoutMs) {
+    if (options.readiness && request.url === "/health/ready") {
+        void serveReadiness(request, response, options.readiness, readinessTimeoutMs);
+        return;
+    }
+    if (options.apiHandler && isApi) {
+        context.deadlineAt = Date.now() + handlerTimeoutMs;
+        const deadline = setTimeout(() => {
+            const error = new HttpError(504, "request_timeout", "Request deadline exceeded.");
+            context.abort(error);
+            if (!response.writableEnded && !response.destroyed)
+                writeJsonError(response, error, context.requestId);
+        }, handlerTimeoutMs);
+        response.once("finish", () => clearTimeout(deadline));
+        response.once("close", () => clearTimeout(deadline));
+        response.once("close", () => {
+            if (!response.writableFinished)
+                request.emit("aborted");
+        });
+        void Promise.resolve()
+            .then(() => options.apiHandler(request, response, context))
+            .catch((error) => {
+            if (!response.writableEnded && !response.destroyed)
+                writeJsonError(response, error, context.requestId);
+        });
+        return;
+    }
+    if (options.developmentHandler) {
+        options.developmentHandler(request, response);
+        return;
+    }
+    void serveFrontend(options.frontendDirectory, request.url || "/", request.method || "GET", response);
+}
+async function serveReadiness(request, response, readiness, timeoutMs) {
+    if (request.method !== "GET" && request.method !== "HEAD") {
+        response.writeHead(405, { Allow: "GET, HEAD" });
+        response.end();
+        return;
+    }
+    let timer;
+    let ready = false;
+    try {
+        ready = await Promise.race([
+            Promise.resolve().then(readiness),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(false), timeoutMs);
+            }),
+        ]);
+    }
+    catch {
+        ready = false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (response.destroyed)
+        return;
+    response.writeHead(ready ? 200 : 503, {
+        "Content-Type": "application/json",
+        "Cache-Control": "no-store",
+    });
+    response.end(request.method === "HEAD" ? undefined : JSON.stringify({ ready }));
+}
+function reportRequest(request, response, requestId, options) {
+    if (!options.logger && !options.onRequestComplete)
+        return;
+    const startedAt = Date.now();
+    let reported = false;
+    const report = () => {
+        if (reported)
+            return;
+        reported = true;
+        const event = {
+            requestId,
+            method: request.method ?? "GET",
+            path: safePath(request.url),
+            statusCode: response.statusCode,
+            durationMs: Date.now() - startedAt,
+            aborted: !response.writableFinished,
+        };
+        try {
+            options.onRequestComplete?.(event);
+        }
+        catch {
+            /* A diagnostics sink must not affect the response. */
+        }
+        if (options.logger) {
+            const level = event.aborted || event.statusCode >= 500
+                ? "error"
+                : event.statusCode >= 400
+                    ? "warn"
+                    : "info";
+            options.logger[level]("HTTP request completed", { ...event });
+        }
+    };
+    response.once("finish", report);
+    response.once("close", report);
+}
+function safePath(url) {
+    try {
+        return new URL(url ?? "/", "http://localhost").pathname;
+    }
+    catch {
+        return "/";
+    }
+}
 function positiveTimeout(value) {
     if (!Number.isSafeInteger(value) || value < 1)
         throw new Error("Invalid HTTP timeout.");

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { readApplicationConfig, type ApplicationConfig, } from "./runtime/config.js";
-export { createApplicationServer, type ApplicationServerOptions, } from "./http/server.js";
-export { composeModules, type ModuleProvider, } from "./modules/runtime/runtime.provider.js";
-export { HttpError, createRequestContext, writeJsonError, parseListQuery, readJsonBody, } from "./modules/http/http.provider.js";
+export { createApplicationServer, type ApplicationServerOptions, type RequestCompletion, } from "./http/server.js";
+export { composeModules, createModuleToken, defineModuleProvider, type ModuleProvider, type ModuleToken, type TypedModuleDefinition, } from "./modules/runtime/runtime.provider.js";
+export { HttpError, createRequestContext, writeJsonError, parseListQuery, readJsonBody, createApiRouter, type ApiMethod, type ApiRoute, type ApiRouteProvider, } from "./modules/http/http.provider.js";
 export { createValidationProvider, parseWithSchema, type ValidationProvider, } from "./modules/validation/validation.provider.js";
 export { createLogger, type Logger, type LoggerOptions, type LogFields, type LogLevel, type LogRecord, } from "./modules/logger/logger.provider.js";
-export { createHttpSecurityProvider, type HttpSecurityOptions, type HttpSecurityProvider, type RateLimitOptions, } from "./modules/http/http-security.provider.js";
-export { createHealthProvider, type HealthCheck, type HealthProvider, type HealthSnapshot, } from "./modules/health/health.provider.js";
+export { createHttpSecurityProvider, type HttpSecurityOptions, type HttpSecurityProvider, type RateLimitOptions, type RateLimitStore, } from "./modules/http/http-security.provider.js";
+export { createHealthProvider, createAsyncHealthProvider, type HealthCheck, type HealthProvider, type HealthSnapshot, type AsyncHealthCheck, type AsyncHealthProvider, } from "./modules/health/health.provider.js";

package/dist/index.js

@@ -1,8 +1,8 @@
 export { readApplicationConfig, } from "./runtime/config.js";
 export { createApplicationServer, } from "./http/server.js";
-export { composeModules, } from "./modules/runtime/runtime.provider.js";
-export { HttpError, createRequestContext, writeJsonError, parseListQuery, readJsonBody, } from "./modules/http/http.provider.js";
+export { composeModules, createModuleToken, defineModuleProvider, } from "./modules/runtime/runtime.provider.js";
+export { HttpError, createRequestContext, writeJsonError, parseListQuery, readJsonBody, createApiRouter, } from "./modules/http/http.provider.js";
 export { createValidationProvider, parseWithSchema, } from "./modules/validation/validation.provider.js";
 export { createLogger, } from "./modules/logger/logger.provider.js";
 export { createHttpSecurityProvider, } from "./modules/http/http-security.provider.js";
-export { createHealthProvider, } from "./modules/health/health.provider.js";
+export { createHealthProvider, createAsyncHealthProvider, } from "./modules/health/health.provider.js";

package/dist/modules/api-client/api-client.provider.js

@@ -45,12 +45,15 @@ async function readPayload(response) {
 function toApiError(response, payload) {
     const envelope = asRecord(payload);
     const error = asRecord(envelope?.error);
-    const code = stringValue(error?.code) ?? "request_failed";
-    const message = stringValue(error?.message) ?? "The request could not be completed.";
+    const code = stringValue(error?.code) ??
+        (response.status === 422 ? "validation_failed" : "request_failed");
+    const message = stringValue(error?.message) ??
+        stringValue(envelope?.message) ??
+        "The request could not be completed.";
     return new ApiClientError(message, response.status, code, stringValue(error?.requestId) ??
         stringValue(envelope?.requestId) ??
         response.headers.get("x-request-id") ??
-        undefined, readFields(error?.fields));
+        undefined, readFields(error?.fields) ?? readFields(envelope?.errors));
 }
 function asRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value)

package/dist/modules/health/health.provider.d.ts

@@ -1,7 +1,13 @@
 export type HealthCheck = () => boolean;
 export type HealthSnapshot = Readonly<Record<string, boolean>>;
+export type AsyncHealthCheck = () => boolean | Promise<boolean>;
 export interface HealthProvider {
     isReady(): boolean;
     snapshot(): HealthSnapshot;
 }
+export interface AsyncHealthProvider {
+    isReady(): Promise<boolean>;
+    snapshot(): Promise<HealthSnapshot>;
+}
 export declare function createHealthProvider(checks: Readonly<Record<string, HealthCheck>>): HealthProvider;
+export declare function createAsyncHealthProvider(checks: Readonly<Record<string, AsyncHealthCheck>>, timeoutMs?: number): AsyncHealthProvider;

package/dist/modules/health/health.provider.js

@@ -12,6 +12,37 @@ export function createHealthProvider(checks) {
         },
     };
 }
+export function createAsyncHealthProvider(checks, timeoutMs = 2_000) {
+    const entries = Object.entries(checks);
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1)
+        throw new Error("Invalid health timeout.");
+    if (entries.some(([name, check]) => !name.trim() || typeof check !== "function"))
+        throw new Error("Health checks require a name and function.");
+    const snapshot = async () => Object.fromEntries(await Promise.all(entries.map(async ([name, check]) => [name, await runAsyncCheck(check, timeoutMs)])));
+    return {
+        snapshot,
+        async isReady() {
+            return Object.values(await snapshot()).every(Boolean);
+        },
+    };
+}
+async function runAsyncCheck(check, timeoutMs) {
+    let timer;
+    try {
+        return await Promise.race([
+            Promise.resolve().then(check),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(false), timeoutMs);
+            }),
+        ]);
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 function runCheck(check) {
     try {
         return check();

package/dist/modules/http/http-rate-limit.d.ts

@@ -0,0 +1,3 @@
+import type { RateLimitOptions } from "./http-security.provider.js";
+export declare function createLimiter(options: RateLimitOptions): (address: string) => number;
+export declare function validateRateLimit(options: RateLimitOptions): void;

package/dist/modules/http/http-rate-limit.js

@@ -0,0 +1,32 @@
+export function createLimiter(options) {
+    const maxEntries = options.maxEntries ?? 10_000;
+    const clients = new Map();
+    return (address) => {
+        const now = Date.now();
+        for (const [key, record] of clients)
+            if (record.resetAt <= now)
+                clients.delete(key);
+        let record = clients.get(address);
+        if (!record) {
+            if (clients.size >= maxEntries)
+                return Math.ceil(options.windowMs / 1000);
+            record = { count: 0, resetAt: now + options.windowMs };
+            clients.set(address, record);
+        }
+        if (record.count >= options.limit)
+            return Math.max(1, Math.ceil((record.resetAt - now) / 1000));
+        record.count++;
+        return 0;
+    };
+}
+export function validateRateLimit(options) {
+    const maxEntries = options.maxEntries ?? 10_000;
+    if (!Number.isSafeInteger(options.limit) ||
+        options.limit < 1 ||
+        !Number.isSafeInteger(options.windowMs) ||
+        options.windowMs < 1 ||
+        !Number.isSafeInteger(maxEntries) ||
+        maxEntries < 1 ||
+        maxEntries > 100_000)
+        throw new Error("Invalid rate limit.");
+}

package/dist/modules/http/http-security.provider.d.ts

@@ -3,6 +3,11 @@ export interface RateLimitOptions {
     limit: number;
     windowMs: number;
     maxEntries?: number;
+    store?: RateLimitStore;
+    storeTimeoutMs?: number;
+}
+export interface RateLimitStore {
+    consume(address: string, limit: number, windowMs: number): Promise<number>;
 }
 export interface HttpSecurityOptions {
     allowedOrigins?: readonly string[];
@@ -17,6 +22,7 @@ export interface HttpSecurityOptions {
 }
 export interface HttpSecurityProvider {
     handle(request: IncomingMessage, response: ServerResponse): boolean;
+    handleAsync(request: IncomingMessage, response: ServerResponse): Promise<boolean>;
     clientAddress(request: IncomingMessage): string;
 }
 export declare function createHttpSecurityProvider(options?: HttpSecurityOptions): HttpSecurityProvider;

package/dist/modules/http/http-security.provider.js

@@ -1,5 +1,6 @@
 import { isIP } from "node:net";
 import { validateHeaderName, validateHeaderValue, } from "node:http";
+import { createLimiter, validateRateLimit } from "./http-rate-limit.js";
 const defaultMethods = [
     "GET",
     "HEAD",
@@ -26,75 +27,102 @@ export function createHttpSecurityProvider(options = {}) {
         validateHeaderName(name);
         validateHeaderValue(name, value);
     }
-    const limiter = options.rateLimit
-        ? createLimiter(options.rateLimit)
-        : undefined;
+    const rateLimit = options.rateLimit;
+    if (rateLimit)
+        validateRateLimit(rateLimit);
+    const limiter = rateLimit && !rateLimit.store ? createLimiter(rateLimit) : undefined;
+    const storeTimeoutMs = rateLimit?.storeTimeoutMs ?? 2_000;
+    if (!Number.isSafeInteger(storeTimeoutMs) || storeTimeoutMs < 1)
+        throw new Error("Invalid rate limit store timeout.");
     const clientAddress = (request) => resolveClientAddress(request, trustedProxies);
-    return {
-        handle(request, response) {
-            response.setHeader("X-Content-Type-Options", "nosniff");
-            response.setHeader("X-Frame-Options", "DENY");
-            response.setHeader("Referrer-Policy", "strict-origin-when-cross-origin");
-            for (const [name, value] of customHeaders)
-                response.setHeader(name, value);
-            if (limiter) {
-                const retryAfter = limiter(clientAddress(request));
-                if (retryAfter > 0) {
-                    response.writeHead(429, {
-                        "Content-Type": "application/json; charset=utf-8",
-                        "Cache-Control": "no-store",
-                        "Retry-After": String(retryAfter),
-                    });
-                    response.end(JSON.stringify({
-                        error: {
-                            code: "rate_limit_exceeded",
-                            message: "Too many requests.",
-                        },
-                    }));
-                    return true;
-                }
-            }
-            const origin = request.headers.origin;
-            if (!origins.size || !origin)
-                return false;
-            response.setHeader("Vary", appendVary(response.getHeader("Vary"), "Origin"));
-            if (!origins.has(origin)) {
+    const applyHeaders = (response) => {
+        response.setHeader("X-Content-Type-Options", "nosniff");
+        response.setHeader("X-Frame-Options", "DENY");
+        response.setHeader("Referrer-Policy", "strict-origin-when-cross-origin");
+        for (const [name, value] of customHeaders)
+            response.setHeader(name, value);
+    };
+    const processRequest = (request, response, retryAfter) => {
+        applyHeaders(response);
+        if (retryAfter > 0) {
+            response.writeHead(429, {
+                "Content-Type": "application/json; charset=utf-8",
+                "Cache-Control": "no-store",
+                "Retry-After": String(retryAfter),
+            });
+            response.end(JSON.stringify({
+                error: { code: "rate_limit_exceeded", message: "Too many requests." },
+            }));
+            return true;
+        }
+        const origin = request.headers.origin;
+        if (!origins.size || !origin)
+            return false;
+        response.setHeader("Vary", appendVary(response.getHeader("Vary"), "Origin"));
+        if (!origins.has(origin)) {
+            response.writeHead(403, { "Cache-Control": "no-store" });
+            response.end();
+            return true;
+        }
+        response.setHeader("Access-Control-Allow-Origin", origin);
+        if (options.allowCredentials)
+            response.setHeader("Access-Control-Allow-Credentials", "true");
+        if (exposedHeaders.length)
+            response.setHeader("Access-Control-Expose-Headers", exposedHeaders.join(", "));
+        const requestedMethod = request.headers["access-control-request-method"];
+        if (request.method === "OPTIONS" && requestedMethod) {
+            response.setHeader("Vary", appendVary(appendVary(response.getHeader("Vary"), "Access-Control-Request-Method"), "Access-Control-Request-Headers"));
+            const requestedHeaders = (request.headers["access-control-request-headers"] ?? "")
+                .split(",")
+                .map((value) => value.trim())
+                .filter(Boolean);
+            if (!methods.includes(requestedMethod) ||
+                requestedHeaders.some((name) => !headers.some((allowed) => allowed.toLowerCase() === name.toLowerCase()))) {
                 response.writeHead(403, { "Cache-Control": "no-store" });
                 response.end();
                 return true;
             }
-            response.setHeader("Access-Control-Allow-Origin", origin);
-            if (options.allowCredentials)
-                response.setHeader("Access-Control-Allow-Credentials", "true");
-            if (exposedHeaders.length)
-                response.setHeader("Access-Control-Expose-Headers", exposedHeaders.join(", "));
-            const requestedMethod = request.headers["access-control-request-method"];
-            if (request.method === "OPTIONS" && requestedMethod) {
-                response.setHeader("Vary", appendVary(appendVary(response.getHeader("Vary"), "Access-Control-Request-Method"), "Access-Control-Request-Headers"));
-                const requestedHeaders = (request.headers["access-control-request-headers"] ?? "")
-                    .split(",")
-                    .map((value) => value.trim())
-                    .filter(Boolean);
-                if (!methods.includes(requestedMethod) ||
-                    requestedHeaders.some((name) => !headers.some((allowed) => allowed.toLowerCase() === name.toLowerCase()))) {
-                    response.writeHead(403, { "Cache-Control": "no-store" });
-                    response.end();
-                    return true;
-                }
-                response.setHeader("Access-Control-Allow-Methods", methods.join(", "));
-                if (requestedHeaders.length)
-                    response.setHeader("Access-Control-Allow-Headers", requestedHeaders.join(", "));
-                response.setHeader("Access-Control-Max-Age", String(maxAge));
-                response.writeHead(204);
-                response.end();
-                return true;
+            response.setHeader("Access-Control-Allow-Methods", methods.join(", "));
+            if (requestedHeaders.length)
+                response.setHeader("Access-Control-Allow-Headers", requestedHeaders.join(", "));
+            response.setHeader("Access-Control-Max-Age", String(maxAge));
+            response.writeHead(204);
+            response.end();
+            return true;
+        }
+        if (!methods.includes(request.method ?? "GET")) {
+            response.writeHead(405, { Allow: methods.join(", ") });
+            response.end();
+            return true;
+        }
+        return false;
+    };
+    const handle = (request, response) => {
+        if (rateLimit?.store)
+            throw new Error("A shared rate limit store requires handleAsync.");
+        return processRequest(request, response, limiter?.(clientAddress(request)) ?? 0);
+    };
+    return {
+        handle,
+        async handleAsync(request, response) {
+            if (!rateLimit?.store)
+                return handle(request, response);
+            applyHeaders(response);
+            let timer;
+            try {
+                const retryAfter = await Promise.race([
+                    Promise.resolve().then(() => rateLimit.store.consume(clientAddress(request), rateLimit.limit, rateLimit.windowMs)),
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(new Error("Rate limit store timed out.")), storeTimeoutMs);
+                    }),
+                ]);
+                if (!Number.isSafeInteger(retryAfter) || retryAfter < 0)
+                    throw new Error("Invalid rate limit store result.");
+                return processRequest(request, response, retryAfter);
             }
-            if (!methods.includes(request.method ?? "GET")) {
-                response.writeHead(405, { Allow: methods.join(", ") });
-                response.end();
-                return true;
+            finally {
+                clearTimeout(timer);
             }
-            return false;
         },
         clientAddress,
     };
@@ -117,36 +145,6 @@ function resolveClientAddress(request, trustedProxies) {
     }
     return peer;
 }
-function createLimiter(options) {
-    const maxEntries = options.maxEntries ?? 10_000;
-    if (!Number.isSafeInteger(options.limit) ||
-        options.limit < 1 ||
-        !Number.isSafeInteger(options.windowMs) ||
-        options.windowMs < 1 ||
-        !Number.isSafeInteger(maxEntries) ||
-        maxEntries < 1 ||
-        maxEntries > 100_000) {
-        throw new Error("Invalid rate limit.");
-    }
-    const clients = new Map();
-    return (address) => {
-        const now = Date.now();
-        for (const [key, record] of clients)
-            if (record.resetAt <= now)
-                clients.delete(key);
-        let record = clients.get(address);
-        if (!record) {
-            if (clients.size >= maxEntries)
-                return Math.ceil(options.windowMs / 1000);
-            record = { count: 0, resetAt: now + options.windowMs };
-            clients.set(address, record);
-        }
-        if (record.count >= options.limit)
-            return Math.max(1, Math.ceil((record.resetAt - now) / 1000));
-        record.count++;
-        return 0;
-    };
-}
 function validateOrigin(value) {
     let parsed;
     try {

package/dist/modules/http/http.provider.d.ts

@@ -12,6 +12,16 @@ export declare function createRequestContext(request: IncomingMessage, deadlineA
     abort: (reason?: unknown) => void;
 };
 export declare function writeJsonError(response: ServerResponse, error: unknown, requestId: string): void;
+export type ApiMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
+export interface ApiRoute {
+    method: ApiMethod;
+    path: string;
+    handler(request: IncomingMessage, response: ServerResponse, context: ReturnType<typeof createRequestContext>, params: Readonly<Record<string, string>>): void | Promise<void>;
+}
+export interface ApiRouteProvider {
+    routes: readonly ApiRoute[];
+}
+export declare function createApiRouter(providers: readonly ApiRouteProvider[]): (request: IncomingMessage, response: ServerResponse, context: ReturnType<typeof createRequestContext>) => void | Promise<void>;
 export declare function parseListQuery(search: URLSearchParams, allowedSorts: readonly string[], defaults?: {
     perPage: number;
     maxPerPage: number;

package/dist/modules/http/http.provider.js

@@ -16,8 +16,12 @@ export class HttpError extends Error {
 export function createRequestContext(request, deadlineAt) {
     const controller = new AbortController();
     request.once("aborted", () => controller.abort());
-    return { requestId: randomUUID(), signal: controller.signal, deadlineAt,
-        abort: (reason) => controller.abort(reason) };
+    return {
+        requestId: randomUUID(),
+        signal: controller.signal,
+        deadlineAt,
+        abort: (reason) => controller.abort(reason),
+    };
 }
 export function writeJsonError(response, error, requestId) {
     if (response.headersSent) {
@@ -26,14 +30,95 @@ export function writeJsonError(response, error, requestId) {
     }
     const known = error instanceof HttpError;
     response.writeHead(known ? error.status : 500, {
-        "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store",
+        "Content-Type": "application/json; charset=utf-8",
+        "Cache-Control": "no-store",
         "X-Request-ID": requestId,
     });
-    response.end(JSON.stringify({ error: {
+    response.end(JSON.stringify({
+        error: {
             code: known ? error.code : "internal_error",
             message: known ? error.message : "Unable to complete the request.",
             ...(known && error.fields ? { fields: error.fields } : {}),
-        }, requestId }));
+        },
+        requestId,
+        ...(known && error.status === 422 && error.fields
+            ? { message: error.message, errors: error.fields }
+            : {}),
+    }));
+}
+export function createApiRouter(providers) {
+    const registered = providers
+        .flatMap((provider) => provider.routes)
+        .map(registerRoute);
+    const keys = new Set();
+    for (const entry of registered) {
+        const key = `${entry.route.method} ${entry.segments.map((part) => (part.startsWith(":") ? ":" : part)).join("/")}`;
+        if (keys.has(key))
+            throw new Error(`Duplicate API route: ${entry.route.path}`);
+        keys.add(key);
+    }
+    registered.sort((left, right) => right.staticCount - left.staticCount);
+    return (request, response, context) => {
+        let segments;
+        try {
+            const pathname = new URL(request.url ?? "/", "http://localhost").pathname;
+            segments = pathname.split("/").filter(Boolean).map(decodeURIComponent);
+            if (segments.some((part) => part.includes("/") || part.includes("\\")))
+                throw new Error("Encoded path separator.");
+        }
+        catch {
+            throw new HttpError(400, "invalid_url", "Invalid URL.");
+        }
+        const matching = registered
+            .map((entry) => ({ entry, params: matchRoute(entry.segments, segments) }))
+            .filter(({ params }) => params !== undefined);
+        const mostSpecific = matching.filter(({ entry }) => entry.staticCount === matching[0]?.entry.staticCount);
+        const selected = mostSpecific.find(({ entry }) => entry.route.method === request.method);
+        if (selected)
+            return selected.entry.route.handler(request, response, context, selected.params);
+        if (mostSpecific.length) {
+            response.setHeader("Allow", [...new Set(mostSpecific.map(({ entry }) => entry.route.method))].join(", "));
+            throw new HttpError(405, "method_not_allowed", "Method not allowed.");
+        }
+        throw new HttpError(404, "not_found", "Resource not found.");
+    };
+}
+function registerRoute(route) {
+    if (!["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE"].includes(route.method) ||
+        typeof route.handler !== "function")
+        throw new Error(`Invalid API route: ${route.path}`);
+    if (!route.path.startsWith("/api/v1/") ||
+        route.path.endsWith("/") ||
+        route.path.includes("?"))
+        throw new Error(`Invalid API route: ${route.path}`);
+    const segments = route.path.split("/").filter(Boolean);
+    for (const part of segments) {
+        if (part.startsWith(":")) {
+            if (!/^:[A-Za-z_][A-Za-z0-9_]*$/.test(part))
+                throw new Error(`Invalid API route: ${route.path}`);
+        }
+        else if (!/^[A-Za-z0-9_-]+$/.test(part)) {
+            throw new Error(`Invalid API route: ${route.path}`);
+        }
+    }
+    return {
+        route,
+        segments,
+        staticCount: segments.filter((part) => !part.startsWith(":")).length,
+    };
+}
+function matchRoute(pattern, path) {
+    if (pattern.length !== path.length)
+        return undefined;
+    const params = Object.create(null);
+    for (let index = 0; index < pattern.length; index++) {
+        const part = pattern[index];
+        if (part.startsWith(":"))
+            params[part.slice(1)] = path[index];
+        else if (part !== path[index])
+            return undefined;
+    }
+    return params;
 }
 export function parseListQuery(search, allowedSorts, defaults = { perPage: 20, maxPerPage: 100 }) {
     const integer = (key, fallback, max) => {
@@ -47,12 +132,19 @@ export function parseListQuery(search, allowedSorts, defaults = { perPage: 20, m
     };
     const sort = search.get("sort") ?? allowedSorts[0];
     const direction = search.get("direction") ?? "asc";
-    if ((sort !== undefined && !allowedSorts.includes(sort)) || !["asc", "desc"].includes(direction)) {
+    if ((sort !== undefined && !allowedSorts.includes(sort)) ||
+        !["asc", "desc"].includes(direction)) {
         throw new HttpError(422, "invalid_query", "Invalid sorting.");
     }
     const page = integer("page", 1, 1_000_000);
     const perPage = integer("per_page", defaults.perPage, defaults.maxPerPage);
-    return { page, perPage, offset: (page - 1) * perPage, sort, direction: direction };
+    return {
+        page,
+        perPage,
+        offset: (page - 1) * perPage,
+        sort,
+        direction: direction,
+    };
 }
 export async function readJsonBody(request, maxBytes = 1_048_576) {
     if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)

package/dist/modules/runtime/runtime.provider.d.ts

@@ -1,16 +1,39 @@
 export interface ModuleProvider<T = unknown> {
     name: string;
     dependencies?: readonly string[];
+    token?: ModuleToken<T>;
+    dependencyTokens?: readonly ModuleToken<any>[];
     create(providers: ReadonlyMap<string, unknown>): T;
     start?(provider: T, signal: AbortSignal): void | Promise<void>;
     stop?(provider: T): void | Promise<void>;
 }
+export interface ModuleToken<T> {
+    readonly name: string;
+    readonly key: symbol;
+    readonly valueType?: (value: T) => T;
+}
+type ModuleValues<Tokens extends readonly ModuleToken<any>[]> = {
+    [Index in keyof Tokens]: Tokens[Index] extends ModuleToken<infer Value> ? Value : never;
+};
+export interface TypedModuleDefinition<T, Tokens extends readonly ModuleToken<any>[]> {
+    token: ModuleToken<T>;
+    dependencies: Tokens;
+    create(...providers: ModuleValues<Tokens>): T;
+    start?(provider: T, signal: AbortSignal): void | Promise<void>;
+    stop?(provider: T): void | Promise<void>;
+}
+export declare function createModuleToken<T>(name: string): ModuleToken<T>;
+export declare function defineModuleProvider<T, const Tokens extends readonly ModuleToken<any>[]>(definition: TypedModuleDefinition<T, Tokens>): ModuleProvider<T>;
 export declare function composeModules(modules: readonly ModuleProvider<any>[], options?: {
     startupTimeoutMs?: number;
     shutdownTimeoutMs?: number;
 }): {
     readonly state: "created" | "starting" | "ready" | "stopping" | "stopped" | "failed";
-    get<T>(name: string): T;
+    get: {
+        <T>(token: ModuleToken<T>): T;
+        <T>(name: string): T;
+    };
     start(): Promise<void>;
     stop(): Promise<void>;
 };
+export {};

package/dist/modules/runtime/runtime.provider.js

@@ -1,3 +1,22 @@
+export function createModuleToken(name) {
+    if (!name.trim())
+        throw new Error("A module token needs a name.");
+    return { name, key: Symbol(name) };
+}
+export function defineModuleProvider(definition) {
+    return {
+        name: definition.token.name,
+        token: definition.token,
+        dependencyTokens: definition.dependencies,
+        dependencies: definition.dependencies.map((token) => token.name),
+        create(providers) {
+            const values = definition.dependencies.map((token) => providers.get(token.name));
+            return definition.create(...values);
+        },
+        start: definition.start,
+        stop: definition.stop,
+    };
+}
 export function composeModules(modules, options = {}) {
     const startupTimeoutMs = options.startupTimeoutMs ?? 30_000;
     if (!Number.isSafeInteger(startupTimeoutMs) || startupTimeoutMs < 1)
@@ -9,19 +28,34 @@ export function composeModules(modules, options = {}) {
     if (pending.size !== modules.length)
         throw new Error("Duplicate module name.");
     const providers = new Map();
+    const tokens = new Map();
     const ordered = [];
     while (pending.size) {
         const ready = [...pending.values()].find((module) => (module.dependencies ?? []).every((name) => providers.has(name)));
         if (!ready)
             throw new Error("Missing or cyclic module dependencies.");
+        for (const token of ready.dependencyTokens ?? []) {
+            if (tokens.get(token.name) !== token)
+                throw new Error(`Module contract mismatch: ${token.name}`);
+        }
         const dependencies = new Map((ready.dependencies ?? []).map((name) => [name, providers.get(name)]));
         providers.set(ready.name, ready.create(dependencies));
+        if (ready.token)
+            tokens.set(ready.name, ready.token);
         ordered.push(ready);
         pending.delete(ready.name);
     }
     const started = [];
     let state = "created";
     let cleanupPromise;
+    function get(key) {
+        const name = typeof key === "string" ? key : key.name;
+        if (!providers.has(name))
+            throw new Error(`Unknown module: ${name}`);
+        if (typeof key !== "string" && tokens.get(name) !== key)
+            throw new Error(`Module contract mismatch: ${name}`);
+        return providers.get(name);
+    }
     async function cleanup() {
         state = "stopping";
         const failures = [];
@@ -45,12 +79,10 @@ export function composeModules(modules, options = {}) {
             throw new AggregateError(failures, "Module cleanup failed.");
     }
     return {
-        get state() { return state; },
-        get(name) {
-            if (!providers.has(name))
-                throw new Error(`Unknown module: ${name}`);
-            return providers.get(name);
+        get state() {
+            return state;
         },
+        get,
         async start() {
             if (state !== "created")
                 throw new Error("Modules can only start once.");
@@ -92,9 +124,12 @@ export function composeModules(modules, options = {}) {
 async function withinDeadline(work, milliseconds, name, phase = "shutdown") {
     let timer;
     try {
-        await Promise.race([work, new Promise((_, reject) => {
+        await Promise.race([
+            work,
+            new Promise((_, reject) => {
                 timer = setTimeout(() => reject(new Error(`Module ${phase} deadline exceeded: ${name}`)), milliseconds);
-            })]);
+            }),
+        ]);
     }
     finally {
         clearTimeout(timer);

package/dist/modules/validation/validation.provider.js

@@ -12,7 +12,7 @@ export function parseWithSchema(schema, input) {
                 : "_form";
             (fields[path] ??= []).push(issue.message);
         }
-        throw new HttpError(422, "validation_failed", "The submitted data is invalid.", Object.fromEntries(Object.entries(fields)));
+        throw new HttpError(422, "validation_failed", "Validation failed", Object.fromEntries(Object.entries(fields)));
     }
     return result.data;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devxcrew/framework",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "type": "module",
   "exports": {
     ".": {