@decohere/http 0.0.1-dev.116

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

@@ -0,0 +1,57 @@
+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;
+    }
+}

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

@@ -0,0 +1,28 @@
+import { defineArgumentMeta } from "@decohere/core/reflection";
+import { MetadataKeys } from "../../const.js";
+import { RequestParts } from "../anvil.types.js";
+export function Query(key) {
+    return Argument({
+        mappingKey: key,
+        argumentLocation: RequestParts.query
+    });
+}
+export function Param(key) {
+    return Argument({
+        mappingKey: key,
+        argumentLocation: RequestParts.params
+    });
+}
+export function Argument(options) {
+    return (target, functionName, argumentIndex)=>{
+        const { mappingKey, argumentLocation, pipes } = options;
+        const func = target[functionName];
+        const meta = {
+            argumentIndex,
+            mappingKey,
+            argumentLocation,
+            pipes
+        };
+        defineArgumentMeta(MetadataKeys.parameter, meta, func, argumentIndex);
+    };
+}

package/es6/src/routing/decorators/auth.decorator.js

@@ -0,0 +1,58 @@
+import { defineArgumentMeta, defineMeta, getMeta } from "@decohere/core/reflection";
+import { MetadataKeys } from "../../const.js";
+/**
+ * Require the principal to be able to perform `action` on `subject`.
+ * Uses an IAuthorizationService (e.g. CaslAuthorizationService) registered in DI.
+ * When applied to a class, all methods inherit the constraint.
+ * When applied to a method, it takes precedence over the class-level decorator.
+ *
+ * @example
+ * \@Authorize("delete", "Article")
+ * \@Authorize("manage", "all")
+ */ export function Authorize(action, subject = "all") {
+    const options = {
+        action,
+        subject
+    };
+    return (target, methodName, _descriptor)=>{
+        if (methodName) {
+            const fn = target[methodName];
+            defineMeta(MetadataKeys.authorize, options, fn);
+        } else {
+            defineMeta(MetadataKeys.authorize, options, target.prototype);
+        }
+    };
+}
+/**
+ * Opt a specific route method out of authentication, even when the controller
+ * class is decorated with @Authorize.
+ */ export function AllowAnonymous() {
+    return (target, methodName, _descriptor)=>{
+        const fn = target[methodName];
+        defineMeta(MetadataKeys.allowAnonymous, true, fn);
+    };
+}
+/** Read the effective @Authorize options for a handler function. */ export function getAuthorizeOptions(controllerPrototype, handlerFn) {
+    // Method-level overrides class-level
+    const methodLevel = getMeta(MetadataKeys.authorize, handlerFn);
+    if (methodLevel !== undefined) return methodLevel;
+    return getMeta(MetadataKeys.authorize, controllerPrototype);
+}
+/** Returns true only when the handler is explicitly marked @AllowAnonymous. */ export function isAllowAnonymous(_controllerPrototype, handlerFn) {
+    return getMeta(MetadataKeys.allowAnonymous, handlerFn) === true;
+}
+/**
+ * Parameter decorator — injects the authenticated Principal into this argument.
+ * The argument resolver will supply the principal verified during the auth step.
+ */ export function CurrentUser() {
+    return (target, propertyKey, parameterIndex)=>{
+        const fn = target[propertyKey];
+        const meta = {
+            argumentIndex: parameterIndex,
+            argumentLocation: "principal",
+            mappingKey: undefined,
+            pipes: []
+        };
+        defineArgumentMeta(MetadataKeys.parameter, meta, fn, parameterIndex);
+    };
+}

package/es6/src/routing/decorators/controller.decorator.js

@@ -0,0 +1,6 @@
+import { MetadataKeys } from "../../const.js";
+export function Controller(options) {
+    return (target)=>{
+        Reflect.defineMetadata(MetadataKeys.controller, options, target.prototype);
+    };
+}

package/es6/src/routing/decorators/field.decorator.js

@@ -0,0 +1,15 @@
+import { defineMeta, getFieldType, getMeta } from "@decohere/core/reflection";
+import { MetadataKeys } from "../../const.js";
+export function Field(fieldLocation, mappingKey) {
+    return (target, fieldName)=>{
+        const fieldMap = getMeta(MetadataKeys.fieldMap, target) ?? new Map();
+        const fieldType = getFieldType(target, fieldName);
+        fieldMap.set(fieldName, {
+            fieldKey: fieldName,
+            mappingKey,
+            fieldType,
+            fieldLocation
+        });
+        defineMeta(MetadataKeys.fieldMap, fieldMap, target);
+    };
+}

package/es6/src/routing/decorators/index.js

@@ -0,0 +1,7 @@
+export * from "./argument.decorator.js";
+export * from "./auth.decorator.js";
+export * from "./controller.decorator.js";
+export * from "./field.decorator.js";
+export * from "./request.decorator.js";
+export * from "./response.decorator.js";
+export * from "./route.decorator.js";

package/es6/src/routing/decorators/request.decorator.js

@@ -0,0 +1,24 @@
+import { defineMeta, getFields, getFieldType, getMeta } from "@decohere/core/reflection";
+import { MetadataKeys } from "../../const.js";
+/**
+ * Used to map a request object to route params
+ * @param mappingKey
+ * @returns
+ */ export function Request(mappingKey) {
+    return (target)=>{
+        const inst = new target();
+        const fieldMap = getMeta(MetadataKeys.fieldMap, target.prototype) ?? new Map();
+        const fields = getFields(inst);
+        for (const field of fields){
+            const fieldType = getFieldType(target.prototype, field.key);
+            const overrides = fieldMap.get(field.key);
+            fieldMap.set(field.key, {
+                fieldKey: field.key,
+                mappingKey: overrides?.mappingKey ?? field.key,
+                fieldType: overrides?.fieldType ?? fieldType,
+                fieldLocation: overrides?.fieldLocation ?? mappingKey
+            });
+        }
+        defineMeta(MetadataKeys.fieldMap, fieldMap, target.prototype);
+    };
+}

package/es6/src/routing/decorators/response.decorator.js

@@ -0,0 +1,16 @@
+import { defineMeta, getMeta } from "@decohere/core/reflection";
+import { MetadataKeys } from "../../const.js";
+/** Set the HTTP status code returned on a successful handler response. */ export function HttpCode(statusCode) {
+    return (_target, _methodName, descriptor)=>{
+        defineMeta(MetadataKeys.httpCode, statusCode, descriptor.value);
+    };
+}
+/** Set a response header on a successful handler response. Stackable. */ export function Header(name, value) {
+    return (_target, _methodName, descriptor)=>{
+        const existing = getMeta(MetadataKeys.headers, descriptor.value) ?? {};
+        defineMeta(MetadataKeys.headers, {
+            ...existing,
+            [name]: value
+        }, descriptor.value);
+    };
+}

package/es6/src/routing/decorators/route.decorator.js

@@ -0,0 +1,37 @@
+import { defineMeta } from "@decohere/core/reflection";
+import { HTTPMethods, MetadataKeys } from "../../const.js";
+import { RouteConfigurationError } from "../anvil.types.js";
+export function Get(path) {
+    return routeDecorator(HTTPMethods.GET, path);
+}
+export function Post(path) {
+    return routeDecorator(HTTPMethods.POST, path);
+}
+export function Put(path) {
+    return routeDecorator(HTTPMethods.PUT, path);
+}
+export function Patch(path) {
+    return routeDecorator(HTTPMethods.PATCH, path);
+}
+export function Delete(path) {
+    return routeDecorator(HTTPMethods.DELETE, path);
+}
+export function Route(method, path) {
+    return routeDecorator(method, path);
+}
+/**
+ * Store method + relative path only. Controller / global prefixes are applied
+ * at registration time in RouteRegistry (avoids TS decorator-order issues).
+ */ function routeDecorator(method, path = "") {
+    return (targetClass, functionName, descriptor)=>{
+        if (path !== "" && !path.startsWith("/")) {
+            throw new RouteConfigurationError(`Error configuring routes. Path defined in controller ${targetClass.constructor.name}.${functionName}() should start '/'`);
+        }
+        const { value: handler } = descriptor;
+        const routeConfig = {
+            method,
+            path
+        };
+        defineMeta(MetadataKeys.route, routeConfig, handler);
+    };
+}

package/es6/src/routing/filters/exception-filter-host.js

@@ -0,0 +1,127 @@
+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 { LifetimeScopeToken } from "@decohere/crucible";
+import { inject, injectable } from "@decohere/crucible/decorators";
+import { scribe } from "@decohere/scribe";
+import { HttpOptionsToken } from "../../const.js";
+import { HttpError, ValidationError } from "../anvil.types.js";
+import { getCatchTypes } from "./exception-filter.js";
+export class DefaultHttpExceptionFilter {
+    logger = scribe.logger(DefaultHttpExceptionFilter.name);
+    catch(error, _ctx) {
+        if (error instanceof ValidationError) {
+            return {
+                status: 400,
+                body: {
+                    statusCode: 400,
+                    error: "Bad Request",
+                    message: error.message,
+                    errors: error.errors
+                }
+            };
+        }
+        if (error instanceof HttpError) {
+            // Never expose internal auth failure details (header shape, issuer, etc.) to clients.
+            if (error.status === 401) {
+                this.logger.warn(error.message);
+                return {
+                    status: 401,
+                    body: {
+                        message: "Unauthorized"
+                    }
+                };
+            }
+            // Sanitize only true 500s. Keep intentional 503 probe messages (e.g. /ready).
+            if (error.status === 500) {
+                this.logger.error(error.message);
+                return {
+                    status: 500,
+                    body: {
+                        message: "Internal Server Error"
+                    }
+                };
+            }
+            return {
+                status: error.status,
+                body: {
+                    message: error.message
+                }
+            };
+        }
+        if (error instanceof Error) {
+            this.logger.error(error.message, error.stack);
+            return {
+                status: 500,
+                body: {
+                    message: "Internal Server Error"
+                }
+            };
+        }
+        return {
+            status: 500,
+            body: {
+                message: "Internal Server Error"
+            }
+        };
+    }
+}
+DefaultHttpExceptionFilter = _ts_decorate([
+    injectable()
+], DefaultHttpExceptionFilter);
+export class ExceptionFilterHost {
+    options;
+    scope;
+    filters;
+    constructor(options, scope){
+        this.options = options;
+        this.scope = scope;
+    }
+    async handle(error, ctx) {
+        for (const filter of this.getFilters()){
+            const filterType = filter.constructor;
+            const types = getCatchTypes(filterType);
+            if (types.length === 0 || types.some((t)=>error instanceof t)) {
+                return await filter.catch(error, ctx);
+            }
+        }
+        return new DefaultHttpExceptionFilter().catch(error, ctx);
+    }
+    getFilters() {
+        if (this.filters != null) {
+            return this.filters;
+        }
+        const custom = this.options?.filterTypes.map((type)=>{
+            if (this.scope == null) {
+                return new type();
+            }
+            return this.scope.resolve(type);
+        }) ?? [];
+        this.filters = [
+            ...custom,
+            new DefaultHttpExceptionFilter()
+        ];
+        return this.filters;
+    }
+}
+ExceptionFilterHost = _ts_decorate([
+    injectable(),
+    _ts_param(0, inject(HttpOptionsToken)),
+    _ts_param(1, inject(LifetimeScopeToken)),
+    _ts_metadata("design:type", Function),
+    _ts_metadata("design:paramtypes", [
+        typeof HttpOptions === "undefined" ? Object : HttpOptions,
+        typeof LifetimeScope === "undefined" ? Object : LifetimeScope
+    ])
+], ExceptionFilterHost);

package/es6/src/routing/filters/exception-filter.js

@@ -0,0 +1,10 @@
+import { defineMeta, getMeta } from "@decohere/core/reflection";
+import { MetadataKeys } from "../../const.js";
+/** Declare which error types this filter handles. Empty = catch-all. */ export function Catch(...types) {
+    return (target)=>{
+        defineMeta(MetadataKeys.catch, types, target);
+    };
+}
+export function getCatchTypes(filterType) {
+    return getMeta(MetadataKeys.catch, filterType) ?? [];
+}

package/es6/src/routing/index.js

@@ -0,0 +1,8 @@
+export * from "./anvil.types.js";
+export * from "./decorators/index.js";
+export * from "./filters/exception-filter.js";
+export * from "./filters/exception-filter-host.js";
+export * from "./middleware/http-access-log.middleware.js";
+export * from "./middleware/middleware.js";
+export * from "./middleware/request-id.js";
+export * from "./pipes/index.js";

package/es6/src/routing/middleware/http-access-log.middleware.js

@@ -0,0 +1,37 @@
+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;
+}
+import { injectable } from "@decohere/crucible/decorators";
+import { scribe } from "@decohere/scribe";
+import { HttpError } from "../anvil.types.js";
+import { REQUEST_ID_HEADER } from "./request-id.js";
+export class HttpAccessLogMiddleware {
+    async use(ctx, next) {
+        const logger = scribe.logger(HttpAccessLogMiddleware.name);
+        const start = performance.now();
+        ctx.request.responseHeaders[REQUEST_ID_HEADER] = ctx.request.requestId;
+        let status = ctx.route.httpCode ?? 200;
+        try {
+            return await next();
+        } catch (error) {
+            status = error instanceof HttpError ? error.status : 500;
+            throw error;
+        } finally{
+            const durationMs = Math.round(performance.now() - start);
+            logger.info({
+                msg: "access",
+                method: ctx.request.method,
+                path: ctx.request.url,
+                status,
+                durationMs,
+                requestId: ctx.request.requestId
+            });
+        }
+    }
+}
+HttpAccessLogMiddleware = _ts_decorate([
+    injectable()
+], HttpAccessLogMiddleware);

package/es6/src/routing/middleware/middleware.js

@@ -0,0 +1,10 @@
+/** Compose middleware around a terminal handler; returns the handler result. */ export function composeMiddleware(middlewares, handler, ctx) {
+    const dispatch = (index)=>{
+        if (index >= middlewares.length) {
+            return handler();
+        }
+        const middleware = middlewares[index];
+        return middleware.use(ctx, ()=>dispatch(index + 1));
+    };
+    return dispatch(0);
+}

package/es6/src/routing/middleware/request-id.js

@@ -0,0 +1,14 @@
+import { randomUUID } from "node:crypto";
+/** Canonical inbound/outbound request id header (lowercase). */ export const REQUEST_ID_HEADER = "x-request-id";
+/**
+ * Prefer an inbound `x-request-id`, then an existing id, otherwise generate one.
+ */ export function resolveRequestId(headers, fallback) {
+    const fromHeader = headers[REQUEST_ID_HEADER]?.trim();
+    if (fromHeader) {
+        return fromHeader;
+    }
+    if (fallback?.trim()) {
+        return fallback.trim();
+    }
+    return randomUUID();
+}

package/es6/src/routing/path.util.js

@@ -0,0 +1,33 @@
+/** Normalize a prefix to `/foo` form with no trailing slash. Empty → `""`. */ export function normalizePrefix(prefix) {
+    if (prefix == null || prefix === "" || prefix === "/") {
+        return "";
+    }
+    const withSlash = prefix.startsWith("/") ? prefix : `/${prefix}`;
+    return withSlash.replace(/\/+$/, "");
+}
+/**
+ * Join a controller prefix with a method-relative route path.
+ * Preserves `@Get("/")` trailing-slash semantics (`/hello` + `/` → `/hello/`).
+ */ export function joinRoutePath(prefix, routePath) {
+    const p = normalizePrefix(prefix);
+    if (routePath === "" || routePath == null) {
+        return p === "" ? "/" : p;
+    }
+    if (routePath === "/") {
+        return p === "" ? "/" : `${p}/`;
+    }
+    if (!routePath.startsWith("/")) {
+        throw new Error(`Route path must start with '/': ${routePath}`);
+    }
+    return `${p}${routePath}`;
+}
+/** Prepend a global prefix onto an already-joined controller route path. */ export function applyGlobalPrefix(globalPrefix, path) {
+    const g = normalizePrefix(globalPrefix);
+    if (g === "") {
+        return path === "" ? "/" : path;
+    }
+    if (path === "/") {
+        return `${g}/`;
+    }
+    return `${g}${path.startsWith("/") ? path : `/${path}`}`;
+}

package/es6/src/routing/pipes/index.js

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

package/es6/src/routing/pipes/pipes.js

@@ -0,0 +1,118 @@
+import { isDateType } from "@decohere/core/reflection";
+import { TransformError, ValidationError } from "../anvil.types.js";
+const invalidBooleanIssue = {
+    path: "/value",
+    message: "Invalid boolean",
+    keyword: "type"
+};
+const invalidNumberIssue = {
+    path: "/value",
+    message: "Invalid number",
+    keyword: "type"
+};
+const invalidDateIssue = {
+    path: "/value",
+    message: "Invalid date",
+    keyword: "format"
+};
+export class Pipe {
+}
+export class BooleanPipe extends Pipe {
+    transform(value, _context) {
+        if (typeof value === "boolean") {
+            return value;
+        }
+        const normalized = typeof value === "string" ? value.trim().toLowerCase() : value;
+        switch(normalized){
+            case "true":
+            case "1":
+            case 1:
+                return true;
+            case "false":
+            case "0":
+            case 0:
+                return false;
+            default:
+                throw new ValidationError("Validation failed", [
+                    invalidBooleanIssue
+                ]);
+        }
+    }
+}
+export class DatePipe extends Pipe {
+    transform(value, _context) {
+        if (value instanceof Date) {
+            if (Number.isNaN(value.getTime())) {
+                throw new ValidationError("Validation failed", [
+                    invalidDateIssue
+                ]);
+            }
+            return value;
+        }
+        if (typeof value === "string") {
+            const trimmed = value.trim();
+            if (trimmed === "") {
+                throw new ValidationError("Validation failed", [
+                    invalidDateIssue
+                ]);
+            }
+            if (/^-?\d+(\.\d+)?$/.test(trimmed)) {
+                return new Date(Number(trimmed));
+            }
+            const parsed = new Date(trimmed);
+            if (Number.isNaN(parsed.getTime())) {
+                throw new ValidationError("Validation failed", [
+                    invalidDateIssue
+                ]);
+            }
+            return parsed;
+        }
+        if (typeof value === "number" && !Number.isNaN(value)) {
+            return new Date(value);
+        }
+        throw new ValidationError("Validation failed", [
+            invalidDateIssue
+        ]);
+    }
+}
+export class JsonPipe extends Pipe {
+    transform(value, context) {
+        try {
+            const obj = JSON.parse(value, (fieldKey, fieldValue)=>{
+                const val = this.reviver(context?.fieldTypes, fieldKey, fieldValue);
+                return val;
+            });
+            return obj;
+        } catch (err) {
+            throw new TransformError(`Error parsing json ${err}`);
+        }
+    }
+    reviver(fieldTypes, fieldKey, value) {
+        if (!fieldKey) {
+            return value;
+        }
+        if (!fieldTypes) {
+            return value;
+        }
+        const fieldType = fieldTypes[fieldKey];
+        if (fieldType == null) {
+            return value;
+        }
+        if (!isDateType(fieldType)) {
+            return value;
+        }
+        return new Date(value.toString());
+    }
+}
+export class NumberPipe extends Pipe {
+    /** Finite numbers only. Blank or non-numeric input is a 400, not `undefined` (#503). */ transform(value, _context) {
+        const text = typeof value === "number" ? null : String(value).trim();
+        const number = text == null ? value : text === "" ? Number.NaN : Number(text);
+        if (!Number.isFinite(number)) {
+            throw new ValidationError("Validation failed", [
+                invalidNumberIssue
+            ]);
+        }
+        return number;
+    }
+}

package/es6/src/routing/services/index.js

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