starlight-server 1.2.0 → 1.5.0

package/dist/router/index.js

@@ -1,36 +1,107 @@
-/**
- * 实现路由注册
- * Implement route registration
- *
- * Usage:
- * const router = new DefaultRouter()
- * router.register('GET', '/hello/:name', async ({ request, response }: { request: Request, response: ResponseUtils }, params: { name: string }) => {
- *   response.json({ hello: params.name })
- * })
- * startHTTPServer({
- *   handler: router.handle
- *   ...
- * })
- *
- * Usage With Custom Context:
- * interface MyContext extends BaseContext {
- *   foo: () => void
- * }
- * class MyRouter extends BaseRouter<MyContext> {
- *   executeWithContext(baseContext: BaseContext, route: Route<MyContext>, params: PathParamaters) {
- *     function foo() { console.log('bar') }
- *     const context = { ...baseContext, foo }
- *     route.handle(context)
- *   }
- * }
- * const router = new MyRouter()
- * router.register('GET', '/foobar', async ({ request, response, foo }) => {
- *   foo()
- *   response.json({})
- * })
- * startHTTPServer({
- *   handler: router.handle
- *   ...
- * })
- */
-export * from './router.js';
+import { joinPath } from '@anjianshi/utils';
+import { getPreflightRequestMethod, handleCORS } from '../http/cors.js';
+import { HTTPError } from '../http/index.js';
+import { Swagger } from '../swagger/index.js';
+import * as helpers from './helpers.js';
+import { matchPath } from './match-path.js';
+export class Router {
+    /**
+     * ----------------------
+     * 路由定义
+     * ----------------------
+     */
+    routes = [];
+    register(route) {
+        this.routes.push(route);
+        this.registerRouteToSwagger(route);
+    }
+    /**
+     * ----------------------
+     * 全局 CORS 配置
+     * ----------------------
+     */
+    cors = false;
+    setCors(rule) {
+        this.cors = rule;
+    }
+    /**
+     * ----------------------
+     * Swagger 配置
+     * ----------------------
+     */
+    _swagger = null;
+    /**
+     * 访问绑定到这个 router 的 Swagger 实例
+     * （必须事先调用过 `router.bindSwagger()`）
+     */
+    get swagger() {
+        if (!this._swagger)
+            throw new Error('必须先绑定 Swagger 实例');
+        return this._swagger;
+    }
+    bindSwagger(swagger = new Swagger(), endpoint = '/swagger') {
+        if (this._swagger)
+            throw new Error('不能重复绑定 Swagger 实例');
+        this._swagger = swagger;
+        this.routes.forEach(this.registerRouteToSwagger.bind(this));
+        this.routes.push({
+            method: 'GET',
+            path: joinPath(endpoint, '/*'),
+            handler: async (context) => {
+                if (context.pathParameters['*'] === undefined && !context.request.path.endsWith('/')) {
+                    context.response.redirect(joinPath(endpoint, '/'), true);
+                }
+                else {
+                    await swagger.output(context.response, context.pathParameters['*']);
+                }
+            },
+        });
+    }
+    registerRouteToSwagger(route) {
+        if (this._swagger)
+            this._swagger.registerOperation(route.method, route.path, route.document ?? {});
+    }
+    /**
+     * -------------------------------
+     * route 调用 / context 配置
+     * -------------------------------
+     */
+    executor = async (basicContext, route) => {
+        await route.handler(basicContext);
+    };
+    setExecutor(executor) {
+        this.executor = executor;
+    }
+    /**
+     * ----------------------
+     * 请求处理
+     * ----------------------
+     */
+    handle = async (request, response) => {
+        const pathMatchedRoutes = matchPath(this.routes.map(route => route.path), request.path).map(result => ({ route: this.routes[result.index], parameters: result.parameters }));
+        if (!pathMatchedRoutes.length)
+            throw new HTTPError(404); // 没有路径匹配的路由
+        const method = request.method; // 请求的实际 method
+        const matched = pathMatchedRoutes.find(match => match.route.method === method);
+        if (!matched) {
+            const preflightTargetMethod = getPreflightRequestMethod(request); // 对于 CORS Preflight 请求，此为客户端原本希望请求的 method
+            const preflightMatched = pathMatchedRoutes.find(match => match.route.method === preflightTargetMethod);
+            if (preflightMatched) {
+                const corsRule = preflightMatched.route.cors ?? this.cors;
+                handleCORS(request, response, typeof corsRule === 'function' ? corsRule(request) : corsRule);
+                response.nodeResponse.end('');
+                return;
+            }
+            throw new HTTPError(405); // 有路径匹配的路由，但是没有 method 匹配的
+        }
+        const basicContext = {};
+        Object.assign(basicContext, {
+            request,
+            response,
+            pathParameters: matched.parameters,
+            validateQuery: helpers.validateQuery.bind(basicContext),
+            validateBody: helpers.validateBody.bind(basicContext),
+        });
+        await this.executor(basicContext, matched.route);
+    };
+}

package/dist/router/match-path.d.ts

@@ -0,0 +1,13 @@
+export interface MatchResult {
+    index: number;
+    pattern: string;
+    parameters: PathParameters;
+}
+export type PathParameters = {
+    [name: string]: string | undefined;
+    '*'?: string;
+};
+/**
+ * 返回与路径匹配的 pattern 及匹配得到的参数值
+ */
+export declare function matchPath(patterns: string[], path: string): MatchResult[];

package/dist/router/match-path.js

@@ -0,0 +1,160 @@
+/**
+ * 实现路径的模式匹配
+ * match(pattern, path) => match-result
+ *
+ * [支持的模式]
+ * 普通模式       | /abc/           | /abc/                             |
+ * 命名参数       | /abc/:foo/bar   | /abc/123/bar => { foo: '123' }    |
+ * 可选的命名参数 | /abc/:foo?/bar  | /abc/bar => {}                    | 可选参数若未传值，不会出现在匹配结果里
+ * 后续路径       | /abc/*          | /abc/123/456 => { *: '123/456' }  | * 只有出现在路由最后面时生效，可匹配任意长度内容，匹配结果不含开头的“/”
+ *
+ * [通用规则]
+ * - “模式”和“待匹配路径”开头结尾的 "/" 均不影响匹配。例如模式 /abc 可以和路径 abc/ 匹配。
+ * - 不区分大小写
+ */
+import { clearSlash } from '@anjianshi/utils';
+import escapeRegExp from 'lodash/escapeRegExp.js';
+var NodeType;
+(function (NodeType) {
+    NodeType["Text"] = "text";
+    NodeType["Named"] = "named";
+    NodeType["Rest"] = "rest";
+})(NodeType || (NodeType = {}));
+// -----------------------------------------------------
+/**
+ * 返回与路径匹配的 pattern 及匹配得到的参数值
+ */
+export function matchPath(patterns, path) {
+    // 解析 pattern 并按优先级排序
+    const parsedPatterns = patterns
+        .map((pattern, index) => {
+        if (patternCache.has(pattern))
+            return { index, pattern, ...patternCache.get(pattern) };
+        const nodes = parsePattern(pattern);
+        const regexp = patternToRegExp(nodes);
+        patternCache.set(pattern, { nodes, regexp });
+        return { index, pattern, nodes, regexp };
+    })
+        .sort((a, b) => patternSorter(a.nodes, b.nodes));
+    path = clearSlash(path);
+    return parsedPatterns
+        .map(({ index, pattern, nodes, regexp }) => {
+        const match = regexp.exec(path);
+        if (!match)
+            return null;
+        const parameters = formatMatchParameters(nodes, [...match].slice(1));
+        return { index, pattern, parameters };
+    })
+        .filter((matched) => matched !== null);
+}
+const patternCache = new Map();
+/**
+ * 整理 pattern regexp 与路径匹配得到的参数值，按 pat节点定义，把正则匹配结果转换成参数值对象。
+ * 对于 `{ type: 'named', optional: true }` 或 `{ type: 'rest }` 的节点，若没有匹配到的值，则值为 undefined。
+ */
+function formatMatchParameters(pattern, values) {
+    const parameters = {};
+    for (const node of pattern) {
+        if (node.type === NodeType.Text)
+            continue;
+        else if (node.type === NodeType.Named)
+            parameters[node.name] = values.shift();
+        else
+            parameters['*'] = values.shift();
+    }
+    return parameters;
+}
+/**
+ * 解析 pattern
+ * '/abc/:foo?/*' => [
+ *   { type: 'text', text: 'abc' },
+ *   { type: 'named', name: 'foo', optional: true },
+ *   { type: 'rest' }
+ * ]
+ */
+function parsePattern(pattern) {
+    pattern = clearSlash(pattern);
+    const nodes = [];
+    const patternParts = pattern.split('/');
+    for (const [i, part] of patternParts.entries()) {
+        if (part.startsWith(':') && part !== ':' && part !== ':?') {
+            const optional = part.endsWith('?');
+            const name = optional ? part.slice(1, -1) : part.slice(1);
+            if (name === '*')
+                throw new Error('pattern parameter name cannot be "*"');
+            nodes.push({ type: NodeType.Named, name, optional });
+        }
+        else if (part === '*' && i === patternParts.length - 1) {
+            nodes.push({ type: NodeType.Rest });
+        }
+        else {
+            nodes.push({ type: NodeType.Text, text: part });
+        }
+    }
+    return nodes;
+}
+/**
+ * 把 pattern 转换成正则表达式
+ *
+ * Nodes                      | Pattern       | RegExp
+ * -------------------------- | ------------- | ----------------------------
+ * []                         |               | ^$
+ * ['abc']                    | abc           | ^abc$
+ * ['abc', named:foo, 'xyz']  | abc/:foo/xyz  | ^abc/([^/]+?)/xyz$
+ * ['abc', named:foo?, 'xyz'] | abc/:foo?/xyz | ^abc(?:/([^/]+?))?/xyz$
+ * ['abc', named:foo?, rest]  | abc/:foo?/*   | ^abc(?:/([^/]+?))?(?:/(.+))?$
+ */
+function patternToRegExp(pattern) {
+    const regexpParts = [];
+    for (const node of pattern) {
+        const prefix = node === pattern[0] ? '' : '/';
+        if (node.type === NodeType.Text) {
+            regexpParts.push(prefix + escapeRegExp(node.text));
+        }
+        else if (node.type === NodeType.Named) {
+            regexpParts.push(node.optional ? `(?:${prefix}([^/]+?))?` : `${prefix}([^/]+?)`);
+        }
+        else {
+            regexpParts.push(`(?:${prefix}(.+))?`);
+        }
+    }
+    return new RegExp('^' + regexpParts.join('') + '$', 'i');
+}
+/**
+ * 比较 pattern 的优先级（两个 pattern 都与路径匹配时，优先级更高的生效）
+ *
+ * 返回值：
+ * - patternA 优先：-1
+ * - patternB 优先：1
+ * - 优先级完全一样，返回 1，即后出现的优先
+ *
+ * 规则：
+ * 1. 挨个 node 比对
+ * 2. 先匹配各节点的类型，text > named > named optional > rest
+ * 3. 节点类型都一致，节点数量多的优先级更高
+ * 4. 节点类型、数量都一样，后出现的覆盖先出现的
+ */
+function patternSorter(patternA, patternB) {
+    const typePriorities = [NodeType.Text, NodeType.Named, NodeType.Rest];
+    const length = Math.max(patternA.length, patternB.length);
+    for (let i = 0; i < length; i++) {
+        const a = patternA[i];
+        const b = patternB[i];
+        // 若 nodes 长度不一样，长的优先
+        if (a === undefined)
+            return -1;
+        else if (b === undefined)
+            return 1;
+        // node 类型不一样，按类型排序
+        const aTypePriority = typePriorities.indexOf(a.type);
+        const bTypePriority = typePriorities.indexOf(b.type);
+        if (aTypePriority !== bTypePriority)
+            return aTypePriority - bTypePriority;
+        // 若都是 named 类型但 optional 不同
+        if (a.type === NodeType.Named && b.type === NodeType.Named && a.optional !== b.optional) {
+            return a.optional ? 1 : -1;
+        }
+    }
+    // 长度、类型都一样，后出现的优先
+    return 1;
+}

package/dist/swagger/factories.d.ts

@@ -0,0 +1,143 @@
+/**
+ * 用更符合日常习惯的参数格式，快捷生成各类 OpenAPI 定义
+ */
+import { type OptionalFields } from '@anjianshi/utils';
+import type { OpenAPI, Schema, Operation, Responses, Response, Reference, Parameter, RequestBody } from './specification.js';
+type SchemaOrRef = Schema | Reference;
+/**
+ * ---------------------
+ * OpenAPI Document
+ * ---------------------
+ */
+export type DocumentOptions = Omit<OptionalFields<OpenAPI, 'openapi' | 'paths'>, 'info'> & {
+    info?: Partial<OpenAPI['info']>;
+};
+export declare function makeDocument(options?: DocumentOptions): OpenAPI;
+/**
+ * ---------------------
+ * Operation
+ * ---------------------
+ */
+export declare function makeOperation(options?: OperationOptions): Operation;
+export interface OperationOptions extends Pick<Operation, 'summary' | 'description'> {
+    category?: string;
+    query?: (Parameter | Reference)[] | {
+        [name: string]: Schema | Omit<ParameterOptions, 'name'>;
+    };
+    /** 用来构建 RequestBody 的选项值，或引用某个 **RequestBody** 的 Reference */
+    body?: Parameters<typeof makeBody>[0] | Reference;
+    /** 用来构建 Response 的选项值，或引用某个 **Response** 的 Reference */
+    response?: Parameters<typeof makeResponse>[0] | Reference;
+}
+/** 判断一个对象是不是 OperationOptions */
+export declare function isOperationOptions(value: unknown): value is OperationOptions;
+/**
+ * -------------------------------
+ * Request
+ * -------------------------------
+ */
+interface ParameterOptions {
+    name: string;
+    description?: string;
+    required?: boolean;
+    schema: SchemaOrRef;
+}
+/** 生成 query 定义 */
+export declare function makeQuery(options: ParameterOptions): Parameter;
+/** 生成 header 定义 */
+export declare function makeHeader(options: ParameterOptions): Parameter;
+/**
+ * 生成 RequestBody 定义，假定 body 通过 JSON 传递且内容是一个对象。
+ * input 支持的传值：
+ * 1. 生成 object Schema 所需的 properties 定义或完整选项值（ObjectOptions）
+ * 2. 已生成的 object Schema
+ *
+ */
+export declare function makeBody(input: Record<string, SchemaOrRef> | ObjectOptions | Schema, description?: string): RequestBody;
+/**
+ * -------------------------------
+ * Responses / Response
+ * -------------------------------
+ */
+/** 传入 Schema 来生成 Responses 定义 */
+export declare function makeResponses(schema: Schema, description?: string): Responses;
+/** 传入已存在的 Response 定义来生成 Responses 定义 */
+export declare function makeResponsesBy(response: Response | Reference): Responses;
+/** 生成 Response 定义 */
+export declare function makeResponse(schema: Schema | Record<string, SchemaOrRef>, description?: string): Response;
+/**
+ * -------------------------------
+ * Schema
+ * -------------------------------
+ */
+/** 判断一个对象是不是 Schema */
+export declare function isSchema(value: unknown): value is Schema;
+/** Schema 通用参数 */
+type SchemaCommonOptions = Pick<Schema, 'title' | 'description' | 'default' | 'enum'>;
+/** 生成 string Schema */
+export declare function makeString(options?: StringOptions): Schema;
+interface StringOptions extends SchemaCommonOptions {
+    min?: number;
+    max?: number;
+    pattern?: string;
+}
+/** 生成 number Schema */
+export declare function makeNumber(options?: NumberOptions): Schema;
+/** 生成 integer Schema */
+export declare function makeInteger(options?: NumberOptions): Schema;
+interface NumberOptions extends SchemaCommonOptions {
+    min?: number;
+    max?: number;
+}
+/** 生成 boolean Schema */
+export declare function makeBoolean(options?: SchemaCommonOptions): Schema;
+/** 生成 null Schema */
+export declare function makeNull(options?: SchemaCommonOptions): Schema;
+/**
+ * 生成 array Schema
+ * 可以直接传入 item 定义，也可以传入完整 options 对象
+ */
+export declare function makeArray(rawOptions: SchemaOrRef | ArrayOptions): Schema;
+interface ArrayOptions extends SchemaCommonOptions {
+    items: SchemaOrRef;
+    min?: number;
+    max?: number;
+    unique?: boolean;
+}
+/**
+ * 生成 object Schema
+ * 可以直接传入 properties 定义，也可以传入完整 options 对象
+ */
+export declare function makeObject(rawOptions: Record<string, SchemaOrRef> | ObjectOptions): Schema;
+interface ObjectOptions extends SchemaCommonOptions {
+    properties: Record<string, SchemaOrRef>;
+    required?: string[];
+}
+/** 指明一个值可能为 null，即转换为 { oneOf: [Schema, nullSchema] } */
+export declare function makeNullable(schema: SchemaOrRef): Schema;
+/**
+ * 生成内容是 MaySuccess 格式的 object Schema
+ * （对 MaySuccess 的定义见 @anjianshi/utils/lang/may-success.ts）
+ */
+interface MaySuccessOptions extends SchemaCommonOptions {
+    /** 成功时的数据格式 */
+    data: SchemaOrRef;
+    /** 失败时的 data 字段格式（通常用不到） */
+    failed?: SchemaOrRef;
+}
+export declare function makeMaySuccess(options: SchemaOrRef | MaySuccessOptions): Schema;
+/**
+ * -------------------------------
+ * Ref
+ * -------------------------------
+ */
+declare function makeReference(target: keyof typeof referenceTargets, name: string): Reference;
+declare function makeReference(uri: string): Reference;
+export { makeReference };
+declare const referenceTargets: {
+    schema: string;
+    response: string;
+    parameter: string;
+    body: string;
+    header: string;
+};

package/dist/swagger/factories.js

@@ -0,0 +1,231 @@
+/**
+ * 用更符合日常习惯的参数格式，快捷生成各类 OpenAPI 定义
+ */
+import { truthy } from '@anjianshi/utils';
+import defaultsDeep from 'lodash/defaultsDeep.js';
+import pick from 'lodash/pick.js';
+export function makeDocument(options) {
+    return defaultsDeep(options ?? {}, {
+        openapi: '3.1.0',
+        paths: {},
+        info: { title: 'API Document', version: '0.0.1' },
+    });
+}
+/**
+ * ---------------------
+ * Operation
+ * ---------------------
+ */
+export function makeOperation(options = {}) {
+    const { category, query, body, response } = options;
+    const parameters = Array.isArray(query)
+        ? query
+        : query
+            ? Object.entries(query).reduce((result, [name, options]) => {
+                const query = makeQuery({ name, ...('schema' in options ? options : { schema: options }) });
+                return [...result, query];
+            }, [])
+            : undefined;
+    const requestBody = body ? ('$ref' in body ? body : makeBody(body)) : undefined;
+    const responses = response
+        ? '$ref' in response
+            ? makeResponsesBy(response)
+            : makeResponses(response)
+        : undefined;
+    return {
+        tags: category !== undefined ? [category] : [],
+        summary: options.summary,
+        description: options.description,
+        parameters,
+        requestBody,
+        responses,
+    };
+}
+/** 判断一个对象是不是 OperationOptions */
+export function isOperationOptions(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    return (['category', 'query', 'body', 'response'].find(key => truthy(value[key])) !== undefined);
+}
+/** 生成 query 定义 */
+export function makeQuery(options) {
+    return { ...options, in: 'query' };
+}
+/** 生成 header 定义 */
+export function makeHeader(options) {
+    return { ...options, in: 'header' };
+}
+/**
+ * 生成 RequestBody 定义，假定 body 通过 JSON 传递且内容是一个对象。
+ * input 支持的传值：
+ * 1. 生成 object Schema 所需的 properties 定义或完整选项值（ObjectOptions）
+ * 2. 已生成的 object Schema
+ *
+ */
+export function makeBody(input, description) {
+    return {
+        description,
+        content: {
+            'application/json': {
+                schema: isSchema(input) ? input : makeObject(input),
+            },
+        },
+        required: true,
+    };
+}
+/**
+ * -------------------------------
+ * Responses / Response
+ * -------------------------------
+ */
+/** 传入 Schema 来生成 Responses 定义 */
+export function makeResponses(schema, description) {
+    return {
+        200: makeResponse(schema, description),
+    };
+}
+/** 传入已存在的 Response 定义来生成 Responses 定义 */
+export function makeResponsesBy(response) {
+    return {
+        200: response,
+    };
+}
+/** 生成 Response 定义 */
+export function makeResponse(schema, description) {
+    return {
+        description,
+        content: {
+            'application/json': {
+                schema: isSchema(schema) ? schema : makeObject(schema),
+            },
+        },
+    };
+}
+/**
+ * -------------------------------
+ * Schema
+ * -------------------------------
+ */
+/** 判断一个对象是不是 Schema */
+export function isSchema(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    return (['type', 'allOf', 'anyOf', 'oneOf', 'not'].find(key => truthy(value[key])) !== undefined);
+}
+function pickSchemaCommon(options) {
+    return pick(options, 'title', 'description', 'default', 'enum');
+}
+/** 生成 string Schema */
+export function makeString(options = {}) {
+    return {
+        ...pickSchemaCommon(options),
+        type: 'string',
+        minLength: options.min,
+        maxLength: options.max,
+        pattern: options.pattern,
+    };
+}
+/** 生成 number Schema */
+export function makeNumber(options = {}) {
+    return {
+        ...pickSchemaCommon(options),
+        type: 'number',
+        minimum: options.min,
+        maximum: options.max,
+    };
+}
+/** 生成 integer Schema */
+export function makeInteger(options = {}) {
+    return {
+        ...makeNumber(options),
+        type: 'integer',
+    };
+}
+/** 生成 boolean Schema */
+export function makeBoolean(options) {
+    return { ...options, type: 'boolean' };
+}
+/** 生成 null Schema */
+export function makeNull(options) {
+    return { ...options, type: 'null' };
+}
+/**
+ * 生成 array Schema
+ * 可以直接传入 item 定义，也可以传入完整 options 对象
+ */
+export function makeArray(rawOptions) {
+    const options = !('items' in rawOptions) ? { items: rawOptions } : rawOptions;
+    return {
+        ...pickSchemaCommon(options),
+        type: 'array',
+        items: options.items,
+        minItems: options.min,
+        maxItems: options.max,
+        uniqueItems: options.unique,
+    };
+}
+/**
+ * 生成 object Schema
+ * 可以直接传入 properties 定义，也可以传入完整 options 对象
+ */
+export function makeObject(rawOptions) {
+    const options = !('properties' in rawOptions)
+        ? { properties: rawOptions }
+        : rawOptions;
+    return {
+        ...pickSchemaCommon(options),
+        type: 'object',
+        properties: options.properties,
+        required: options.required,
+    };
+}
+/** 指明一个值可能为 null，即转换为 { oneOf: [Schema, nullSchema] } */
+export function makeNullable(schema) {
+    if ('$ref' in schema)
+        return { oneOf: [schema, makeNull()] };
+    const { title, description, ...restSchema } = schema;
+    return { title, description, oneOf: [restSchema, makeNull()] };
+}
+export function makeMaySuccess(options) {
+    const { data, failed, ...restOptions } = 'data' in options ? options : { data: options, failed: undefined };
+    const successSchema = makeObject({
+        title: '成功结果',
+        properties: {
+            success: makeBoolean({ enum: [true] }),
+            data,
+        },
+    });
+    const failedSchema = makeObject({
+        title: '失败结果',
+        properties: {
+            success: makeBoolean({ enum: [false] }),
+            message: makeString(),
+            code: { oneOf: [makeString(), makeNumber()] },
+            ...(failed ? { data: failed } : {}),
+        },
+    });
+    return {
+        ...pickSchemaCommon(restOptions),
+        oneOf: [successSchema, failedSchema],
+    };
+}
+function makeReference(target, uri) {
+    if (typeof uri === 'string') {
+        const name = uri;
+        return {
+            $ref: `#/components/${referenceTargets[target]}/${name}`,
+        };
+    }
+    else {
+        const uri = target;
+        return { $ref: uri };
+    }
+}
+export { makeReference };
+const referenceTargets = {
+    schema: 'schemas',
+    response: 'responses',
+    parameter: 'parameters',
+    body: 'requestBodies',
+    header: 'headers',
+};