starlight-server 1.2.0 → 1.5.0

package/README.md

@@ -1 +1,11 @@
-# Starlight Server: Simple But Powerful Node.js HTTP Server
+# Starlight Server: 功能简约、结构清晰的 HTTP 服务框架
+
+TODO:
+https://github.com/pillarjs/path-to-regexp/blob/master/src/index.ts
+https://github.com/expressjs/multer
+
+此框架专用于实现 HTTP 服务。它由几个独立模块组成：
+
+- http
+- router
+- swagger

package/dist/demo/index.js

@@ -1,7 +1,6 @@
 import path from 'node:path';
 import { getFileDir } from '@anjianshi/utils/env-node/index.js';
-import { getLogger, startHTTPServer, Router, } from '../index.js';
-import { registerSwaggerRoute } from '../swagger/index.js';
+import { getLogger, startHTTPServer, Router } from '../index.js';
 const logger = getLogger({
     level: 'debug',
     debugLib: '*',
@@ -9,43 +8,58 @@ const logger = getLogger({
         dir: path.resolve(getFileDir(import.meta), '../../logs'),
     },
 });
-class DemoRouter extends Router {
-    async executeWithContext(baseContext, route, pathParameters) {
-        const context = {
-            ...baseContext,
-            now: () => Date.now(),
-        };
-        await route.handler(context, pathParameters);
-    }
-}
-const router = new DemoRouter();
-router.registerResponseReference('hello', { object: [{ name: 'hello', type: 'string' }] });
+// declare module '../index.js' {
+//   interface Context {
+//     now: () => number
+//   }
+// }
+const router = new Router();
+router.setCors(true);
+router.bindSwagger();
+router.setExecutor(async (basicContext, route) => {
+    await route.handler({
+        ...basicContext,
+        // now: () => Date.now(),
+    });
+});
+const swagger = router.swagger;
+swagger.registerResponse('hello', swagger.response({
+    hello: swagger.string(),
+}));
 router.register({
-    category: 'demo',
-    description: 'hello world',
     method: 'GET',
     path: '/hello',
-    body: [
-        { name: 'abc', type: 'number' },
-        { name: 'def', type: { array: { type: 'string' } } },
-    ],
-    response: {
-        object: [{ name: 'key', type: 'string' }],
+    document: {
+        category: 'demo',
+        description: 'hello world',
+        query: {
+            q1: { schema: swagger.number(), required: true },
+            q2: { schema: swagger.number(), description: '这是q2' },
+            q3: swagger.boolean(),
+        },
+        body: {
+            abc: swagger.number(),
+            def: swagger.array(swagger.string()),
+        },
+        response: {
+            name: swagger.string(),
+        },
     },
-    handler({ response }) {
-        response.json({ hello: 'world' });
+    handler(ctx) {
+        ctx.response.json({ name: 'world' });
     },
 });
 router.register({
-    category: 'demo',
     method: 'POST',
     path: '/hello',
-    response: { ref: 'hello' },
+    document: {
+        category: 'demo',
+        response: swagger.ref('response', 'hello'),
+    },
     handler({ response }) {
-        response.json({ hello: 'world post' });
+        response.json({ hello: 'world' });
     },
 });
-registerSwaggerRoute(router);
 startHTTPServer({
     handler: router.handle,
     logger: logger.getChild('http'),

package/dist/http/cors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * CORS 处理逻辑
+ */
+import { type Request } from './request.js';
+import { ResponseUtils } from './response.js';
+import { type NodeRequest, type NodeResponse } from './types.js';
+/**
+ * 判断是否是 CORS Preflight 请求
+ */
+export declare function isPreflight(request: Request | NodeRequest): boolean;
+/**
+ * 若请求是 CORS Preflight 请求，返回客户端原本想请求的 Method
+ * 否则返回 null
+ */
+export declare function getPreflightRequestMethod(request: Request | NodeRequest): string | null;
+/**
+ * CORS 放行规则
+ * - false：不放行
+ * - true：无条件放行（等同于 { allowOrigin: '*', allowHeaders: '*', exposeHeaders: '*' }）
+ * - object：手动指定规则
+ *   - 未指定的 key 不会输出对应 header
+ *   - allowHeaders 仅对 Preflight 请求有效
+ *   - exposeHeaders 仅对非 Preflight 请求有效
+ */
+export type CORSRule = boolean | {
+    allowOrigin?: string;
+    allowHeaders?: string;
+    exposeHeaders?: string;
+};
+/**
+ * 输出 CORS 相关 headers
+ */
+export declare function handleCORS(request: Request | NodeRequest, response: ResponseUtils | NodeResponse, rule: CORSRule): void;

package/dist/http/cors.js

@@ -0,0 +1,33 @@
+import { ResponseUtils } from './response.js';
+/**
+ * 判断是否是 CORS Preflight 请求
+ */
+export function isPreflight(request) {
+    return (request.method === 'OPTIONS' &&
+        typeof request.headers['access-control-request-method'] === 'string');
+}
+/**
+ * 若请求是 CORS Preflight 请求，返回客户端原本想请求的 Method
+ * 否则返回 null
+ */
+export function getPreflightRequestMethod(request) {
+    return isPreflight(request) ? request.headers['access-control-request-method'] ?? '' : null;
+}
+/**
+ * 输出 CORS 相关 headers
+ */
+export function handleCORS(request, response, rule) {
+    // 不输出 CORS 相关 headers，浏览器会默认服务端不允许跨域请求
+    if (rule === false)
+        return;
+    if (rule === true)
+        rule = { allowOrigin: '*', allowHeaders: '*', exposeHeaders: '*' };
+    const nodeResponse = response instanceof ResponseUtils ? response.nodeResponse : response;
+    const requestIsPreflight = isPreflight(request);
+    if (rule.allowOrigin !== undefined)
+        nodeResponse.setHeader('Access-Control-Allow-Origin', rule.allowOrigin);
+    if (requestIsPreflight && rule.allowHeaders !== undefined)
+        nodeResponse.setHeader('Access-Control-Allow-Headers', rule.allowHeaders);
+    if (!requestIsPreflight && rule.exposeHeaders !== undefined)
+        nodeResponse.setHeader('Access-Control-Expose-Headers', rule.exposeHeaders);
+}

package/dist/http/index.d.ts

@@ -7,3 +7,4 @@ export * from './response.js';
 export * from './server.js';
 export * from './http-status.js';
 export * from './mime-types.js';
+export * from './cors.js';

package/dist/http/index.js

@@ -7,3 +7,4 @@ export * from './response.js';
 export * from './server.js';
 export * from './http-status.js';
 export * from './mime-types.js';
+export * from './cors.js';

package/dist/http/mime-types.js

@@ -50,26 +50,7 @@ export const MIMETypes = [
     { type: 'application/mxf', extensions: ['.mxf'] },
     {
         type: 'application/octet-stream',
-        extensions: [
-            '.a',
-            '.bin',
-            '.bpk',
-            '.deploy',
-            '.dist',
-            '.distz',
-            '.dmg',
-            '.dms',
-            '.dump',
-            '.elc',
-            '.iso',
-            '.lha',
-            '.lrf',
-            '.lzh',
-            '.o',
-            '.obj',
-            '.pkg',
-            '.so',
-        ],
+        extensions: ['.a', '.bin', '.bpk', '.deploy', '.dist', '.distz', '.dmg', '.dms', '.dump', '.elc', '.iso', '.lha', '.lrf', '.lzh', '.o', '.obj', '.pkg', '.so'], // prettier-ignore
     },
     { type: 'application/oda', extensions: ['.oda'] },
     { type: 'application/oebps-package+xml', extensions: ['.opf'] },

package/dist/http/request.d.ts

@@ -1,10 +1,11 @@
 /// <reference types="node" resolution-mode="require"/>
 import type http from 'node:http';
-import { type Logger } from '@anjianshi/utils';
+import { type Logger } from '../logging.js';
 import { RequestBody, type BodyOptions } from './body/index.js';
 import { type NodeRequest } from './types.js';
 /**
  * 对 Node.js 请求内容的二次封装
+ *
  * - 提供经过整理的请求信息
  * - 自带 body 解析（实现了 “body 大小限制” 和 “JSON、form-data 等格式的内容解析”）
  *
@@ -15,11 +16,26 @@ import { type NodeRequest } from './types.js';
 export declare class Request {
     readonly nodeRequest: NodeRequest;
     protected readonly logger: Logger;
+    /** HTTP Method，始终为大写 */
     readonly method: string;
+    /** 完整的请求 URL */
+    readonly url: string;
+    /** 域名及端口 */
     readonly host: string;
+    /** 请求路径 */
     readonly path: string;
-    readonly query: URLSearchParams;
+    /** 解析后的 query 对象 */
+    readonly query: Record<string, string>;
+    /**
+     * headers 对象，以 Record<string, xxx> 形式访问，仅支持小写 key。
+     * （可使用 request.getHeader() 方法不区分大小写获取 header）
+     */
     readonly headers: http.IncomingHttpHeaders;
+    /** 请求体。出于性能考虑，调用具体解析方法时才执行解析。 */
     readonly body: RequestBody;
     constructor(nodeRequest: NodeRequest, logger: Logger, bodyOptions: BodyOptions);
+    /**
+     * 获取 HTTP Header，支持任意大小写形式：content-type / Content-Type
+     */
+    getHeader<const K extends string>(key: K): http.IncomingHttpHeaders[Lowercase<K>];
 }

package/dist/http/request.js

@@ -1,7 +1,9 @@
+import { parseQuery } from '@anjianshi/utils';
 import { RequestBody } from './body/index.js';
 import { HTTPError } from './types.js';
 /**
  * 对 Node.js 请求内容的二次封装
+ *
  * - 提供经过整理的请求信息
  * - 自带 body 解析（实现了 “body 大小限制” 和 “JSON、form-data 等格式的内容解析”）
  *
@@ -12,29 +14,48 @@ import { HTTPError } from './types.js';
 export class Request {
     nodeRequest;
     logger;
+    /** HTTP Method，始终为大写 */
     method;
+    /** 完整的请求 URL */
+    url;
+    /** 域名及端口 */
     host;
+    /** 请求路径 */
     path;
+    /** 解析后的 query 对象 */
     query;
+    /**
+     * headers 对象，以 Record<string, xxx> 形式访问，仅支持小写 key。
+     * （可使用 request.getHeader() 方法不区分大小写获取 header）
+     */
     headers;
+    /** 请求体。出于性能考虑，调用具体解析方法时才执行解析。 */
     body;
     constructor(nodeRequest, logger, bodyOptions) {
         this.nodeRequest = nodeRequest;
         this.logger = logger;
         if (nodeRequest.method === undefined)
             throw new HTTPError(405);
-        this.method = nodeRequest.method;
+        this.method = nodeRequest.method.toUpperCase();
         try {
-            const url = new URL(nodeRequest.url ?? '', `http://${nodeRequest.headers.host ?? ''}`);
-            this.host = url.host;
-            this.path = url.pathname;
-            this.query = url.searchParams;
+            // 参考：<https://nodejs.org/api/http.html#messageurl>
+            const urlObject = new URL(nodeRequest.url ?? '', `http://${nodeRequest.headers.host ?? ''}`);
+            this.url = urlObject.href;
+            this.host = urlObject.host;
+            this.path = urlObject.pathname;
         }
         catch (e) {
-            this.logger.warn('parse url failed', e);
-            throw new HTTPError(400, 'url invalid');
+            this.logger.warn(`parse URL failed：${nodeRequest.url}`, e);
+            throw new HTTPError(400, 'URL invalid');
         }
+        this.query = parseQuery(this.url);
         this.headers = nodeRequest.headers;
         this.body = new RequestBody(nodeRequest, bodyOptions);
     }
+    /**
+     * 获取 HTTP Header，支持任意大小写形式：content-type / Content-Type
+     */
+    getHeader(key) {
+        return this.headers[key.toLowerCase()];
+    }
 }

package/dist/http/response.d.ts

@@ -1,5 +1,5 @@
 /// <reference types="node" resolution-mode="require"/>
-import { type Logger } from '@anjianshi/utils';
+import { type Logger } from '../logging.js';
 import { type NodeResponse } from './types.js';
 /**
  * 封装响应内容输出函数
@@ -11,10 +11,6 @@ export declare class ResponseUtils {
     constructor(nodeResponse: NodeResponse, logger: Logger);
     header(name: string, value: string): void;
     headers(...items: [string, string][]): void;
-    /**
-     * Output CORS Headers
-     */
-    cors(allowOrigin?: string, allowHeaders?: string): void;
     text(content: string | Buffer): void;
     /**
      * Output JSON
@@ -27,6 +23,14 @@ export declare class ResponseUtils {
     file(content: Buffer | string, path: string): void;
     /**
      * Output HTTP Error
+     *
+     * response.error(new HTTPError(xxx)) // 传入 HTTP Error
+     * response.error(404) // 传入 HTTP Status
+     * response.error(xxx) // 传入其他内容，会记录下日志并以 500 状态结束请求
      */
     error(error: unknown): void;
+    /**
+     * 执行重定向
+     */
+    redirect(url: string, permanent?: boolean): void;
 }

package/dist/http/response.js

@@ -17,12 +17,6 @@ export class ResponseUtils {
     headers(...items) {
         items.forEach(([name, value]) => this.header(name, value));
     }
-    /**
-     * Output CORS Headers
-     */
-    cors(allowOrigin = '*', allowHeaders = '*') {
-        this.headers(['Access-Control-Allow-Origin', allowOrigin], ['Access-Control-Allow-Headers', allowHeaders]);
-    }
     text(content) {
         this.nodeResponse.end(content);
     }
@@ -51,16 +45,30 @@ export class ResponseUtils {
     }
     /**
      * Output HTTP Error
+     *
+     * response.error(new HTTPError(xxx)) // 传入 HTTP Error
+     * response.error(404) // 传入 HTTP Status
+     * response.error(xxx) // 传入其他内容，会记录下日志并以 500 状态结束请求
      */
     error(error) {
         if (error instanceof HTTPError) {
             this.nodeResponse.statusCode = error.status; // eslint-disable-line require-atomic-updates
             this.nodeResponse.end(error.message);
         }
+        else if (typeof error === 'number') {
+            this.error(new HTTPError(error));
+        }
         else {
             this.logger.error(error);
-            this.nodeResponse.statusCode = 500; // eslint-disable-line require-atomic-updates
-            this.nodeResponse.end(new HTTPError(500).message);
+            this.error(new HTTPError(500));
         }
     }
+    /**
+     * 执行重定向
+     */
+    redirect(url, permanent = false) {
+        this.nodeResponse.statusCode = permanent ? 301 : 302;
+        this.header('Location', url);
+        this.nodeResponse.end();
+    }
 }

package/dist/http/server.d.ts

@@ -1,4 +1,4 @@
-import { type Logger } from '@anjianshi/utils';
+import { type Logger } from '../logging.js';
 import { type BodyOptions } from './body/index.js';
 import { Request } from './request.js';
 import { ResponseUtils } from './response.js';

package/dist/http/server.js

@@ -1,5 +1,5 @@
 import http from 'node:http';
-import { LogLevel } from '@anjianshi/utils';
+import { LogLevel } from '../logging.js';
 import { Request } from './request.js';
 import { ResponseUtils } from './response.js';
 /**

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+export * from './logging.js';
 export * from './http/index.js';
 export * from './router/index.js';
-export * from './logging.js';
+export * from './swagger/index.js';
+export { validators } from '@anjianshi/utils/validators/index.js';

package/dist/index.js

@@ -1,4 +1,5 @@
+export * from './logging.js';
 export * from './http/index.js';
 export * from './router/index.js';
-export * from './logging.js';
-// export * from './swagger/index.js'
+export * from './swagger/index.js';
+export { validators } from '@anjianshi/utils/validators/index.js';

package/dist/logging.d.ts

@@ -1,15 +1,16 @@
 /**
  * 实现日志记录
  */
-import { Logger } from '@anjianshi/utils';
-import { type FileHandlerOptions } from '@anjianshi/utils/env-node/logging.js';
+import { Logger, LogLevel } from '@anjianshi/utils';
+import { type FileHandlerOptions } from '@anjianshi/utils/env-node/logging/index.js';
 export type { FileHandlerOptions };
+export { Logger, LogLevel };
 export interface LoggingOptions {
     /**
      * 指定日志等级（debug info warn err）
      * Specify log level.
      */
-    level?: string;
+    level?: string | LogLevel;
     /**
      * 文件日志参数
      * File log options

package/dist/logging.js

@@ -2,29 +2,17 @@
  * 实现日志记录
  */
 import { truthy, Logger, LogLevel, adaptDebugLib } from '@anjianshi/utils';
-import { ConsoleHandler, FileHandler, } from '@anjianshi/utils/env-node/logging.js';
+import { ConsoleHandler, FileHandler, } from '@anjianshi/utils/env-node/logging/index.js';
 import debug from 'debug';
-const levelMap = {
-    debug: LogLevel.Debug,
-    info: LogLevel.Info,
-    warn: LogLevel.Warning,
-    warning: LogLevel.Warning,
-    err: LogLevel.Error,
-    error: LogLevel.Error,
-};
+export { Logger, LogLevel };
 export function getLogger(options = {}) {
     const logger = new Logger();
     logger.addHandler(new ConsoleHandler());
-    if (options.level !== undefined) {
-        const level = levelMap[options.level.toLowerCase()];
-        if (level !== undefined)
-            logger.setLevel(level);
-    }
-    if (options.file) {
+    if (options.level !== undefined)
+        logger.setLevel(options.level);
+    if (options.file)
         logger.addHandler(new FileHandler(options.file));
-    }
-    if (truthy(options.debugLib)) {
-        void adaptDebugLib(debug, options.debugLib === true ? '*' : options.debugLib, logger);
-    }
+    if (truthy(options.debugLib))
+        adaptDebugLib(debug, options.debugLib === true ? '*' : options.debugLib, logger);
     return logger;
 }

package/dist/router/helpers.d.ts

@@ -0,0 +1,6 @@
+import { type Validator, validators } from '@anjianshi/utils/validators/index.js';
+import { type BasicContext } from './index.js';
+export { validators };
+export declare function validatePathParameters<T>(this: BasicContext, struct: Record<string, Validator>): T;
+export declare function validateQuery<T>(this: BasicContext, struct: Record<string, Validator>): T;
+export declare function validateBody<T>(this: BasicContext, struct: Record<string, Validator>): Promise<T>;

package/dist/router/helpers.js

@@ -0,0 +1,24 @@
+import { validators } from '@anjianshi/utils/validators/index.js';
+import { HTTPError } from '../index.js';
+export { validators };
+export function validatePathParameters(struct) {
+    const result = validators.struct(struct).validate('path', this.pathParameters);
+    if (result.success)
+        return result.data;
+    throw new HTTPError(400, result.message);
+}
+export function validateQuery(struct) {
+    const result = validators.struct(struct).validate('query', this.request.query);
+    if (result.success)
+        return result.data;
+    throw new HTTPError(400, result.message);
+}
+export async function validateBody(struct) {
+    const body = await this.request.body.json();
+    if (typeof body !== 'object' || body === null || Array.isArray(body))
+        throw new HTTPError(400, 'Invalid JSON body, should be an object.');
+    const result = validators.struct(struct).validate('body', this.request.body);
+    if (result.success)
+        return result.data;
+    throw new HTTPError(400, result.message);
+}

package/dist/router/index.d.ts

@@ -1,38 +1,67 @@
-/**
- * 实现路由注册
- * 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';
-export { type PathParameters } from './match.js';
-export type { BasicDataType, Parameter, BasicParameter, ParameterDataType } from './parameters.js';
+import { type CORSRule } from '../http/cors.js';
+import { type Request, type ResponseUtils } from '../http/index.js';
+import { Swagger, type Method } from '../swagger/index.js';
+import * as helpers from './helpers.js';
+import { type PathParameters } from './match-path.js';
+export interface BasicContext {
+    request: Request;
+    response: ResponseUtils;
+    pathParameters: PathParameters;
+    validatePathParameters: typeof helpers.validatePathParameters;
+    validateQuery: typeof helpers.validateQuery;
+    validateBody: typeof helpers.validateBody;
+}
+/** 使用者可自行补充 Context 定义  */
+export interface Context extends BasicContext {
+}
+export interface Route {
+    method: Method;
+    path: string;
+    handler: (context: Context) => void | Promise<void>;
+    /** 接口文档（需 router 绑定 Swagger 实例才生效） */
+    document?: Parameters<Swagger['registerOperation']>[2];
+    /** 此接口的 CORS 规则 */
+    cors?: CORSRule;
+}
+export declare class Router {
+    /**
+     * ----------------------
+     * 路由定义
+     * ----------------------
+     */
+    readonly routes: Route[];
+    register(route: Route): void;
+    /**
+     * ----------------------
+     * 全局 CORS 配置
+     * ----------------------
+     */
+    private cors;
+    setCors(rule: typeof this.cors): void;
+    /**
+     * ----------------------
+     * Swagger 配置
+     * ----------------------
+     */
+    private _swagger;
+    /**
+     * 访问绑定到这个 router 的 Swagger 实例
+     * （必须事先调用过 `router.bindSwagger()`）
+     */
+    get swagger(): Swagger;
+    bindSwagger(swagger?: Swagger, endpoint?: string): void;
+    private registerRouteToSwagger;
+    /**
+     * -------------------------------
+     * route 调用 / context 配置
+     * -------------------------------
+     */
+    private executor;
+    setExecutor(executor: typeof this.executor): void;
+    /**
+     * ----------------------
+     * 请求处理
+     * ----------------------
+     */
+    readonly handle: (request: Request, response: ResponseUtils) => Promise<void>;
+}