@decohere/http 0.0.1-dev.125 → 0.0.1-dev.5

package/es6/src/openapi/request-schema.js

@@ -1,160 +0,0 @@
-import { isPrimitiveOrDateType } from "@decohere/core/reflection";
-import { InjectedParts } from "../routing/anvil.types.js";
-export function buildRouteRequestSchemas(route) {
-    const queryParams = [];
-    const pathParams = [];
-    let bodySchema;
-    for (const routeArg of route.routeArgs ?? []){
-        if (routeArg.argumentLocation != null && InjectedParts.includes(routeArg.argumentLocation)) {
-            continue;
-        }
-        if (isPrimitiveOrDateType(routeArg.argumentType)) {
-            const location = routeArg.argumentLocation;
-            if (location === "query" || location === "params") {
-                const param = {
-                    name: routeArg.mappingKey ?? "value",
-                    in: location === "params" ? "path" : "query",
-                    required: location === "params",
-                    schema: typeToSchema(routeArg.argumentType.name)
-                };
-                if (location === "params") {
-                    pathParams.push(param);
-                } else {
-                    queryParams.push(param);
-                }
-            }
-            continue;
-        }
-        const parts = objectArgToParts(routeArg);
-        queryParams.push(...parts.queryParams);
-        pathParams.push(...parts.pathParams);
-        if (parts.body != null) {
-            bodySchema = mergeObjectSchemas(bodySchema, parts.body);
-        }
-    }
-    return {
-        queryParams,
-        pathParams,
-        body: bodySchema
-    };
-}
-export function objectArgToParts(routeArg) {
-    const queryParams = [];
-    const pathParams = [];
-    const bodyProperties = {};
-    const bodyRequired = [];
-    const argLocation = routeArg.argumentLocation;
-    for (const [, meta] of routeArg.fieldMap?.entries() ?? []){
-        const location = meta.fieldLocation ?? argLocation;
-        const name = meta.mappingKey || meta.fieldKey;
-        const schema = typeToSchema(meta.fieldType?.name);
-        if (location === "query") {
-            queryParams.push({
-                name,
-                in: "query",
-                required: false,
-                schema
-            });
-        } else if (location === "params") {
-            pathParams.push({
-                name,
-                in: "path",
-                required: true,
-                schema
-            });
-        } else if (location === "body" || location == null && argLocation === "body") {
-            bodyProperties[name] = schema;
-            bodyRequired.push(name);
-        } else if (location == null && argLocation == null) {
-            // Unlocated object fields default to body for OpenAPI (common DTO pattern).
-            bodyProperties[name] = schema;
-            bodyRequired.push(name);
-        }
-    }
-    // Whole-object body argument with no fields still advertises an object body.
-    if (argLocation === "body" && Object.keys(bodyProperties).length === 0) {
-        return {
-            queryParams,
-            pathParams,
-            body: {
-                type: "object",
-                additionalProperties: true
-            }
-        };
-    }
-    const body = Object.keys(bodyProperties).length > 0 ? {
-        type: "object",
-        properties: bodyProperties,
-        required: bodyRequired,
-        additionalProperties: false
-    } : undefined;
-    return {
-        queryParams,
-        pathParams,
-        body
-    };
-}
-export function mergeObjectSchemas(a, b) {
-    if (a == null) {
-        return b;
-    }
-    return {
-        type: "object",
-        properties: {
-            ...a.properties,
-            ...b.properties
-        },
-        required: [
-            ...new Set([
-                ...a.required ?? [],
-                ...b.required ?? []
-            ])
-        ],
-        additionalProperties: false
-    };
-}
-export function typeToSchema(typeName) {
-    switch(typeName){
-        case "Number":
-            return {
-                type: "number"
-            };
-        case "Boolean":
-            return {
-                type: "boolean"
-            };
-        case "Date":
-            return {
-                type: "string",
-                format: "date-time"
-            };
-        case "String":
-            return {
-                type: "string"
-            };
-        default:
-            return {};
-    }
-}
-/** JSON Schema object for required path params (HTTP path values are always strings). */ export function pathParamsToSchema(params) {
-    if (params.length === 0) {
-        return undefined;
-    }
-    const properties = {};
-    const required = [];
-    for (const param of params){
-        properties[param.name] = {
-            type: "string",
-            minLength: 1
-        };
-        if (param.required !== false) {
-            required.push(param.name);
-        }
-    }
-    return {
-        type: "object",
-        properties,
-        required,
-        additionalProperties: true
-    };
-}

package/es6/src/openapi/request-validator.js

@@ -1,71 +0,0 @@
-import { Ajv } from "ajv";
-import { ValidationError } from "../routing/anvil.types.js";
-import { buildRouteRequestSchemas, pathParamsToSchema } from "./request-schema.js";
-export { ValidationError };
-/**
- * Fail-closed request validation from route / OpenAPI / `@Field` metadata.
- * Uses AJV against the same schemas as the OpenAPI generator (no type coercion).
- */ export function validateRequest(route, request) {
-    const { params, body } = getValidators(route);
-    const issues = [];
-    if (params != null) {
-        collectIssues(params, request.params ?? {}, "/params", issues);
-    }
-    if (body != null) {
-        collectIssues(body, request.body, "/body", issues);
-    }
-    if (issues.length > 0) {
-        throw new ValidationError("Validation failed", issues);
-    }
-}
-const ajv = new Ajv({
-    allErrors: true,
-    coerceTypes: false,
-    removeAdditional: false,
-    useDefaults: false,
-    strict: false
-});
-/**
- * Compiled once per route and reused. Compiling per request was slow, and AJV keeps every
- * schema it compiles, so memory grew with traffic (#498).
- */ const validatorsByRoute = new WeakMap();
-function getValidators(route) {
-    let validators = validatorsByRoute.get(route);
-    if (validators == null) {
-        const schemas = buildRouteRequestSchemas(route);
-        const paramsSchema = pathParamsToSchema(schemas.pathParams);
-        validators = {
-            params: paramsSchema != null ? ajv.compile(paramsSchema) : undefined,
-            body: schemas.body != null ? ajv.compile(schemas.body) : undefined
-        };
-        validatorsByRoute.set(route, validators);
-    }
-    return validators;
-}
-function collectIssues(validate, data, rootPath, issues) {
-    if (validate(data)) {
-        return;
-    }
-    for (const err of validate.errors ?? []){
-        issues.push(toIssue(err, rootPath));
-    }
-}
-function toIssue(err, rootPath) {
-    const instance = err.instancePath ?? "";
-    const path = instance.length > 0 ? `${rootPath}${instance}` : rootPath;
-    const message = err.message ?? "is invalid";
-    return {
-        path,
-        message: formatAjvMessage(err, message),
-        keyword: err.keyword
-    };
-}
-function formatAjvMessage(err, fallback) {
-    if (err.keyword === "required" && typeof err.params?.missingProperty === "string") {
-        return `must have required property '${err.params.missingProperty}'`;
-    }
-    if (err.keyword === "additionalProperties" && typeof err.params?.additionalProperty === "string") {
-        return `must NOT have additional property '${err.params.additionalProperty}'`;
-    }
-    return fallback;
-}

package/es6/src/providers/fastify.provider.js

@@ -1,376 +0,0 @@
-function _ts_decorate(decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-function _ts_metadata(k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-}
-function _ts_param(paramIndex, decorator) {
-    return function(target, key) {
-        decorator(target, key, paramIndex);
-    };
-}
-import { randomUUID } from "node:crypto";
-import { stat } from "node:fs/promises";
-import path from "node:path";
-import { Readable } from "node:stream";
-import { inject } from "@decohere/crucible/decorators";
-import { scribe } from "@decohere/scribe";
-import compress from "@fastify/compress";
-import cors from "@fastify/cors";
-import helmet from "@fastify/helmet";
-import rateLimit from "@fastify/rate-limit";
-import fastifyStatic from "@fastify/static";
-import Fastify from "fastify";
-import { ExceptionFilterHostToken, HttpOptionsToken, RouteRegistryToken, RouterToken } from "../const.js";
-import { DEFAULT_HTTP_BODY_LIMIT, DEFAULT_HTTP_RATE_LIMIT } from "../http/http.security.js";
-import { DEFAULT_COMPRESSION_ENCODINGS, DEFAULT_COMPRESSION_THRESHOLD } from "../http/http.compression.js";
-import { staticFiles } from "../http/http.static.js";
-import { generateOpenApiDocument, resolveOpenApiPath } from "../openapi/openapi.generator.js";
-import { HttpRequest } from "../routing/anvil.types.js";
-import { DefaultHttpExceptionFilter } from "../routing/filters/exception-filter-host.js";
-import { REQUEST_ID_HEADER, resolveRequestId } from "../routing/middleware/request-id.js";
-import { normalizePrefix } from "../routing/path.util.js";
-import { encodeSse } from "../sse/sse.encoder.js";
-import { DEFAULT_SSE_HEARTBEAT_MS, SseResponse } from "../sse/sse.types.js";
-export class FastifyProvider {
-    provider;
-    router;
-    routeRegistry;
-    httpOptions;
-    exceptionFilterHost;
-    closing;
-    logger = scribe.logger(FastifyProvider.name);
-    /** One per live `@Sse()` request, so stopping the app can end the streams. */ openStreams = new Set();
-    constructor(routeRegistry, router, httpOptions, exceptionFilterHost){
-        this.routeRegistry = routeRegistry;
-        this.router = router;
-        this.httpOptions = httpOptions;
-        this.exceptionFilterHost = exceptionFilterHost;
-        this.provider = Fastify({
-            logger: false,
-            requestIdHeader: REQUEST_ID_HEADER,
-            genReqId: ()=>randomUUID(),
-            bodyLimit: httpOptions?.bodyLimit ?? DEFAULT_HTTP_BODY_LIMIT
-        });
-    }
-    async start(options) {
-        const statics = await this.resolveStatics();
-        await this.registerHelmet(this.httpOptions?.helmet);
-        await this.registerRateLimit(this.httpOptions?.rateLimit, statics);
-        await this.registerCors(this.httpOptions?.cors);
-        await this.registerCompression(this.httpOptions?.compression);
-        this.registerOpenApi(this.httpOptions);
-        this.registerAllRoutes(this.routeRegistry);
-        for (const mount of statics){
-            await this.registerStatic(mount, statics);
-        }
-        this.closeConnectionsWhileStopping();
-        await this.provider.listen(options);
-        return {
-            addresses: this.addresses
-        };
-    }
-    async stop() {
-        // App stops HTTP before disposing the container, which calls this again.
-        // A stream never finishes on its own, and close() waits for open responses, so end them first.
-        for (const stream of this.openStreams){
-            stream.abort(new Error("The app is stopping"));
-        }
-        this.closing ??= this.provider.close();
-        await this.closing;
-        return {
-            message: "closed"
-        };
-    }
-    async [Symbol.asyncDispose]() {
-        await this.stop();
-    }
-    /**
-	 * Once stopping, tell clients to drop the connection after their response. Otherwise
-	 * a request that was in flight leaves a kept-alive socket that holds `close()` open
-	 * until Node's keep-alive timeout (5s).
-	 */ closeConnectionsWhileStopping() {
-        this.provider.addHook("onSend", async (_request, reply, payload)=>{
-            if (this.closing) reply.header("connection", "close");
-            return payload;
-        });
-    }
-    get addresses() {
-        return this.provider.addresses().filter((a)=>a.family === "IPv4").map((a)=>`http://${a.address}:${a.port}`);
-    }
-    async registerHelmet(helmetOptions) {
-        if (helmetOptions === false) {
-            return;
-        }
-        await this.provider.register(helmet, helmetOptions ?? {});
-    }
-    async registerRateLimit(rateLimitOptions, statics) {
-        if (rateLimitOptions === false) {
-            return;
-        }
-        // Static files are outside the rate limit (ADR 0007). Matched on the route the request
-        // resolved to, not on its URL, so only requests the static plugin serves are exempt.
-        const staticRoutes = new Set(statics.map((mount)=>`${mount.prefix}*`));
-        const userAllowList = rateLimitOptions?.allowList;
-        await this.provider.register(rateLimit, {
-            ...DEFAULT_HTTP_RATE_LIMIT,
-            ...rateLimitOptions,
-            allowList: (request, key)=>{
-                if (staticRoutes.has(request.routeOptions.url ?? "")) return true;
-                if (typeof userAllowList === "function") return userAllowList(request, key);
-                return Array.isArray(userAllowList) && userAllowList.includes(key);
-            }
-        });
-    }
-    async resolveStatics() {
-        return staticFiles.resolve(this.httpOptions?.statics ?? [], {
-            nodeEnv: process.env.NODE_ENV,
-            directoryExists: async (directory)=>(await stat(directory).catch(()=>undefined))?.isDirectory() === true,
-            warn: (message)=>this.logger.warn(message)
-        });
-    }
-    /**
-	 * One encapsulated context per mount: its not-found handler (the SPA fallback) applies to
-	 * paths under the prefix and nowhere else, so an API 404 is never answered with the UI.
-	 */ async registerStatic(mount, mounts) {
-        const withoutSlash = mount.prefix.slice(0, -1);
-        const isRoot = mount.prefix === "/";
-        const excluded = staticFiles.excluder(mount.exclude);
-        const belongsToApi = this.apiBoundary();
-        // Requests that already fell back once: a missing index must be a 404, not a loop.
-        const fellBack = new WeakSet();
-        await this.provider.register(async (scope)=>{
-            await scope.register(fastifyStatic, {
-                root: mount.root,
-                prefix: "/",
-                index: mount.index,
-                dotfiles: "ignore",
-                list: false,
-                redirect: false,
-                etag: true,
-                lastModified: true,
-                // The header is set in setHeaders, per file.
-                cacheControl: false,
-                setHeaders: (reply, filePath)=>{
-                    reply.header("cache-control", staticFiles.cacheControlFor(mount, path.relative(mount.root, filePath)));
-                }
-            });
-            // Excluded paths are not served at all: not as a file, not as the fallback.
-            scope.addHook("onRequest", async (request, reply)=>{
-                if (excluded(staticFiles.normalizePathname(request.url))) {
-                    return reply.callNotFound();
-                }
-            });
-            scope.setNotFoundHandler((request, reply)=>{
-                const [pathname = "", query] = request.url.split("?");
-                const readOnly = request.method === "GET" || request.method === "HEAD";
-                // `/ui` goes to `/ui/`. A request for it reaches the root mount's handler instead
-                // when there is one, so that handler redirects for the other mounts too.
-                const redirectTo = mounts.find((other)=>other.prefix !== "/" && other.prefix.slice(0, -1) === pathname && (isRoot || other === mount));
-                if (readOnly && redirectTo != null) {
-                    return reply.redirect(query == null ? redirectTo.prefix : `${redirectTo.prefix}?${query}`, 301);
-                }
-                const normalized = staticFiles.normalizePathname(request.url);
-                if (mount.spaFallback && !fellBack.has(request) && !excluded(normalized) && staticFiles.shouldFallBack({
-                    method: request.method,
-                    pathname: normalized,
-                    accept: request.headers.accept
-                }, belongsToApi)) {
-                    fellBack.add(request);
-                    return reply.sendFile(mount.index);
-                }
-                return reply.code(404).send({
-                    message: `Route ${request.method}:${pathname} not found`,
-                    error: "Not Found",
-                    statusCode: 404
-                });
-            });
-        }, {
-            prefix: withoutSlash
-        });
-    }
-    /** What the static fallback leaves to the API: the global prefix, else the registered routes. ADR 0007. */ apiBoundary() {
-        return staticFiles.apiBoundary({
-            globalPrefix: normalizePrefix(this.httpOptions?.globalPrefix),
-            openApiPath: this.httpOptions?.openapi == null ? undefined : resolveOpenApiPath(this.httpOptions.openapi),
-            routePaths: [
-                ...this.routeRegistry.routes
-            ].map((route)=>route.path)
-        });
-    }
-    /**
-	 * `@fastify/compress` with best-practice defaults; the plugin owns the policy. Registered
-	 * before any route so every response goes through it, errors and static files included.
-	 * `providerOptions` is merged last, so a user can override any plugin option.
-	 */ async registerCompression(compressionOptions) {
-        if (compressionOptions === false) {
-            return;
-        }
-        await this.provider.register(compress, {
-            global: true,
-            threshold: compressionOptions?.threshold ?? DEFAULT_COMPRESSION_THRESHOLD,
-            encodings: [
-                ...compressionOptions?.encodings ?? DEFAULT_COMPRESSION_ENCODINGS
-            ],
-            ...compressionOptions?.types != null && {
-                customTypes: compressionOptions.types
-            },
-            ...compressionOptions?.providerOptions
-        });
-    }
-    async registerCors(corsOptions) {
-        if (corsOptions == null) {
-            return;
-        }
-        await this.provider.register(cors, {
-            origin: corsOptions.origin,
-            methods: corsOptions.methods,
-            allowedHeaders: corsOptions.allowedHeaders,
-            exposedHeaders: corsOptions.exposedHeaders,
-            credentials: corsOptions.credentials,
-            maxAge: corsOptions.maxAge
-        });
-    }
-    registerOpenApi(httpOptions) {
-        const openapi = httpOptions?.openapi;
-        if (openapi == null) {
-            return;
-        }
-        const path = resolveOpenApiPath(openapi);
-        const document = generateOpenApiDocument(this.routeRegistry, openapi);
-        this.provider.get(path, async (_request, reply)=>{
-            reply.header("content-type", "application/json; charset=utf-8");
-            return document;
-        });
-    }
-    registerAllRoutes(registry) {
-        for (const route of registry.routes){
-            const { key, method, path } = route;
-            this.provider.route({
-                method,
-                url: path,
-                handler: (request, reply)=>this.routeRequest(route, key, request, reply)
-            });
-        }
-    }
-    async routeRequest(route, key, request, reply) {
-        const httpRequest = this.fastifyToRequest(request);
-        const disconnect = this.abortOnDisconnect(reply, httpRequest, route.sse != null);
-        try {
-            const response = await this.router.route(key, httpRequest);
-            if (route.httpCode != null) {
-                reply.status(route.httpCode);
-            }
-            if (route.headers != null) {
-                for (const [name, value] of Object.entries(route.headers)){
-                    reply.header(name, value);
-                }
-            }
-            this.applyResponseHeaders(reply, httpRequest);
-            if (response instanceof SseResponse) {
-                return this.sendEventStream(route, reply, response, disconnect);
-            }
-            return response;
-        } catch (error) {
-            const result = this.exceptionFilterHost ? await this.exceptionFilterHost.handle(error, {
-                request: httpRequest
-            }) : new DefaultHttpExceptionFilter().catch(error, {
-                request: httpRequest
-            });
-            if (result.headers) {
-                for (const [name, value] of Object.entries(result.headers)){
-                    reply.header(name, value);
-                }
-            }
-            this.applyResponseHeaders(reply, httpRequest);
-            // Returned so Fastify waits for the async onSend hooks instead of sending an empty reply of its own.
-            return reply.status(result.status).send(result.body);
-        }
-    }
-    /**
-	 * Gives the handler a signal that aborts when the client goes away before the response
-	 * finished. Streams are also tracked so that stopping the app can abort them.
-	 */ abortOnDisconnect(reply, httpRequest, isStream) {
-        const controller = new AbortController();
-        httpRequest.signal = controller.signal;
-        if (isStream) {
-            if (this.closing) controller.abort(new Error("The app is stopping"));
-            this.openStreams.add(controller);
-        }
-        reply.raw.once("close", ()=>{
-            this.openStreams.delete(controller);
-            if (!reply.raw.writableFinished) {
-                controller.abort(new Error("The client disconnected"));
-            }
-        });
-        return controller;
-    }
-    sendEventStream(route, reply, response, disconnect) {
-        let started = false;
-        const release = ()=>{
-            response.release().catch((error)=>{
-                this.logger.error("Releasing the request scope of an SSE stream failed", error);
-            });
-        };
-        const frames = encodeSse(response.events, {
-            signal: disconnect.signal,
-            heartbeatMs: route.sse?.heartbeatMs ?? DEFAULT_SSE_HEARTBEAT_MS,
-            onProducerStopped: (stopped)=>void stopped.then(release)
-        });
-        const guarded = async function*() {
-            started = true;
-            yield* frames;
-        }();
-        // Never pulled if the client left first, in which case nothing else would release the scope.
-        reply.raw.once("close", ()=>{
-            if (!started) release();
-        });
-        return reply.status(route.httpCode ?? 200).header("content-type", "text/event-stream; charset=utf-8").header("cache-control", "no-cache, no-transform").header("x-accel-buffering", "no")// A stream owns its connection; closing it afterwards lets app stop finish at once instead of waiting out keep-alive.
-        .header("connection", "close").send(Readable.from(guarded));
-    }
-    applyResponseHeaders(reply, httpRequest) {
-        reply.header(REQUEST_ID_HEADER, httpRequest.requestId);
-        for (const [name, value] of Object.entries(httpRequest.responseHeaders)){
-            reply.header(name, value);
-        }
-    }
-    fastifyToRequest(fastifyRequest) {
-        const method = fastifyRequest.method;
-        const url = fastifyRequest.url;
-        const params = fastifyRequest.params;
-        const query = fastifyRequest.query;
-        const body = fastifyRequest.body ?? {};
-        const headers = {};
-        for (const [key, value] of Object.entries(fastifyRequest.headers)){
-            if (typeof value === "string") {
-                headers[key.toLowerCase()] = value;
-            }
-        }
-        const requestId = resolveRequestId(headers, String(fastifyRequest.id ?? ""));
-        return new HttpRequest({
-            requestId,
-            url,
-            method,
-            params,
-            query,
-            body,
-            headers
-        });
-    }
-}
-FastifyProvider = _ts_decorate([
-    _ts_param(0, inject(RouteRegistryToken)),
-    _ts_param(1, inject(RouterToken)),
-    _ts_param(2, inject(HttpOptionsToken)),
-    _ts_param(3, inject(ExceptionFilterHostToken)),
-    _ts_metadata("design:type", Function),
-    _ts_metadata("design:paramtypes", [
-        typeof RouteRegistry === "undefined" ? Object : RouteRegistry,
-        typeof Router === "undefined" ? Object : Router,
-        typeof HttpOptions === "undefined" ? Object : HttpOptions,
-        typeof ExceptionFilterHost === "undefined" ? Object : ExceptionFilterHost
-    ])
-], FastifyProvider);

package/es6/src/providers/index.js

@@ -1 +0,0 @@
-export * from "./fastify.provider.js";

package/es6/src/routing/anvil.types.js

@@ -1,57 +0,0 @@
-export const RequestParts = {
-    query: "query",
-    params: "params",
-    body: "body",
-    principal: "principal",
-    signal: "signal",
-    lastEventId: "lastEventId"
-};
-/** Argument locations filled by the HTTP package itself rather than read from the request payload. */ export const InjectedParts = [
-    "principal",
-    "signal",
-    "lastEventId"
-];
-export class HttpRequest {
-    constructor(data){
-        Object.assign(this, data);
-    }
-    requestId = "";
-    url;
-    method;
-    params = {};
-    query = {};
-    body;
-    headers = {};
-    /** Aborts when the client disconnects or the app stops. Never aborts if the provider cannot tell. */ signal = new AbortController().signal;
-    /** Outbound headers set by middleware; applied by the HTTP provider. */ responseHeaders = {};
-}
-export class RouteConfigurationError extends Error {
-}
-export class RoutingError extends Error {
-}
-export class TransformError extends Error {
-}
-export class HttpError extends Error {
-    status;
-    constructor(message, status){
-        super(message);
-        this.status = status;
-    }
-}
-export class UnauthorizedError extends HttpError {
-    constructor(message = "Unauthorized"){
-        super(message, 401);
-    }
-}
-export class ForbiddenError extends HttpError {
-    constructor(message = "Forbidden"){
-        super(message, 403);
-    }
-}
-export class ValidationError extends HttpError {
-    errors;
-    constructor(message = "Bad Request", errors = []){
-        super(message, 400);
-        this.errors = errors;
-    }
-}