starlight-server 1.3.0 → 1.5.0

package/dist/swagger/specification.js

@@ -0,0 +1,130 @@
+/**
+ * OpenAPI Specification
+ * https://swagger.io/specification/
+ *
+ * ---------------------
+ *
+ * # 概念解释
+ *
+ * Operation
+ *   即通常说的“接口”。
+ *   OpenAPI 遵循 RESTFul 的思路，一个路径代表一项资源，每个 HTTP Method 代表对此资源的一项操作（Operation）。
+ *
+ * Tag
+ *   接口标签，可以理解为是接口分组。
+ *   一个接口可以有多个标签，即接口能归属多个分组。
+ *
+ * Security Scheme
+ *   认证方案。基于 OAuth 等标准制定的具体执行方案。
+ *
+ * Security Requirement
+ *   认证要求。
+ *   要求发起请求时必须实现一种或多种“认证方案”。
+ *   一个接口可以有多套“认证要求”，请求方选择其中一种来实现。
+ *   （注意是选择一种“要求”，而不是选择“要求”里的一种“方案”）。
+ *
+ * Link
+ *   接口关联。
+ *   接口之间可能有关联关系，例如 `/schools/:id` 和 `/schools/:schoolId/classes/:id` 就是相关的接口，
+ *   并且前者的 `id` 参数对应后者的 `schoolId` 参数。
+ *   “接口关联”就是用来记录下这些关系。
+ *
+ * Webhook
+ *   由“接口提供方”主动请求“接口使用者”的网址，例如在某些事件发生时通知使用者。
+ *
+ * Callback
+ *   接口回调：某个接口被调用后，反过来请求“请求发起者”的网址。
+ *   例如像微信授权流程：“使用者”请求授权接口 - “微信”反过来请求“使用者”的网址来传递授权结果
+ *   注意：Callback 和 Webhook 很像，不过一个是“调用接口后”反过来被请求；另一个是跟接口调用无关，单纯被“接口提供方”调用。
+ *
+ * Data Type
+ *   数据类型（string、number、boolean、array、object...）。
+ *
+ * Schema
+ *   数据规范：定义一种数据的“数据格式”和“验证规则”。
+ *   - “数据格式”包含数据类型（Data Type）信息，对于 object，也包含对象接口信息。
+ *     它决定了数据以什么形态存在，例如在内存中怎么存储。
+ *   - 验证规则则是像“字符串长度在 8 ~ 16 之间”等“业务”上的要求，它与数据的存在方式无关，但决定了数据是否符合业务需求。
+ *
+ * Media Type
+ *   以特定 MIME Type 传递的内容的 Schema 和范例。
+ *   固定以 { [MIMEType]: MediaType } 的形式出现。
+ *
+ * ---------------------
+ *
+ * # 字符串扩展
+ *
+ * CommonMark
+ *   支持 CommonMark 格式的富文本字符串
+ *
+ * MIME Type
+ *   表示 MIME Type 的字符串，如：application/json。
+ *   凡是可指定 MIME Type 字符串的地方，都支持通配符 `image/*`，并可用逗号分隔多项 `image/jpg,image/png`。
+ *
+ * Runtime Expression
+ *   可通过此表达式结合请求信息计算出一个 URL。
+ *   详见 <https://swagger.io/specification/#runtime-expressions>
+ *
+ * ---------------------
+ *
+ * # 请求参数序列化（Parameter Style）
+ *
+ * 发起请求时要携带参数，如果业务上要求参数值不是纯文本（如数组、对象），那么需要经过格式化才能传递。
+ *
+ * 例如一个接口批量返回若干本书的详情：`GET /books`，并通过 `id_list` 参数指定一系列书的 ID。
+ * 这个 id_list 应该是一个数组 `[1,2,3]`，但 HTTP 请求只能传递纯文本，需要把数组 `序列化` 成纯文本来传递。
+ * 最常见的办法，是把 `id_list` 放在 query 里，多个 ID 用逗号分隔：`/books?id_list=1,2,3`，这种序列化方式在 OpenAPI 规范里被称为 `form`。
+ * 还有一种办法是直接加在 path 里：`/books/1,2,3`，这种方式被称为 `simple`。
+ * 以上都是使用 OpenAPI 规范里预设的序列化方式（Parameter Style）来序列化参数，这被称为是 `简单场景的参数`。
+ *
+ * 另外，还可以由服务器端和客户端约定，用某种 MIME Type（如 application/json）的格式序列化参数：`/books/?id_list=[1,2,3]`。
+ * 这被称为 `复杂场景的参数`（即“预设方案满足不了需求场景”的参数）。
+ *
+ * ## 预设序列化方式（Parameter Style）列表
+ *
+ * ----------------------------------------------------------
+ * 序列化方式     | 支持数据类型           | 支持的参数位置
+ * ----------------------------------------------------------
+ * matrix         | primitive,array,object | path
+ * label          | primitive,array,object | path
+ * form           | primitive,array,object | query,cookie
+ * simple         | primitive,array        | path,header
+ * spaceDelimited | array,object           | query
+ * pipeDelimited  | array,object           | query
+ * deepObject     | object                 | query
+ *
+ * ## 各参数位置默认的序列化方式
+ *
+ * - path: simple
+ * - query: form
+ * - header: simple
+ * - cookie: form
+ *
+ * ## 参数值范例
+ *
+ * 假设有一个名为 `color` 的参数，有以下几种值之一：
+ * ```
+ * string -> "blue"
+ * array -> ["blue", "black", "brown"]
+ * object -> { "R": 100, "G": 200, "B": 150 }
+ * ```
+ *
+ * -----------------------------------------------------------------------------------------------------------------------------------
+ * 序列化方式     | 拆分传递 | 空值     | string      | array                               | object
+ * -----------------------------------------------------------------------------------------------------------------------------------
+ * matrix         | 否       | ;color   | ;color=blue | ;color=blue;black;brown             | ;color=R,100,G,200,B,150
+ * matrix         | 是       | ;color   | ;color=blue | ;color=blue;color=black;color=brown | ;R=100;G=200;B=150
+ * label          | 否       | .        | .blue       | .blue.black.brown                   | .R.100.G.200.B.150
+ * label          | 是       | .        | .blue       | .blue.black.brown                   | .R=100.G=200.B=150
+ * form           | 否       | color=   | color=blue  | color=blue,black,brown              | color=R,100,G,200,B,150
+ * form           | 是       | color=   | color=blue  | color=blue&color=black&color=brown  | R=100&G=200&B=150
+ * simple         | 否       | 不支持   | blue        | blue,black,brown                    | R,100,G,200,B,150
+ * simple         | 是       | 不支持   | blue        | blue,black,brown                    | R=100,G=200,B=150
+ * spaceDelimited | 否       | 不支持   | 不支持      |	blue%20black%20brown                | R%20100%20G%20200%20B%20150
+ * pipeDelimited  | 否       | 不支持   | 不支持      |	blue|black|brown                    | R|100|G|200|B|150
+ * deepObject     | 是       | 不支持   | 不支持      |	不支持                              | color[R]=100&color[G]=200&color[B]=150
+ *
+ * 注：拆分传递就是值有多项（即值是 array 或 object）时，每项分别传递：`a=1&a=2&a=3`；
+ *     反之则是一次性传递：`a=1,2,3`
+ */
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "starlight-server",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Simple But Powerful Node.js HTTP Server",
   "type": "module",
   "scripts": {
@@ -30,25 +30,25 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@anjianshi/utils": "^1.0.9",
+    "@anjianshi/utils": "^1.3.1",
     "chalk": "^5.3.0",
     "debug": "^4.3.4",
-    "lodash": "^4.17.21",
-    "swagger-ui-dist": "^5.10.3"
+    "swagger-ui-dist": "^5.11.10"
   },
   "devDependencies": {
-    "@anjianshi/presets": "^1.4.0",
+    "@anjianshi/presets-eslint-node": "^1.0.3",
+    "@anjianshi/presets-eslint-typescript": "^1.0.3",
+    "@anjianshi/presets-prettier": "^1.0.0",
+    "@anjianshi/presets-typescript": "^1.0.1",
     "@types/debug": "^4.1.9",
     "@types/lodash": "^4.14.199",
     "@types/node": "^20.8.6",
     "@types/swagger-ui-dist": "^3.30.4",
     "concurrently": "^8.2.1",
-    "eslint": "^8.54.0",
     "nodemon": "^3.0.2",
     "rimraf": "^4.3.0",
-    "tsc-alias": "^1.8.8",
-    "typescript": "^5.3.2"
+    "tsc-alias": "^1.8.8"
   },
   "eslintIgnore": [],
-  "prettier": "@anjianshi/presets/prettierrc"
+  "prettier": "@anjianshi/presets-prettier/prettierrc"
 }

package/src/demo/index.ts

@@ -1,14 +1,6 @@
 import path from 'node:path'
 import { getFileDir } from '@anjianshi/utils/env-node/index.js'
-import {
-  getLogger,
-  startHTTPServer,
-  type BaseContext,
-  type Route,
-  type PathParameters,
-  Router,
-} from '@/index.js'
-import { registerSwaggerRoute } from '@/swagger/index.js'
+import { getLogger, startHTTPServer, Router } from '@/index.js'
 
 const logger = getLogger({
   level: 'debug',
@@ -18,59 +10,66 @@ const logger = getLogger({
   },
 })
 
-type DemoContext = BaseContext & {
-  now: () => number
-}
-class DemoRouter extends Router<DemoContext> {
-  async executeWithContext(
-    baseContext: BaseContext,
-    route: Route<DemoContext>,
-    pathParameters: PathParameters,
-  ) {
-    const context: DemoContext = {
-      ...baseContext,
-      now: () => Date.now(),
-    }
-    await route.handler(context, pathParameters)
-  }
-}
-const router = new DemoRouter()
+// declare module '@/index.js' {
+//   interface Context {
+//     now: () => number
+//   }
+// }
 
-router.registerResponseReference('hello', { object: [{ name: 'hello', type: 'string' }] })
+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',
-  query: [
-    { name: 'q1', type: 'number', required: true },
-    { name: 'q2', type: 'string', description: '这是q2' },
-  ],
-  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/src/http/cors.ts

@@ -0,0 +1,59 @@
+/**
+ * CORS 处理逻辑
+ */
+import { type Request } from './request.js'
+import { ResponseUtils } from './response.js'
+import { type NodeRequest, type NodeResponse } from './types.js'
+
+/**
+ * 判断是否是 CORS Preflight 请求
+ */
+export function isPreflight(request: Request | NodeRequest) {
+  return (
+    request.method === 'OPTIONS' &&
+    typeof request.headers['access-control-request-method'] === 'string'
+  )
+}
+
+/**
+ * 若请求是 CORS Preflight 请求，返回客户端原本想请求的 Method
+ * 否则返回 null
+ */
+export function getPreflightRequestMethod(request: Request | NodeRequest) {
+  return isPreflight(request) ? request.headers['access-control-request-method'] ?? '' : 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 function handleCORS(
+  request: Request | NodeRequest,
+  response: ResponseUtils | NodeResponse,
+  rule: CORSRule
+) {
+  // 不输出 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/src/http/index.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/src/http/mime-types.ts

@@ -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/src/http/request.ts

@@ -1,10 +1,12 @@
 import type http from 'node:http'
-import { type Logger } from '@anjianshi/utils'
+import { parseQuery } from '@anjianshi/utils'
+import { type Logger } from '@/logging.js'
 import { RequestBody, type BodyOptions } from './body/index.js'
 import { HTTPError, type NodeRequest } from './types.js'
 
 /**
  * 对 Node.js 请求内容的二次封装
+ *
  * - 提供经过整理的请求信息
  * - 自带 body 解析（实现了 “body 大小限制” 和 “JSON、form-data 等格式的内容解析”）
  *
@@ -13,32 +15,58 @@ import { HTTPError, type NodeRequest } from './types.js'
  * - Comes with body parsing (implements 'body size limit' and 'content parsing for formats such as JSON and form-data').
  */
 export class Request {
+  /** 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(
     readonly nodeRequest: NodeRequest,
     protected readonly logger: Logger,
-    bodyOptions: BodyOptions,
+    bodyOptions: BodyOptions
   ) {
     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<const K extends string>(key: K): http.IncomingHttpHeaders[Lowercase<K>] {
+    return this.headers[key.toLowerCase()]
+  }
 }

package/src/http/response.ts

@@ -1,4 +1,4 @@
-import { type Logger } from '@anjianshi/utils'
+import { type Logger } from '@/logging.js'
 import { path2MIMEType } from './mime-types.js'
 import { HTTPError, type NodeResponse } from './types.js'
 
@@ -7,10 +7,7 @@ import { HTTPError, type NodeResponse } from './types.js'
  * Encapsulate functions for outputting response content.
  */
 export class ResponseUtils {
-  constructor(
-    readonly nodeResponse: NodeResponse,
-    readonly logger: Logger,
-  ) {}
+  constructor(readonly nodeResponse: NodeResponse, readonly logger: Logger) {}
 
   header(name: string, value: string) {
     this.nodeResponse.setHeader(name, value)
@@ -20,16 +17,6 @@ export class ResponseUtils {
     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: string | Buffer) {
     this.nodeResponse.end(content)
   }
@@ -59,15 +46,29 @@ export class ResponseUtils {
 
   /**
    * Output HTTP Error
+   *
+   * response.error(new HTTPError(xxx)) // 传入 HTTP Error
+   * response.error(404) // 传入 HTTP Status
+   * response.error(xxx) // 传入其他内容，会记录下日志并以 500 状态结束请求
    */
   error(error: unknown) {
     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: string, permanent = false) {
+    this.nodeResponse.statusCode = permanent ? 301 : 302
+    this.header('Location', url)
+    this.nodeResponse.end()
+  }
 }

package/src/http/server.ts

@@ -1,5 +1,5 @@
 import http from 'node:http'
-import { type Logger, LogLevel } from '@anjianshi/utils'
+import { type Logger, LogLevel } from '@/logging.js'
 import { type BodyOptions } from './body/index.js'
 import { Request } from './request.js'
 import { ResponseUtils } from './response.js'
@@ -33,7 +33,7 @@ export function startHTTPServer(
     handler?: RequestHandler
     logger: Logger
     port: number
-  },
+  }
 ) {
   const { handler = placeholderHandler, logger, port, ...bodyOptions } = options
 

package/src/index.ts

@@ -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/src/logging.ts

@@ -6,17 +6,18 @@ import {
   ConsoleHandler,
   FileHandler,
   type FileHandlerOptions,
-} from '@anjianshi/utils/env-node/logging.js'
+} from '@anjianshi/utils/env-node/logging/index.js'
 import debug from 'debug'
 
 export type { FileHandlerOptions }
+export { Logger, LogLevel }
 
 export interface LoggingOptions {
   /**
    * 指定日志等级（debug info warn err）
    * Specify log level.
    */
-  level?: string
+  level?: string | LogLevel
 
   /**
    * 文件日志参数
@@ -31,27 +32,12 @@ export interface LoggingOptions {
   debugLib?: boolean | string
 }
 
-const levelMap: Record<string, LogLevel> = {
-  debug: LogLevel.Debug,
-  info: LogLevel.Info,
-  warn: LogLevel.Warning,
-  warning: LogLevel.Warning,
-  err: LogLevel.Error,
-  error: LogLevel.Error,
-}
-
 export function getLogger(options: LoggingOptions = {}) {
   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) {
-    logger.addHandler(new FileHandler(options.file))
-  }
-  if (truthy(options.debugLib)) {
-    void adaptDebugLib(debug, options.debugLib === true ? '*' : options.debugLib, logger)
-  }
+  if (options.level !== undefined) logger.setLevel(options.level)
+  if (options.file) logger.addHandler(new FileHandler(options.file))
+  if (truthy(options.debugLib))
+    adaptDebugLib(debug, options.debugLib === true ? '*' : options.debugLib, logger)
   return logger
 }

package/src/router/helpers.ts

@@ -0,0 +1,27 @@
+import { type Validator, validators } from '@anjianshi/utils/validators/index.js'
+import { HTTPError } from '@/index.js'
+import { type BasicContext } from './index.js'
+
+export { validators }
+
+export function validatePathParameters<T>(this: BasicContext, struct: Record<string, Validator>) {
+  const result = validators.struct(struct).validate('path', this.pathParameters)
+  if (result.success) return result.data as T
+  throw new HTTPError(400, result.message)
+}
+
+export function validateQuery<T>(this: BasicContext, struct: Record<string, Validator>) {
+  const result = validators.struct(struct).validate('query', this.request.query)
+  if (result.success) return result.data as T
+  throw new HTTPError(400, result.message)
+}
+
+export async function validateBody<T>(this: BasicContext, struct: Record<string, Validator>) {
+  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 as T
+  throw new HTTPError(400, result.message)
+}