@decohere/http 0.0.1-dev.116

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

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get ValidationError () {
+        return _anviltypes.ValidationError;
+    },
+    get validateRequest () {
+        return validateRequest;
+    }
+});
+const _ajv = require("ajv");
+const _anviltypes = require("../routing/anvil.types.js");
+const _requestschema = require("./request-schema.js");
+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 _anviltypes.ValidationError("Validation failed", issues);
+    }
+}
+const ajv = new _ajv.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 = (0, _requestschema.buildRouteRequestSchemas)(route);
+        const paramsSchema = (0, _requestschema.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/commonjs/src/providers/fastify.provider.js

@@ -0,0 +1,391 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "FastifyProvider", {
+    enumerable: true,
+    get: function() {
+        return FastifyProvider;
+    }
+});
+const _nodecrypto = require("node:crypto");
+const _promises = require("node:fs/promises");
+const _nodepath = /*#__PURE__*/ _interop_require_default(require("node:path"));
+const _nodestream = require("node:stream");
+const _decorators = require("@decohere/crucible/decorators");
+const _scribe = require("@decohere/scribe");
+const _compress = /*#__PURE__*/ _interop_require_default(require("@fastify/compress"));
+const _cors = /*#__PURE__*/ _interop_require_default(require("@fastify/cors"));
+const _helmet = /*#__PURE__*/ _interop_require_default(require("@fastify/helmet"));
+const _ratelimit = /*#__PURE__*/ _interop_require_default(require("@fastify/rate-limit"));
+const _static = /*#__PURE__*/ _interop_require_default(require("@fastify/static"));
+const _fastify = /*#__PURE__*/ _interop_require_default(require("fastify"));
+const _const = require("../const.js");
+const _httpsecurity = require("../http/http.security.js");
+const _httpcompression = require("../http/http.compression.js");
+const _httpstatic = require("../http/http.static.js");
+const _openapigenerator = require("../openapi/openapi.generator.js");
+const _anviltypes = require("../routing/anvil.types.js");
+const _exceptionfilterhost = require("../routing/filters/exception-filter-host.js");
+const _requestid = require("../routing/middleware/request-id.js");
+const _pathutil = require("../routing/path.util.js");
+const _sseencoder = require("../sse/sse.encoder.js");
+const _ssetypes = require("../sse/sse.types.js");
+function _interop_require_default(obj) {
+    return obj && obj.__esModule ? obj : {
+        default: obj
+    };
+}
+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);
+    };
+}
+class FastifyProvider {
+    provider;
+    router;
+    routeRegistry;
+    httpOptions;
+    exceptionFilterHost;
+    closing;
+    logger = _scribe.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 = (0, _fastify.default)({
+            logger: false,
+            requestIdHeader: _requestid.REQUEST_ID_HEADER,
+            genReqId: ()=>(0, _nodecrypto.randomUUID)(),
+            bodyLimit: httpOptions?.bodyLimit ?? _httpsecurity.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.default, 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, {
+            ..._httpsecurity.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 _httpstatic.staticFiles.resolve(this.httpOptions?.statics ?? [], {
+            nodeEnv: process.env.NODE_ENV,
+            directoryExists: async (directory)=>(await (0, _promises.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 = _httpstatic.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(_static.default, {
+                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", _httpstatic.staticFiles.cacheControlFor(mount, _nodepath.default.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(_httpstatic.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 = _httpstatic.staticFiles.normalizePathname(request.url);
+                if (mount.spaFallback && !fellBack.has(request) && !excluded(normalized) && _httpstatic.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 _httpstatic.staticFiles.apiBoundary({
+            globalPrefix: (0, _pathutil.normalizePrefix)(this.httpOptions?.globalPrefix),
+            openApiPath: this.httpOptions?.openapi == null ? undefined : (0, _openapigenerator.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.default, {
+            global: true,
+            threshold: compressionOptions?.threshold ?? _httpcompression.DEFAULT_COMPRESSION_THRESHOLD,
+            encodings: [
+                ...compressionOptions?.encodings ?? _httpcompression.DEFAULT_COMPRESSION_ENCODINGS
+            ],
+            ...compressionOptions?.types != null && {
+                customTypes: compressionOptions.types
+            },
+            ...compressionOptions?.providerOptions
+        });
+    }
+    async registerCors(corsOptions) {
+        if (corsOptions == null) {
+            return;
+        }
+        await this.provider.register(_cors.default, {
+            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 = (0, _openapigenerator.resolveOpenApiPath)(openapi);
+        const document = (0, _openapigenerator.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 _ssetypes.SseResponse) {
+                return this.sendEventStream(route, reply, response, disconnect);
+            }
+            return response;
+        } catch (error) {
+            const result = this.exceptionFilterHost ? await this.exceptionFilterHost.handle(error, {
+                request: httpRequest
+            }) : new _exceptionfilterhost.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 = (0, _sseencoder.encodeSse)(response.events, {
+            signal: disconnect.signal,
+            heartbeatMs: route.sse?.heartbeatMs ?? _ssetypes.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(_nodestream.Readable.from(guarded));
+    }
+    applyResponseHeaders(reply, httpRequest) {
+        reply.header(_requestid.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 = (0, _requestid.resolveRequestId)(headers, String(fastifyRequest.id ?? ""));
+        return new _anviltypes.HttpRequest({
+            requestId,
+            url,
+            method,
+            params,
+            query,
+            body,
+            headers
+        });
+    }
+}
+FastifyProvider = _ts_decorate([
+    _ts_param(0, (0, _decorators.inject)(_const.RouteRegistryToken)),
+    _ts_param(1, (0, _decorators.inject)(_const.RouterToken)),
+    _ts_param(2, (0, _decorators.inject)(_const.HttpOptionsToken)),
+    _ts_param(3, (0, _decorators.inject)(_const.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/commonjs/src/providers/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./fastify.provider.js"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}

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

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get ForbiddenError () {
+        return ForbiddenError;
+    },
+    get HttpError () {
+        return HttpError;
+    },
+    get HttpRequest () {
+        return HttpRequest;
+    },
+    get InjectedParts () {
+        return InjectedParts;
+    },
+    get RequestParts () {
+        return RequestParts;
+    },
+    get RouteConfigurationError () {
+        return RouteConfigurationError;
+    },
+    get RoutingError () {
+        return RoutingError;
+    },
+    get TransformError () {
+        return TransformError;
+    },
+    get UnauthorizedError () {
+        return UnauthorizedError;
+    },
+    get ValidationError () {
+        return ValidationError;
+    }
+});
+const RequestParts = {
+    query: "query",
+    params: "params",
+    body: "body",
+    principal: "principal",
+    signal: "signal",
+    lastEventId: "lastEventId"
+};
+const InjectedParts = [
+    "principal",
+    "signal",
+    "lastEventId"
+];
+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 = {};
+}
+class RouteConfigurationError extends Error {
+}
+class RoutingError extends Error {
+}
+class TransformError extends Error {
+}
+class HttpError extends Error {
+    status;
+    constructor(message, status){
+        super(message);
+        this.status = status;
+    }
+}
+class UnauthorizedError extends HttpError {
+    constructor(message = "Unauthorized"){
+        super(message, 401);
+    }
+}
+class ForbiddenError extends HttpError {
+    constructor(message = "Forbidden"){
+        super(message, 403);
+    }
+}
+class ValidationError extends HttpError {
+    errors;
+    constructor(message = "Bad Request", errors = []){
+        super(message, 400);
+        this.errors = errors;
+    }
+}

package/commonjs/src/routing/decorators/argument.decorator.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get Argument () {
+        return Argument;
+    },
+    get Param () {
+        return Param;
+    },
+    get Query () {
+        return Query;
+    }
+});
+const _reflection = require("@decohere/core/reflection");
+const _const = require("../../const.js");
+const _anviltypes = require("../anvil.types.js");
+function Query(key) {
+    return Argument({
+        mappingKey: key,
+        argumentLocation: _anviltypes.RequestParts.query
+    });
+}
+function Param(key) {
+    return Argument({
+        mappingKey: key,
+        argumentLocation: _anviltypes.RequestParts.params
+    });
+}
+function Argument(options) {
+    return (target, functionName, argumentIndex)=>{
+        const { mappingKey, argumentLocation, pipes } = options;
+        const func = target[functionName];
+        const meta = {
+            argumentIndex,
+            mappingKey,
+            argumentLocation,
+            pipes
+        };
+        (0, _reflection.defineArgumentMeta)(_const.MetadataKeys.parameter, meta, func, argumentIndex);
+    };
+}