@nocobase/app-server 0.11.1-alpha.5 → 2.0.0-beta.2

package/dist/router/api-limits.js

@@ -0,0 +1,281 @@
+import { bodyLimit } from 'hono/body-limit';
+import { createMiddleware } from 'hono/factory';
+import { defineAppConfig, } from '../config/define-app-config.js';
+import { envString } from '@nocobase/config/providers/env';
+import { ApiError, apiErrorHandler, appErrorDomain } from './api-error.js';
+const durationUnits = {
+    ms: 1,
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+};
+const sizeUnits = {
+    b: 1,
+    kb: 1024,
+    mb: 1024 ** 2,
+    gb: 1024 ** 3,
+};
+/** Milliseconds for a duration such as `30s`; a bare number, or a string of digits, is milliseconds. */
+export function parseApiDuration(value, name) {
+    return parseQuantity(value, name, durationUnits, 'a positive duration such as "500ms", "30s", "1m" or "1h"');
+}
+/** Bytes for a size such as `10mb`; a bare number, or a string of digits, is bytes. */
+export function parseApiSize(value, name) {
+    return parseQuantity(value, name, sizeUnits, 'a positive size such as "512kb", "10mb" or "1gb"');
+}
+function parseQuantity(value, name, units, expected) {
+    let amount;
+    if (typeof value === 'number') {
+        amount = value;
+    }
+    else if (typeof value === 'string') {
+        const match = /^(\d+(?:\.\d+)?)\s*([a-z]*)$/i.exec(value.trim());
+        const multiplier = match
+            ? match[2]
+                ? units[match[2].toLowerCase()]
+                : 1
+            : undefined;
+        if (match && multiplier !== undefined)
+            amount = Number(match[1]) * multiplier;
+    }
+    if (amount === undefined || !Number.isFinite(amount) || amount <= 0) {
+        throw new Error(`${name} must be ${expected}.`);
+    }
+    return Math.ceil(amount);
+}
+const apiConfigFields = new Set([
+    'bodyLimit',
+    'timeout',
+    'rateLimit',
+]);
+const rateLimitFields = new Set(['max', 'window']);
+/** Resolves the `api` section, throwing on the first malformed value. An unset or `null` value stays off. */
+export function resolveApiLimits(config) {
+    if (config === undefined || config === null)
+        return {};
+    if (!isRecord(config))
+        throw new Error('api must be a mapping.');
+    const { bodyLimit: size, timeout, rateLimit } = config;
+    return {
+        ...(isSet(size)
+            ? { bodyLimitBytes: parseApiSize(size, 'api.bodyLimit') }
+            : {}),
+        ...(isSet(timeout)
+            ? { timeoutMs: parseApiDuration(timeout, 'api.timeout') }
+            : {}),
+        ...(isSet(rateLimit) ? { rateLimit: resolveRateLimit(rateLimit) } : {}),
+    };
+}
+function resolveRateLimit(value) {
+    if (!isRecord(value))
+        throw new Error('api.rateLimit must be a mapping with max and window.');
+    const { max, window } = value;
+    if (typeof max !== 'number' || !Number.isInteger(max) || max <= 0) {
+        throw new Error('api.rateLimit.max must be a positive integer.');
+    }
+    if (!isSet(window))
+        throw new Error('api.rateLimit.window is required.');
+    return { max, windowMs: parseApiDuration(window, 'api.rateLimit.window') };
+}
+/** The rules the `api` section is held to, run at start, on reload and by `config check`. */
+export const validateApiConfig = (api, context) => {
+    if (!isRecord(api)) {
+        context.error('', 'must be a mapping.');
+        return;
+    }
+    for (const key of Object.keys(api)) {
+        if (!apiConfigFields.has(key))
+            context.warning(key, 'is not an api setting, so nothing reads it. Expected bodyLimit, timeout or rateLimit.');
+    }
+    const check = (path, parse) => {
+        try {
+            parse();
+        }
+        catch (error) {
+            context.error(path, (error instanceof Error ? error.message : String(error)).replace(`api.${path} `, ''));
+        }
+    };
+    if (isSet(api.bodyLimit))
+        check('bodyLimit', () => parseApiSize(api.bodyLimit, 'api.bodyLimit'));
+    if (isSet(api.timeout))
+        check('timeout', () => parseApiDuration(api.timeout, 'api.timeout'));
+    const rateLimit = api.rateLimit;
+    if (!isSet(rateLimit))
+        return;
+    if (!isRecord(rateLimit)) {
+        context.error('rateLimit', 'must be a mapping with max and window.');
+        return;
+    }
+    for (const key of Object.keys(rateLimit)) {
+        if (!rateLimitFields.has(key))
+            context.warning(`rateLimit.${key}`, 'is not a rateLimit setting, so nothing reads it. Expected max and window.');
+    }
+    const { max, window } = rateLimit;
+    if (typeof max !== 'number' || !Number.isInteger(max) || max <= 0)
+        context.error('rateLimit.max', 'must be a positive integer.');
+    if (!isSet(window))
+        context.error('rateLimit.window', 'is required.');
+    else
+        check('rateLimit.window', () => parseApiDuration(window, 'api.rateLimit.window'));
+};
+/** The environment variables that set `api` fields. */
+const API_ENVIRONMENT = {
+    API_BODY_LIMIT: envString('bodyLimit', {
+        description: 'The largest request body any /api route accepts, such as 10mb; off when unset.',
+        required: false,
+    }),
+    API_TIMEOUT: envString('timeout', {
+        description: 'How long an /api request may take before it is answered 503 REQUEST_TIMEOUT, such as 30s; off when unset.',
+        required: false,
+    }),
+};
+/**
+ * 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 function defineApiConfig(definition = {}) {
+    const extra = definition.validate === undefined
+        ? []
+        : Array.isArray(definition.validate)
+            ? definition.validate
+            : [definition.validate];
+    return defineAppConfig({
+        defaults: definition.defaults ?? {},
+        validate: [validateApiConfig, ...extra],
+        ...(definition.public ? { public: definition.public } : {}),
+        env: { ...API_ENVIRONMENT, ...definition.env },
+    });
+}
+/** The path no limit counts: load balancers and probes poll it, and must not be throttled or timed out. */
+const exemptPaths = new Set(['/api/healthz']);
+/**
+ * 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 function installApiLimits(api, config, options = {}) {
+    const limits = resolveApiLimits(config);
+    if (limits.rateLimit)
+        api.use('*', apiRateLimitMiddleware(limits.rateLimit, options));
+    if (limits.timeoutMs !== undefined)
+        api.use('*', apiTimeoutMiddleware(limits.timeoutMs));
+    if (limits.bodyLimitBytes !== undefined)
+        api.use('*', apiBodyLimitMiddleware(limits.bodyLimitBytes));
+}
+/** Refuses a body over `maxBytes` with `413 BODY_TOO_LARGE`, whether it declares its length or streams it. */
+export function apiBodyLimitMiddleware(maxBytes) {
+    return bodyLimit({
+        maxSize: maxBytes,
+        onError: (context) => apiErrorHandler(new ApiError({
+            status: 'INVALID_ARGUMENT',
+            reason: 'BODY_TOO_LARGE',
+            domain: appErrorDomain,
+            message: `The request body exceeds the application's limit of ${maxBytes} bytes.`,
+            httpStatus: 413,
+        }), context),
+    });
+}
+/**
+ * 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 function apiTimeoutMiddleware(timeoutMs) {
+    return createMiddleware(async (context, next) => {
+        if (exemptPaths.has(context.req.path)) {
+            await next();
+            return;
+        }
+        let timer;
+        const deadline = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                reject(new ApiError({
+                    status: 'UNAVAILABLE',
+                    reason: 'REQUEST_TIMEOUT',
+                    domain: appErrorDomain,
+                    message: `The request was not handled within ${timeoutMs} ms.`,
+                }));
+            }, timeoutMs);
+        });
+        const handled = next();
+        try {
+            await Promise.race([handled, deadline]);
+        }
+        finally {
+            clearTimeout(timer);
+            // A handler that loses the race may still fail later; its outcome has nowhere to go, and must not surface as an
+            // unhandled rejection that stops the process.
+            handled.catch(() => undefined);
+        }
+    });
+}
+/** The most clients counted at once; past it the oldest window is dropped, so memory stays bounded under a flood. */
+const maxTrackedClients = 100_000;
+/**
+ * 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 function apiRateLimitMiddleware(limit, options = {}) {
+    const now = options.now ?? Date.now;
+    // Every window has the same length and a client's entry is re-inserted when its window restarts, so insertion
+    // order is expiry order: expired entries are always at the front.
+    const windows = new Map();
+    return createMiddleware(async (context, next) => {
+        if (exemptPaths.has(context.req.path))
+            return next();
+        const client = clientAddress(context);
+        if (client === undefined)
+            return next();
+        const time = now();
+        for (const [key, window] of windows) {
+            if (window.resetAt > time)
+                break;
+            windows.delete(key);
+        }
+        let window = windows.get(client);
+        if (!window) {
+            if (windows.size >= maxTrackedClients) {
+                const oldest = windows.keys().next();
+                if (!oldest.done)
+                    windows.delete(oldest.value);
+            }
+            window = { count: 0, resetAt: time + limit.windowMs };
+            windows.set(client, window);
+        }
+        window.count += 1;
+        if (window.count <= limit.max)
+            return next();
+        const retryAfter = Math.max(1, Math.ceil((window.resetAt - time) / 1000));
+        const response = apiErrorHandler(new ApiError({
+            status: 'RESOURCE_EXHAUSTED',
+            reason: 'RATE_LIMITED',
+            domain: appErrorDomain,
+            message: `Too many requests: at most ${limit.max} per ${limit.windowMs} ms. Retry after ${retryAfter} s.`,
+            metadata: { retryAfterSeconds: retryAfter },
+        }), context);
+        response.headers.set('Retry-After', String(retryAfter));
+        return response;
+    });
+}
+/** The remote address of the connection, as `@hono/node-server` exposes it, or `undefined` outside a Node server. */
+function clientAddress(context) {
+    const env = context.env;
+    const address = (env?.incoming ?? env?.server?.incoming)?.socket
+        ?.remoteAddress;
+    return typeof address === 'string' && address ? address : undefined;
+}
+function isSet(value) {
+    return value !== undefined && value !== null;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=api-limits.js.map

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

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

package/dist/router/cli/derive.d.ts

@@ -0,0 +1,32 @@
+import type { ApiDocument } from '../openapi/document.js';
+import { type CliCaller, type CliCommand, type CliExclusion, type CliIdentity, type CliManifest } from './types.js';
+export interface DeriveCliCommandsOptions {
+    /**
+     * The security schemes that name an identity: an operation whose requirements name one is offered to that identity.
+     * `cookieAuth` and `apiKeyAuth` name a person by default.
+     */
+    readonly identitySchemes?: Readonly<Record<string, CliIdentity>>;
+    /** Operations left out, as if their `x-cli` were `false`. */
+    readonly exclude?: readonly CliExclusion[];
+}
+/** `issueId` → `issue-id`, `AiEmployee` → `ai-employee`. */
+export declare function kebabCase(value: string): string;
+/**
+ * The command words derived from an operation's tag, path and method. A `POST` to a path that ends in a literal after
+ * a parameter is a custom method (`POST /issues/{id}/close` → `close`), unless the path is a collection, which
+ * `collections` names by having a `GET` on it (`POST /issues/{id}/comments` → `comments create`).
+ */
+export declare function deriveCommandWords(method: string, path: string, tag: string | undefined, collections?: ReadonlySet<string>): string[];
+/**
+ * Every command the API document describes, for every caller: each documented operation that is not hidden and whose
+ * `x-cli` is not `false`. A derived name that two operations share falls back to the tag and the `operationId`; a name
+ * an `x-cli.command` gives twice keeps its first operation.
+ */
+export declare function deriveAllCliCommands(document: ApiDocument, options?: DeriveCliCommandsOptions): CliCommand[];
+/** The commands a caller may run: offered to its identity, and holding the action each one names. */
+export declare function filterCliCommands(commands: readonly CliCommand[], caller: Pick<CliCaller, 'kind' | 'actions'>): CliCommand[];
+/** The manifest of `caller`'s commands, and of those it is not offered, with why. */
+export declare function cliManifestOf(commands: readonly CliCommand[], caller: CliCaller): CliManifest;
+/** The manifest of the commands the API document describes that `caller` may run. */
+export declare function deriveCliCommands(document: ApiDocument, caller: CliCaller, options?: DeriveCliCommandsOptions): CliManifest;
+//# sourceMappingURL=derive.d.ts.map

package/dist/router/cli/derive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.d.ts","sourceRoot":"","sources":["../../../src/router/cli/derive.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,WAAW,EAKjB,MAAM,YAAY,CAAC;AAQpB,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IACjE,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;CAC5C;AAoCD,4DAA4D;AAC5D,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO/C;AAWD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,WAAW,GAAE,WAAW,CAAC,MAAM,CAAa,GAC3C,MAAM,EAAE,CAwCV;AAybD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,WAAW,EACrB,OAAO,GAAE,wBAA6B,GACrC,UAAU,EAAE,CA4Cd;AAED,qGAAqG;AACrG,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,SAAS,UAAU,EAAE,EAC/B,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC,GAC1C,UAAU,EAAE,CAId;AAaD,qFAAqF;AACrF,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,SAAS,UAAU,EAAE,EAC/B,MAAM,EAAE,SAAS,GAChB,WAAW,CAiCb;AAED,qFAAqF;AACrF,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,WAAW,EACrB,MAAM,EAAE,SAAS,EACjB,OAAO,GAAE,wBAA6B,GACrC,WAAW,CAEb"}