@nocobase/app-server 0.11.1-alpha.4 → 2.0.0-beta.1

package/dist/router/api-error.d.ts

@@ -0,0 +1,171 @@
+import type { Context, MiddlewareHandler, NotFoundHandler } from 'hono';
+import type { ContentfulStatusCode } from 'hono/utils/http-status';
+/**
+ * The error categories an `/api` response may report, with the HTTP status each one maps to. The names and mapping are
+ * Google's canonical error codes (AIP-193), so a client branches on a fixed, documented set rather than on whatever
+ * each plugin invents. `reason` carries the plugin-specific detail.
+ */
+export declare const apiErrorStatusCodes: {
+    readonly INVALID_ARGUMENT: 400;
+    readonly FAILED_PRECONDITION: 400;
+    readonly OUT_OF_RANGE: 400;
+    readonly UNAUTHENTICATED: 401;
+    readonly PERMISSION_DENIED: 403;
+    readonly NOT_FOUND: 404;
+    readonly ALREADY_EXISTS: 409;
+    readonly ABORTED: 409;
+    readonly RESOURCE_EXHAUSTED: 429;
+    readonly INTERNAL: 500;
+    readonly UNIMPLEMENTED: 501;
+    readonly UNAVAILABLE: 503;
+    readonly DEADLINE_EXCEEDED: 504;
+};
+export type ApiErrorStatus = keyof typeof apiErrorStatusCodes;
+/** The error reasons and domain the framework itself reports. Plugins use their own domain and reasons. */
+export declare const appErrorDomain = "app";
+export interface ApiLocalizedMessage {
+    readonly locale: string;
+    readonly message: string;
+}
+/** One invalid field in a request, as AIP-193's `BadRequest.FieldViolation`. */
+export interface ApiFieldViolation {
+    /** Path to the field, such as `releaseId` or `items[2].name`. */
+    readonly field: string;
+    readonly description: string;
+    readonly reason?: string;
+}
+export interface ApiErrorOptions {
+    readonly status: ApiErrorStatus;
+    /** What went wrong, in UPPER_SNAKE_CASE, unique within `domain`. Clients branch on `reason`, never on `message`. */
+    readonly reason: string;
+    /** Who defined `reason`: the plugin's URL namespace, such as `hub`, or `app` for the framework. */
+    readonly domain: string;
+    /** Developer-facing English description. Never shown to end users and never relied on by clients. */
+    readonly message: string;
+    /** User-facing text already translated by the handler. */
+    readonly localizedMessage?: ApiLocalizedMessage;
+    readonly fieldViolations?: readonly ApiFieldViolation[];
+    /** Further machine-readable facts about this occurrence. Values must be JSON-serializable. */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    /**
+     * The HTTP status to answer with when a protocol requires one the status table does not produce, such as 413 or
+     * 415. Leave unset otherwise: the status from `status` is what clients expect.
+     */
+    readonly httpStatus?: ContentfulStatusCode;
+    readonly cause?: unknown;
+}
+export interface ApiErrorPayload {
+    readonly code: number;
+    readonly status: ApiErrorStatus;
+    readonly reason: string;
+    readonly domain: string;
+    readonly message: string;
+    readonly localizedMessage?: ApiLocalizedMessage;
+    readonly fieldViolations?: readonly ApiFieldViolation[];
+    readonly metadata?: Readonly<Record<string, unknown>>;
+    readonly requestId?: string;
+}
+/** The body of every failed `/api` response. */
+export interface ApiErrorBody {
+    readonly error: ApiErrorPayload;
+}
+/**
+ * An error a route throws to answer with the standard `/api` error body.
+ *
+ * ```ts
+ * throw new ApiError({ status: 'NOT_FOUND', reason: 'APP_NOT_FOUND', domain: 'hub', message: `App ${id} was not found.` });
+ * ```
+ */
+export declare class ApiError extends Error {
+    /** The HTTP status of the response. */
+    readonly code: ContentfulStatusCode;
+    readonly status: ApiErrorStatus;
+    readonly reason: string;
+    readonly domain: string;
+    readonly localizedMessage: ApiLocalizedMessage | undefined;
+    readonly fieldViolations: readonly ApiFieldViolation[] | undefined;
+    readonly metadata: Readonly<Record<string, unknown>> | undefined;
+    constructor(options: ApiErrorOptions);
+    toPayload(requestId?: string): ApiErrorPayload;
+}
+/** The canonical status for an HTTP status code, for errors raised as bare HTTP statuses. */
+export declare function apiErrorStatusFromHttp(code: number): ApiErrorStatus;
+/**
+ * The `ApiError` for an error the framework recognizes, or `undefined` for one it does not:
+ *
+ * - an `ApiError` as it is;
+ * - Hono's `HTTPException`, and any error that carries a 4xx `status` the way Hono's `getResponse()` convention does
+ *   (such as `AuthorizationDeniedError`), with their status and message, and a string `reason` and `domain` on such an
+ *   error kept too;
+ * - a `RepositoryError` whose `status` is not `INTERNAL` (a refused write, a missing record, a version conflict), with
+ *   that status, its code as `reason`, domain `app`, and its `path` and `details` as `metadata`. One that is the
+ *   server's own fault, such as an invalid Policy, is not recognized.
+ */
+export declare function recognizeApiError(error: unknown): ApiError | undefined;
+/**
+ * Convert anything a route threw into an `ApiError`: what `recognizeApiError` recognizes, and anything else as an
+ * unexpected failure answered with a 500 that reveals nothing about its cause.
+ */
+export declare function toApiError(error: unknown): ApiError;
+export declare function apiErrorBody(error: ApiError, requestId?: string): ApiErrorBody;
+/**
+ * The `onError` for a plugin's router: it answers every error `recognizeApiError` recognizes in the standard body and
+ * rethrows the rest, so an enclosing router can still translate it and the application answers an unexpected failure
+ * with an opaque 500. A router that translates its own domain errors does that first and then delegates here. Install
+ * it even though the application renders the same errors: a router tested on a bare Hono has no `/api` handler.
+ */
+export declare function apiErrorHandler(error: unknown, context: Context): Response;
+export declare const apiNotFoundHandler: NotFoundHandler;
+/** One problem a schema reported, as zod and Standard Schema issues are shaped. */
+export interface ApiInputIssue {
+    readonly path: readonly PropertyKey[];
+    readonly message: string;
+    readonly code?: string;
+}
+/** A schema with zod's `safeParse`, matched by shape so the framework does not depend on a zod version. */
+export interface ApiInputSchema<T> {
+    safeParse(value: unknown): {
+        readonly success: true;
+        readonly data: T;
+    } | {
+        readonly success: false;
+        readonly error: {
+            readonly issues: readonly ApiInputIssue[];
+        };
+    };
+}
+/**
+ * Validate request input against a schema, returning the parsed value or throwing a 400 `INVALID_ARGUMENT` that names
+ * every invalid field. Use it inside Hono's `validator()` so handlers read only `context.req.valid(...)`.
+ *
+ * Superseded by `apiValidator(target, schema)`, which answers the same error and also declares the schema in the API
+ * document. Routes not yet migrated keep working with this.
+ */
+export declare function parseApiInput<T>(schema: ApiInputSchema<T>, value: unknown): T;
+/**
+ * The 400 `INVALID_ARGUMENT` with reason `INVALID_INPUT` and one field violation per issue that every input validator
+ * answers. A path segment may be a key or a Standard Schema `{ key }` segment; a `code` on an issue, as zod sets one,
+ * becomes the violation's `reason`.
+ */
+export declare function invalidApiInputError(issues: readonly ApiInputIssueLike[]): ApiError;
+/** An issue as zod and Standard Schema report one, whose path segments may be keys or `{ key }` objects. */
+export interface ApiInputIssueLike {
+    readonly message: string;
+    readonly path?: readonly (PropertyKey | {
+        readonly key: PropertyKey;
+    })[] | undefined;
+}
+export declare const requestIdHeader = "x-request-id";
+declare module 'hono' {
+    interface ContextVariableMap {
+        requestId: string;
+    }
+}
+/**
+ * The id of the current request: an `x-request-id` the caller sent, when it is short and plain enough to log safely,
+ * otherwise a new UUID. The first call per request decides it, so the request log and the response always agree.
+ */
+export declare function getRequestId(context: Context): string;
+/** Echo the request id in the `x-request-id` response header, so a user reporting a failure can quote it. */
+export declare function requestIdMiddleware(): MiddlewareHandler;
+//# sourceMappingURL=api-error.d.ts.map

package/dist/router/api-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-error.d.ts","sourceRoot":"","sources":["../../src/router/api-error.ts"],"names":[],"mappings":"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"}

package/dist/router/api-error.js

@@ -0,0 +1,291 @@
+import { randomUUID } from 'node:crypto';
+import { RepositoryError } from '@nocobase/db';
+import { createMiddleware } from 'hono/factory';
+import { HTTPException } from 'hono/http-exception';
+/**
+ * The error categories an `/api` response may report, with the HTTP status each one maps to. The names and mapping are
+ * Google's canonical error codes (AIP-193), so a client branches on a fixed, documented set rather than on whatever
+ * each plugin invents. `reason` carries the plugin-specific detail.
+ */
+export const apiErrorStatusCodes = Object.freeze({
+    INVALID_ARGUMENT: 400,
+    FAILED_PRECONDITION: 400,
+    OUT_OF_RANGE: 400,
+    UNAUTHENTICATED: 401,
+    PERMISSION_DENIED: 403,
+    NOT_FOUND: 404,
+    ALREADY_EXISTS: 409,
+    ABORTED: 409,
+    RESOURCE_EXHAUSTED: 429,
+    INTERNAL: 500,
+    UNIMPLEMENTED: 501,
+    UNAVAILABLE: 503,
+    DEADLINE_EXCEEDED: 504,
+});
+/** The error reasons and domain the framework itself reports. Plugins use their own domain and reasons. */
+export const appErrorDomain = 'app';
+/**
+ * An error a route throws to answer with the standard `/api` error body.
+ *
+ * ```ts
+ * throw new ApiError({ status: 'NOT_FOUND', reason: 'APP_NOT_FOUND', domain: 'hub', message: `App ${id} was not found.` });
+ * ```
+ */
+export class ApiError extends Error {
+    /** The HTTP status of the response. */
+    code;
+    status;
+    reason;
+    domain;
+    localizedMessage;
+    fieldViolations;
+    metadata;
+    constructor(options) {
+        super(options.message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'ApiError';
+        this.code = options.httpStatus ?? apiErrorStatusCodes[options.status];
+        this.status = options.status;
+        this.reason = options.reason;
+        this.domain = options.domain;
+        this.localizedMessage = options.localizedMessage;
+        this.fieldViolations = options.fieldViolations;
+        this.metadata = options.metadata;
+    }
+    toPayload(requestId) {
+        return {
+            code: this.code,
+            status: this.status,
+            reason: this.reason,
+            domain: this.domain,
+            message: this.message,
+            ...(this.localizedMessage
+                ? { localizedMessage: this.localizedMessage }
+                : {}),
+            ...(this.fieldViolations?.length
+                ? { fieldViolations: this.fieldViolations }
+                : {}),
+            ...(this.metadata ? { metadata: this.metadata } : {}),
+            ...(requestId ? { requestId } : {}),
+        };
+    }
+}
+const statusByHttpCode = {
+    400: 'INVALID_ARGUMENT',
+    401: 'UNAUTHENTICATED',
+    403: 'PERMISSION_DENIED',
+    404: 'NOT_FOUND',
+    409: 'ABORTED',
+    413: 'INVALID_ARGUMENT',
+    415: 'INVALID_ARGUMENT',
+    429: 'RESOURCE_EXHAUSTED',
+    501: 'UNIMPLEMENTED',
+    503: 'UNAVAILABLE',
+    504: 'DEADLINE_EXCEEDED',
+};
+/** The canonical status for an HTTP status code, for errors raised as bare HTTP statuses. */
+export function apiErrorStatusFromHttp(code) {
+    return (statusByHttpCode[code] ?? (code >= 500 ? 'INTERNAL' : 'FAILED_PRECONDITION'));
+}
+/**
+ * The `ApiError` for an error the framework recognizes, or `undefined` for one it does not:
+ *
+ * - an `ApiError` as it is;
+ * - Hono's `HTTPException`, and any error that carries a 4xx `status` the way Hono's `getResponse()` convention does
+ *   (such as `AuthorizationDeniedError`), with their status and message, and a string `reason` and `domain` on such an
+ *   error kept too;
+ * - a `RepositoryError` whose `status` is not `INTERNAL` (a refused write, a missing record, a version conflict), with
+ *   that status, its code as `reason`, domain `app`, and its `path` and `details` as `metadata`. One that is the
+ *   server's own fault, such as an invalid Policy, is not recognized.
+ */
+export function recognizeApiError(error) {
+    if (error instanceof ApiError)
+        return error;
+    if (error instanceof HTTPException) {
+        return new ApiError({
+            status: apiErrorStatusFromHttp(error.status),
+            reason: `HTTP_${error.status}`,
+            domain: appErrorDomain,
+            message: error.message || `Request failed with status ${error.status}.`,
+            httpStatus: error.status,
+            cause: error,
+        });
+    }
+    const repositoryError = repositoryApiError(error);
+    if (repositoryError)
+        return repositoryError;
+    const statusError = readStatusError(error);
+    if (statusError) {
+        return new ApiError({
+            status: apiErrorStatusFromHttp(statusError.status),
+            reason: statusError.reason ?? `HTTP_${statusError.status}`,
+            domain: statusError.domain ?? appErrorDomain,
+            message: statusError.message,
+            httpStatus: statusError.status,
+            cause: error,
+        });
+    }
+    return undefined;
+}
+/**
+ * Convert anything a route threw into an `ApiError`: what `recognizeApiError` recognizes, and anything else as an
+ * unexpected failure answered with a 500 that reveals nothing about its cause.
+ */
+export function toApiError(error) {
+    return (recognizeApiError(error) ??
+        new ApiError({
+            status: 'INTERNAL',
+            reason: 'INTERNAL_ERROR',
+            domain: appErrorDomain,
+            message: 'Internal server error.',
+            cause: error,
+        }));
+}
+function readStatusError(error) {
+    if (!(error instanceof Error) || !('status' in error))
+        return undefined;
+    const { status } = error;
+    if (typeof status !== 'number' || status < 400 || status > 499)
+        return undefined;
+    const fields = error;
+    return {
+        status,
+        message: error.message,
+        ...(typeof fields.reason === 'string' ? { reason: fields.reason } : {}),
+        ...(typeof fields.domain === 'string' ? { domain: fields.domain } : {}),
+    };
+}
+export function apiErrorBody(error, requestId) {
+    return { error: error.toPayload(requestId) };
+}
+/**
+ * Answer with the standard error body for `error`, carrying the request's id; anything unrecognized is an opaque 500.
+ * Framework-internal: plugins answer through `apiErrorHandler`, which rethrows what it does not recognize.
+ */
+function apiErrorResponse(context, error) {
+    const apiError = toApiError(error);
+    return context.json(apiErrorBody(apiError, getRequestId(context)), apiError.code);
+}
+/**
+ * The `onError` for a plugin's router: it answers every error `recognizeApiError` recognizes in the standard body and
+ * rethrows the rest, so an enclosing router can still translate it and the application answers an unexpected failure
+ * with an opaque 500. A router that translates its own domain errors does that first and then delegates here. Install
+ * it even though the application renders the same errors: a router tested on a bare Hono has no `/api` handler.
+ */
+export function apiErrorHandler(error, context) {
+    const known = recognizeApiError(error);
+    if (known)
+        return apiErrorResponse(context, known);
+    throw error;
+}
+export const apiNotFoundHandler = (context) => apiErrorResponse(context, new ApiError({
+    status: 'NOT_FOUND',
+    reason: 'ROUTE_NOT_FOUND',
+    domain: appErrorDomain,
+    message: `No API route matches ${context.req.method} ${context.req.path}.`,
+}));
+/**
+ * Validate request input against a schema, returning the parsed value or throwing a 400 `INVALID_ARGUMENT` that names
+ * every invalid field. Use it inside Hono's `validator()` so handlers read only `context.req.valid(...)`.
+ *
+ * Superseded by `apiValidator(target, schema)`, which answers the same error and also declares the schema in the API
+ * document. Routes not yet migrated keep working with this.
+ */
+export function parseApiInput(schema, value) {
+    const result = schema.safeParse(value);
+    if (result.success)
+        return result.data;
+    throw invalidApiInputError(result.error.issues);
+}
+/**
+ * The 400 `INVALID_ARGUMENT` with reason `INVALID_INPUT` and one field violation per issue that every input validator
+ * answers. A path segment may be a key or a Standard Schema `{ key }` segment; a `code` on an issue, as zod sets one,
+ * becomes the violation's `reason`.
+ */
+export function invalidApiInputError(issues) {
+    return new ApiError({
+        status: 'INVALID_ARGUMENT',
+        reason: 'INVALID_INPUT',
+        domain: appErrorDomain,
+        message: 'The request contains invalid fields.',
+        fieldViolations: issues.map((issue) => {
+            const code = issue.code;
+            return {
+                field: (issue.path ?? [])
+                    .map((segment) => typeof segment === 'object' && segment !== null
+                    ? String(segment.key)
+                    : String(segment))
+                    .join('.'),
+                description: issue.message,
+                ...(typeof code === 'string' && code ? { reason: code } : {}),
+            };
+        }),
+    });
+}
+export const requestIdHeader = 'x-request-id';
+const maxRequestIdLength = 255;
+const requestIdPattern = /^[\w\-=.]+$/;
+/**
+ * The id of the current request: an `x-request-id` the caller sent, when it is short and plain enough to log safely,
+ * otherwise a new UUID. The first call per request decides it, so the request log and the response always agree.
+ */
+export function getRequestId(context) {
+    const existing = context.get('requestId');
+    if (existing)
+        return existing;
+    const incoming = context.req.header(requestIdHeader);
+    const requestId = incoming &&
+        incoming.length <= maxRequestIdLength &&
+        requestIdPattern.test(incoming)
+        ? incoming
+        : randomUUID();
+    context.set('requestId', requestId);
+    return requestId;
+}
+/** Echo the request id in the `x-request-id` response header, so a user reporting a failure can quote it. */
+export function requestIdMiddleware() {
+    return createMiddleware(async (context, next) => {
+        const requestId = getRequestId(context);
+        await next();
+        try {
+            context.res.headers.set(requestIdHeader, requestId);
+        }
+        catch {
+            // A response passed through from upstream can carry immutable headers.
+            context.res = new Response(context.res.body, context.res);
+            context.res.headers.set(requestIdHeader, requestId);
+        }
+    });
+}
+/**
+ * The standard API error for a Repository error the caller may see, or `undefined` for one that is the server's own
+ * fault and must surface as an opaque 500. The error's own `status` decides which, so a code added to the Repository
+ * needs nothing here. Any route that lets a Repository error propagate answers this way.
+ */
+function repositoryApiError(error) {
+    if (!(error instanceof RepositoryError) || error.status === 'INTERNAL')
+        return undefined;
+    const field = error.path?.map(String).join('.');
+    return new ApiError({
+        status: error.status,
+        reason: error.code,
+        domain: appErrorDomain,
+        message: error.message,
+        ...(error.status === 'INVALID_ARGUMENT' && field
+            ? {
+                fieldViolations: [
+                    { field, description: error.message, reason: error.code },
+                ],
+            }
+            : {}),
+        ...(error.path === undefined && error.details === undefined
+            ? {}
+            : {
+                metadata: {
+                    ...(error.path === undefined ? {} : { path: error.path }),
+                    ...(error.details === undefined ? {} : { details: error.details }),
+                },
+            }),
+        cause: error,
+    });
+}
+//# sourceMappingURL=api-error.js.map

package/dist/router/api-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-error.js","sourceRoot":"","sources":["../../src/router/api-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAG/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAc5B,MAAM,CAAC,MAAM,CAAC;IAChB,gBAAgB,EAAE,GAAG;IACrB,mBAAmB,EAAE,GAAG;IACxB,YAAY,EAAE,GAAG;IACjB,eAAe,EAAE,GAAG;IACpB,iBAAiB,EAAE,GAAG;IACtB,SAAS,EAAE,GAAG;IACd,cAAc,EAAE,GAAG;IACnB,OAAO,EAAE,GAAG;IACZ,kBAAkB,EAAE,GAAG;IACvB,QAAQ,EAAE,GAAG;IACb,aAAa,EAAE,GAAG;IAClB,WAAW,EAAE,GAAG;IAChB,iBAAiB,EAAE,GAAG;CACvB,CAAC,CAAC;AAIH,2GAA2G;AAC3G,MAAM,CAAC,MAAM,cAAc,GAAG,KAAK,CAAC;AAqDpC;;;;;;GAMG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,uCAAuC;IACvB,IAAI,CAAuB;IAC3B,MAAM,CAAiB;IACvB,MAAM,CAAS;IACf,MAAM,CAAS;IACf,gBAAgB,CAAkC;IAClD,eAAe,CAA2C;IAC1D,QAAQ,CAAgD;IAExE,YAAmB,OAAwB;QACzC,KAAK,CACH,OAAO,CAAC,OAAO,EACf,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CACnE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,UAAU,IAAI,mBAAmB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACtE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;QACjD,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;QAC/C,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;IACnC,CAAC;IAEM,SAAS,CAAC,SAAkB;QACjC,OAAO;YACL,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,GAAG,CAAC,IAAI,CAAC,gBAAgB;gBACvB,CAAC,CAAC,EAAE,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,EAAE;gBAC7C,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM;gBAC9B,CAAC,CAAC,EAAE,eAAe,EAAE,IAAI,CAAC,eAAe,EAAE;gBAC3C,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrD,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpC,CAAC;IACJ,CAAC;CACF;AAED,MAAM,gBAAgB,GAA6C;IACjE,GAAG,EAAE,kBAAkB;IACvB,GAAG,EAAE,iBAAiB;IACtB,GAAG,EAAE,mBAAmB;IACxB,GAAG,EAAE,WAAW;IAChB,GAAG,EAAE,SAAS;IACd,GAAG,EAAE,kBAAkB;IACvB,GAAG,EAAE,kBAAkB;IACvB,GAAG,EAAE,oBAAoB;IACzB,GAAG,EAAE,eAAe;IACpB,GAAG,EAAE,aAAa;IAClB,GAAG,EAAE,mBAAmB;CACzB,CAAC;AAEF,6FAA6F;AAC7F,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,OAAO,CACL,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAC7E,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,IAAI,KAAK,YAAY,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,KAAK,YAAY,aAAa,EAAE,CAAC;QACnC,OAAO,IAAI,QAAQ,CAAC;YAClB,MAAM,EAAE,sBAAsB,CAAC,KAAK,CAAC,MAAM,CAAC;YAC5C,MAAM,EAAE,QAAQ,KAAK,CAAC,MAAM,EAAE;YAC9B,MAAM,EAAE,cAAc;YACtB,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,8BAA8B,KAAK,CAAC,MAAM,GAAG;YACvE,UAAU,EAAE,KAAK,CAAC,MAAM;YACxB,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;IACD,MAAM,eAAe,GAAG,kBAAkB,CAAC,KAAK,CAAC,CAAC;IAClD,IAAI,eAAe;QAAE,OAAO,eAAe,CAAC;IAC5C,MAAM,WAAW,GAAG,eAAe,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,WAAW,EAAE,CAAC;QAChB,OAAO,IAAI,QAAQ,CAAC;YAClB,MAAM,EAAE,sBAAsB,CAAC,WAAW,CAAC,MAAM,CAAC;YAClD,MAAM,EAAE,WAAW,CAAC,MAAM,IAAI,QAAQ,WAAW,CAAC,MAAM,EAAE;YAC1D,MAAM,EAAE,WAAW,CAAC,MAAM,IAAI,cAAc;YAC5C,OAAO,EAAE,WAAW,CAAC,OAAO;YAC5B,UAAU,EAAE,WAAW,CAAC,MAA8B;YACtD,KAAK,EAAE,KAAK;SACb,CAAC,CAAC;IACL,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,CACL,iBAAiB,CAAC,KAAK,CAAC;QACxB,IAAI,QAAQ,CAAC;YACX,MAAM,EAAE,UAAU;YAClB,MAAM,EAAE,gBAAgB;YACxB,MAAM,EAAE,cAAc;YACtB,OAAO,EAAE,wBAAwB;YACjC,KAAK,EAAE,KAAK;SACb,CAAC,CACH,CAAC;AACJ,CAAC;AASD,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,CAAC,CAAC,KAAK,YAAY,KAAK,CAAC,IAAI,CAAC,CAAC,QAAQ,IAAI,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACxE,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IACzB,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,GAAG,GAAG,IAAI,MAAM,GAAG,GAAG;QAC5D,OAAO,SAAS,CAAC;IACnB,MAAM,MAAM,GAAG,KAGd,CAAC;IACF,OAAO;QACL,MAAM;QACN,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,GAAG,CAAC,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvE,GAAG,CAAC,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxE,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,KAAe,EACf,SAAkB;IAElB,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC;AAC/C,CAAC;AAED;;;GAGG;AACH,SAAS,gBAAgB,CAAC,OAAgB,EAAE,KAAc;IACxD,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;IACnC,OAAO,OAAO,CAAC,IAAI,CACjB,YAAY,CAAC,QAAQ,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC,EAC7C,QAAQ,CAAC,IAAI,CACd,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc,EAAE,OAAgB;IAC9D,MAAM,KAAK,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC;IACvC,IAAI,KAAK;QAAE,OAAO,gBAAgB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IACnD,MAAM,KAAK,CAAC;AACd,CAAC;AAED,MAAM,CAAC,MAAM,kBAAkB,GAAoB,CAAC,OAAO,EAAE,EAAE,CAC7D,gBAAgB,CACd,OAAO,EACP,IAAI,QAAQ,CAAC;IACX,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,iBAAiB;IACzB,MAAM,EAAE,cAAc;IACtB,OAAO,EAAE,wBAAwB,OAAO,CAAC,GAAG,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,GAAG;CAC3E,CAAC,CACH,CAAC;AAmBJ;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAI,MAAyB,EAAE,KAAc;IACxE,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACvC,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC;IACvC,MAAM,oBAAoB,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AAClD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,MAAoC;IAEpC,OAAO,IAAI,QAAQ,CAAC;QAClB,MAAM,EAAE,kBAAkB;QAC1B,MAAM,EAAE,eAAe;QACvB,MAAM,EAAE,cAAc;QACtB,OAAO,EAAE,sCAAsC;QAC/C,eAAe,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;YACpC,MAAM,IAAI,GAAI,KAAqC,CAAC,IAAI,CAAC;YACzD,OAAO;gBACL,KAAK,EAAE,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;qBACtB,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CACf,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;oBAC7C,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC;oBACrB,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CACpB;qBACA,IAAI,CAAC,GAAG,CAAC;gBACZ,WAAW,EAAE,KAAK,CAAC,OAAO;gBAC1B,GAAG,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC9D,CAAC;QACJ,CAAC,CAAC;KACH,CAAC,CAAC;AACL,CAAC;AASD,MAAM,CAAC,MAAM,eAAe,GAAG,cAAc,CAAC;AAQ9C,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAC/B,MAAM,gBAAgB,GAAG,aAAa,CAAC;AAEvC;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,OAAgB;IAC3C,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAuB,CAAC;IAChE,IAAI,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAC9B,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC;IACrD,MAAM,SAAS,GACb,QAAQ;QACR,QAAQ,CAAC,MAAM,IAAI,kBAAkB;QACrC,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC;QAC7B,CAAC,CAAC,QAAQ;QACV,CAAC,CAAC,UAAU,EAAE,CAAC;IACnB,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IACpC,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,6GAA6G;AAC7G,MAAM,UAAU,mBAAmB;IACjC,OAAO,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAiB,EAAE;QAC7D,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;QACxC,MAAM,IAAI,EAAE,CAAC;QACb,IAAI,CAAC;YACH,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC;QACtD,CAAC;QAAC,MAAM,CAAC;YACP,uEAAuE;YACvE,OAAO,CAAC,GAAG,GAAG,IAAI,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;YAC1D,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,SAAS,CAAC,CAAC;QACtD,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,SAAS,kBAAkB,CAAC,KAAc;IACxC,IAAI,CAAC,CAAC,KAAK,YAAY,eAAe,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,UAAU;QACpE,OAAO,SAAS,CAAC;IACnB,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAChD,OAAO,IAAI,QAAQ,CAAC;QAClB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,MAAM,EAAE,KAAK,CAAC,IAAI;QAClB,MAAM,EAAE,cAAc;QACtB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,kBAAkB,IAAI,KAAK;YAC9C,CAAC,CAAC;gBACE,eAAe,EAAE;oBACf,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,EAAE;iBAC1D;aACF;YACH,CAAC,CAAC,EAAE,CAAC;QACP,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;YACzD,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE,QAAQ,EAAE;oBACR,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;oBACzD,GAAG,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;iBACnE;aACF,CAAC;QACN,KAAK,EAAE,KAAK;KACb,CAAC,CAAC;AACL,CAAC"}

package/dist/router/api-limits.d.ts

@@ -0,0 +1,80 @@
+import type { Hono, MiddlewareHandler } from 'hono';
+import { type AppConfigDefinition, type AppConfigFactory, type ConfigValidator } from '../config/define-app-config.js';
+/** A duration: a number of milliseconds, or a string such as `500ms`, `30s`, `1m` or `1h`. */
+export type ApiDuration = number | string;
+/** A size: a number of bytes, or a string such as `512kb`, `10mb` or `1gb` (powers of 1024). */
+export type ApiSize = number | string;
+export interface ApiRateLimitConfig {
+    /** How many requests one client may make per `window`. */
+    readonly max: number;
+    readonly window: ApiDuration;
+}
+/**
+ * The `api` section: limits the application applies to every `/api` request, ahead of any route. Each one is off while
+ * it is unset, and nothing is installed for it.
+ */
+export interface ApiConfig {
+    /** The largest request body any `/api` route accepts. Routes still set their own, usually smaller, limit. */
+    readonly bodyLimit?: ApiSize | null;
+    /** How long a handler may take to produce its response. A streaming response that has started is not cut off. */
+    readonly timeout?: ApiDuration | null;
+    /** Requests per client per window, counted in this process. */
+    readonly rateLimit?: ApiRateLimitConfig | null;
+}
+/** The `api` section with every value resolved to a number. */
+export interface ResolvedApiLimits {
+    readonly bodyLimitBytes?: number;
+    readonly timeoutMs?: number;
+    readonly rateLimit?: {
+        readonly max: number;
+        readonly windowMs: number;
+    };
+}
+/** Milliseconds for a duration such as `30s`; a bare number, or a string of digits, is milliseconds. */
+export declare function parseApiDuration(value: unknown, name: string): number;
+/** Bytes for a size such as `10mb`; a bare number, or a string of digits, is bytes. */
+export declare function parseApiSize(value: unknown, name: string): number;
+/** Resolves the `api` section, throwing on the first malformed value. An unset or `null` value stays off. */
+export declare function resolveApiLimits(config: ApiConfig | undefined): ResolvedApiLimits;
+/** The rules the `api` section is held to, run at start, on reload and by `config check`. */
+export declare const validateApiConfig: ConfigValidator<ApiConfig>;
+/**
+ * Declares the `api` section with the framework's validation and environment variables, in place of
+ * `defineAppConfig`. Every limit defaults to off. A `validate` given here runs after the framework's own.
+ */
+export declare function defineApiConfig(definition?: Partial<AppConfigDefinition<ApiConfig>>): AppConfigFactory<ApiConfig>;
+export interface InstallApiLimitsOptions {
+    /** The clock the rate limiter reads, for tests. */
+    readonly now?: () => number;
+}
+/**
+ * Installs the configured limits on the `/api` router, in the order a request meets them: the rate limit, before any
+ * work is done for a client already over it; then the deadline, which also covers reading the body; then the body
+ * ceiling. Nothing is installed for a limit that is not configured. Call it after the request id middleware, so every
+ * refusal carries the request's id, and before any route.
+ */
+export declare function installApiLimits(api: Hono, config: ApiConfig | undefined, options?: InstallApiLimitsOptions): void;
+/** Refuses a body over `maxBytes` with `413 BODY_TOO_LARGE`, whether it declares its length or streams it. */
+export declare function apiBodyLimitMiddleware(maxBytes: number): MiddlewareHandler;
+/**
+ * Answers `503 REQUEST_TIMEOUT` when the handler has not returned its response within `timeoutMs`.
+ *
+ * The deadline covers the time until the response object exists, not the time spent sending it, so a streaming
+ * response that has started runs to its end. The handler itself cannot be cancelled and keeps running after the
+ * deadline; what it eventually returns or throws is discarded.
+ */
+export declare function apiTimeoutMiddleware(timeoutMs: number): MiddlewareHandler;
+/**
+ * Counts requests per client in fixed windows and answers `429 RATE_LIMITED`, with `Retry-After` in seconds, once a
+ * client exceeds `max` in its current window.
+ *
+ * The client is the address of the connection, read from the Node.js server bindings. The signed-in user is not known
+ * at this point: authentication runs inside the routes that need it. A request whose address is unknown, such as one an
+ * in-process Hub forwards, is not counted. Counters live in this process, so each instance of a multi-instance
+ * deployment counts on its own.
+ */
+export declare function apiRateLimitMiddleware(limit: {
+    readonly max: number;
+    readonly windowMs: number;
+}, options?: InstallApiLimitsOptions): MiddlewareHandler;
+//# sourceMappingURL=api-limits.d.ts.map

package/dist/router/api-limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-limits.d.ts","sourceRoot":"","sources":["../../src/router/api-limits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAW,IAAI,EAAE,iBAAiB,EAAE,MAAM,MAAM,CAAC;AAI7D,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACrB,MAAM,gCAAgC,CAAC;AAIxC,8FAA8F;AAC9F,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,CAAC;AAE1C,gGAAgG;AAChG,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAEtC,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,6GAA6G;IAC7G,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACpC,iHAAiH;IACjH,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACtC,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAChD;AAED,+DAA+D;AAC/D,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1E;AAgBD,wGAAwG;AACxG,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAOrE;AAED,uFAAuF;AACvF,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAOjE;AAkCD,6GAA6G;AAC7G,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,GAAG,SAAS,GAC5B,iBAAiB,CAanB;AAgBD,6FAA6F;AAC7F,eAAO,MAAM,iBAAiB,EAAE,eAAe,CAAC,SAAS,CAkDxD,CAAC;AAgBF;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,UAAU,GAAE,OAAO,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAM,GACvD,gBAAgB,CAAC,SAAS,CAAC,CAa7B;AAKD,MAAM,WAAW,uBAAuB;IACtC,mDAAmD;IACnD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,IAAI,EACT,MAAM,EAAE,SAAS,GAAG,SAAS,EAC7B,OAAO,GAAE,uBAA4B,GACpC,IAAI,CAQN;AAED,8GAA8G;AAC9G,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,CAe1E;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,iBAAiB,CA6BzE;AAUD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,EAC1D,OAAO,GAAE,uBAA4B,GACpC,iBAAiB,CAuCnB"}