starlight-server 0.0.1

package/src/http/request.ts

@@ -0,0 +1,44 @@
+import type http from 'node:http'
+import { type Logger } from '@anjianshi/utils'
+import { RequestBody, type BodyOptions } from './body/index.js'
+import { HTTPError, type NodeRequest } from './types.js'
+
+/**
+ * 对 Node.js 请求内容的二次封装
+ * - 提供经过整理的请求信息
+ * - 自带 body 解析（实现了 “body 大小限制” 和 “JSON、form-data 等格式的内容解析”）
+ *
+ * Secondary encapsulation of the Node.js Request object
+ * - Organized request information
+ * - Comes with body parsing (implements 'body size limit' and 'content parsing for formats such as JSON and form-data').
+ */
+export class Request {
+  readonly method: string
+  readonly host: string
+  readonly path: string
+  readonly query: URLSearchParams
+  readonly headers: http.IncomingHttpHeaders
+  readonly body: RequestBody
+
+  constructor(
+    readonly nodeRequest: NodeRequest,
+    protected readonly logger: Logger,
+    bodyOptions: BodyOptions,
+  ) {
+    if (nodeRequest.method === undefined) throw new HTTPError(405)
+    this.method = nodeRequest.method
+
+    try {
+      const url = new URL(nodeRequest.url ?? '', `http://${nodeRequest.headers.host ?? ''}`)
+      this.host = url.host
+      this.path = url.pathname
+      this.query = url.searchParams
+    } catch (e) {
+      this.logger.warn('parse url failed', e)
+      throw new HTTPError(400, 'url invalid')
+    }
+
+    this.headers = nodeRequest.headers
+    this.body = new RequestBody(nodeRequest, bodyOptions)
+  }
+}

package/src/http/response.ts

@@ -0,0 +1,73 @@
+import { type Logger } from '@anjianshi/utils'
+import { path2MIMEType } from './mime-types.js'
+import { HTTPError, type NodeResponse } from './types.js'
+
+/**
+ * 封装响应内容输出函数
+ * Encapsulate functions for outputting response content.
+ */
+export class ResponseUtils {
+  constructor(
+    readonly nodeResponse: NodeResponse,
+    readonly logger: Logger,
+  ) {}
+
+  header(name: string, value: string) {
+    this.nodeResponse.setHeader(name, value)
+  }
+
+  headers(...items: [string, string][]) {
+    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)
+  }
+
+  /**
+   * Output JSON
+   */
+  json(data: unknown) {
+    try {
+      const json = JSON.stringify(data)
+      this.header('Content-Type', 'application/json; charset=UTF-8')
+      this.nodeResponse.end(json)
+    } catch (e) {
+      throw new HTTPError(500, 'Invalid JSON Response')
+    }
+  }
+
+  /**
+   * 原样输出文件内容，并带上文件类型对应的 MIME Type
+   * Output the file content and include the MIME Type corresponding to the file type.
+   */
+  file(content: Buffer | string, path: string) {
+    const mimeType = path2MIMEType(path)
+    if (mimeType !== null) this.header('Content-Type', mimeType)
+    this.nodeResponse.end(content)
+  }
+
+  /**
+   * Output HTTP Error
+   */
+  error(error: unknown) {
+    if (error instanceof HTTPError) {
+      this.nodeResponse.statusCode = error.status // eslint-disable-line require-atomic-updates
+      this.nodeResponse.end(error.message)
+    } else {
+      this.logger.error(error)
+      this.nodeResponse.statusCode = 500 // eslint-disable-line require-atomic-updates
+      this.nodeResponse.end(new HTTPError(500).message)
+    }
+  }
+}

package/src/http/server.ts

@@ -0,0 +1,67 @@
+import http from 'node:http'
+import { type Logger, LogLevel } from '@anjianshi/utils'
+import { type BodyOptions } from './body/index.js'
+import { Request } from './request.js'
+import { ResponseUtils } from './response.js'
+import { type NodeRequest, type NodeResponse } from './types.js'
+
+export type RequestHandler = (request: Request, response: ResponseUtils) => unknown
+
+/**
+ * 二次封装 Node.js HTTP Server，实现了更完善的 request 和 response 处理
+ * Secondary encapsulation of the Node.js HTTP Server, with more complete request and response handling.
+ *
+ * 功能点：
+ * - 经过整理的 request 信息，且自带 body 解析
+ * - 快速输出指定格式的响应内容
+ * - 自带异常处理
+ *   - 任意处抛出 HTTPError，可以指定 HTTP Status 结束请求
+ *   - 抛出其他 Error，则以 Status 500 结束请求
+ *
+ * Features:
+ * - Organized request information, and built-in body parsing
+ * - Quickly output response content in a specified format
+ * - Built-in exception handling
+ *   - Throw HTTPError anywhere, and end the request with the specified HTTP Status
+ *   - If another Error is thrown, end the request with Status 500
+ *
+ * Usage：
+ * startHTTPServer(handler, options)
+ */
+export function startHTTPServer(
+  options: BodyOptions & {
+    handler?: RequestHandler
+    logger: Logger
+    port: number
+  },
+) {
+  const { handler = placeholderHandler, logger, port, ...bodyOptions } = options
+
+  async function handleRequest(nodeRequest: NodeRequest, nodeResponse: NodeResponse) {
+    const logStart = Date.now()
+    const logMethod = nodeRequest.method ?? 'UNKNOWN'
+    const logUrl = nodeRequest.url ?? ''
+    logger.info('<--', logMethod, logUrl)
+
+    const response = new ResponseUtils(nodeResponse, logger)
+    try {
+      const request = new Request(nodeRequest, logger, bodyOptions)
+      await handler(request, response)
+    } catch (error) {
+      response.error(error)
+    }
+
+    const logUsage = Date.now() - logStart
+    const logStatus = nodeResponse.statusCode
+    const logLevel = logStatus >= 400 ? LogLevel.Warning : LogLevel.Info
+    logger.log(logLevel, ['-->', logMethod, logUrl, logStatus, `${logUsage}ms`])
+  }
+
+  const server = http.createServer(handleRequest)
+  logger.info('Listening', port)
+  server.listen(port)
+}
+
+function placeholderHandler(request: Request, response: ResponseUtils) {
+  response.json({ message: 'Hello World, from starlight.' })
+}

package/src/http/types.ts

@@ -0,0 +1,31 @@
+/**
+ * 重新定义 HTTP 请求相关类型
+ * Redefine HTTP request-related types.
+ */
+import type http from 'node:http'
+import { HTTPStatusMap } from './http-status.js'
+
+/**
+ * Node.js 原生的请求对象
+ * Node.js native request object
+ */
+export type NodeRequest = http.IncomingMessage
+
+/**
+ * Node.js 原生的响应对象
+ * Node.js native response object
+ */
+export type NodeResponse = http.ServerResponse & { req: http.IncomingMessage }
+
+/**
+ * 带有 HTTP Status 的错误对象
+ * Error object with HTTP Status
+ */
+export class HTTPError extends Error {
+  readonly status: number
+
+  constructor(status: number, message?: string) {
+    super(message ?? HTTPStatusMap.get(status) ?? status.toString())
+    this.status = status
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from '@/http/index.js'
+export * from '@/router/index.js'
+export * from '@/logging.js'
+// export * from '@/swagger/index.js'

package/src/logging.ts

@@ -0,0 +1,57 @@
+/**
+ * 实现日志记录
+ */
+import { truthy, Logger, LogLevel, adaptDebugLib } from '@anjianshi/utils'
+import {
+  ConsoleHandler,
+  FileHandler,
+  type FileHandlerOptions,
+} from '@anjianshi/utils/env-node/logging.js'
+import debug from 'debug'
+
+export type { FileHandlerOptions }
+
+export interface LoggingOptions {
+  /**
+   * 指定日志等级（debug info warn err）
+   * Specify log level.
+   */
+  level?: string
+
+  /**
+   * 文件日志参数
+   * File log options
+   */
+  file?: Partial<FileHandlerOptions>
+
+  /**
+   * 是否把 debug 库的日志引入进来；可通过字符串指定匹配规则
+   * Whether to import logs from 'debug' library; can specify matching rules through strings
+   */
+  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)
+  }
+  return logger
+}

package/src/router/cors.ts

@@ -0,0 +1,54 @@
+import { type Request, type ResponseUtils } from '@/http/index.js'
+
+/**
+ * CORS 配置
+ *
+ * - false: 不处理跨域
+ * - true: 支持且不设限（等同于 { allowOrigin: '*', allowHeaders: '*', exposeHeaders: '*' }）
+ * - { allowOrigin, allowHeaders, exposeHeaders }: 手动配置
+ *
+ * allowHeaders 仅对 Preflight 请求有效
+ * exposeHeaders 仅对非 Preflight 请求有效
+ */
+export type CORSOptions =
+  | boolean
+  | { allowOrigin?: string; allowHeaders?: string; exposeHeaders?: string }
+
+/**
+ * 若当前请求是 CORS Preflight 请求，返回实际请求的 method，否则返回 null
+ */
+export function getMethodFromCORSPreflight(request: Request) {
+  if (
+    request.method === 'OPTIONS' &&
+    request.headers['Access-Control-Request-Methods'] !== undefined
+  ) {
+    const rawMethod = request.headers['Access-Control-Request-Methods']
+    return Array.isArray(rawMethod) ? rawMethod[0]! : rawMethod
+  }
+  return null
+}
+
+/**
+ * 输出 CORS 相关 headers
+ */
+export function outputCORSHeaders(
+  response: ResponseUtils,
+  cors: CORSOptions,
+  isPreflight: boolean,
+) {
+  if (cors === true) {
+    response.headers(['Access-Control-Allow-Origin', '*'])
+    if (isPreflight) response.headers(['Access-Control-Allow-Headers', '*'])
+    else response.headers(['Access-Control-Expose-Headers', '*'])
+  } else if (cors !== false) {
+    if (cors.allowOrigin !== undefined)
+      response.header('Access-Control-Allow-Origin', cors.allowOrigin)
+    if (isPreflight && cors.allowHeaders !== undefined)
+      response.header('Access-Control-Allow-Headers', cors.allowHeaders)
+    if (!isPreflight && cors.exposeHeaders !== undefined)
+      response.header('Access-Control-Expose-Headers', cors.exposeHeaders)
+  } else {
+    // 若指定为“不处理跨域”，则不输出 headers，浏览器会默认服务端不允许跨域请求
+    // （后续 route handler 仍有机会自行设置 CORS headers）
+  }
+}

package/src/router/index.ts

@@ -0,0 +1,38 @@
+/**
+ * 实现路由注册
+ * 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, ParameterDataType } from './parameters.js'

package/src/router/match.ts

@@ -0,0 +1,194 @@
+/**
+ * 匹配路由路径
+ *
+ * 支持的格式：
+ * 1. /abc/ abc/ /abc => 这几种形式等价
+ * 2. /abc/:foo/bar => 命名参数（foo）
+ * 3. /abc/:foo?/bar => 可选命名参数（foo）
+ * 4. /abc/* => 后续路径（任意长度，* 只能出现在路由最后面，匹配结果不含开头的“/”）
+ *
+ * 路由不区分大小写
+ */
+import escapeRegExp from 'lodash/escapeRegExp.js'
+
+/**
+ * 标准化路径
+ * 标准化后，相同的两个路径一定也是相同的字符串（例如 /Abc/Def 和 abc/def/ 都会变成 abc/def）。
+ *
+ * - 移除首尾和重复的 '/'，完成后有 path 有这几种可能的格式： ''、'abc'、'abc/def'
+ * - 统一改为小写
+ */
+export function normalizePath(path: string) {
+  if (path.startsWith('/')) path = path.slice(1)
+  if (path.endsWith('/')) path = path.slice(0, -1)
+  path = path.replace(/\/+/g, '/')
+  return path.toLowerCase()
+}
+
+/**
+ * 解析路由路径定义
+ * '/abc/:foo?/*' => [{ type: 'text', text: 'abc' }, { type: 'named', name: 'foo', optional: true }, { type: 'rest' }]
+ */
+function parseRoutePath(routePath: string): ParsedPath {
+  const normalizedPath = normalizePath(routePath)
+
+  const nodes: PathNode[] = []
+  const pathParts = normalizedPath.split('/')
+  for (const [i, part] of pathParts.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('route path parameter name cannot be "*"')
+      nodes.push({ type: PathNodeType.Named, name, optional })
+    } else if (part === '*' && i === pathParts.length - 1) {
+      nodes.push({ type: PathNodeType.Rest })
+    } else {
+      nodes.push({ type: PathNodeType.Text, text: part })
+    }
+  }
+
+  return nodes
+}
+
+enum PathNodeType {
+  /** 纯文本 */
+  Text = 'text',
+  /** 命名参数 */
+  Named = 'named',
+  /** 后续路径 */
+  Rest = 'rest',
+}
+type PathNode =
+  | { type: PathNodeType.Text; text: string }
+  | { type: PathNodeType.Named; name: string; optional: boolean }
+  | { type: PathNodeType.Rest }
+type ParsedPath = PathNode[]
+
+/**
+ * 把路由定义转换成正则表达式
+ *
+ * Nodes                      | Path          | 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 parsedPathToRegExp(parsedPath: ParsedPath) {
+  const regexpParts: string[] = []
+  for (const node of parsedPath) {
+    const prefix = node === parsedPath[0] ? '' : '/'
+    if (node.type === PathNodeType.Text) {
+      regexpParts.push(prefix + escapeRegExp(node.text))
+    } else if (node.type === PathNodeType.Named) {
+      regexpParts.push(node.optional ? `(?:${prefix}([^/]+?))?` : `${prefix}([^/]+?)`)
+    } else {
+      regexpParts.push(`(?:${prefix}(.+))?`)
+    }
+  }
+  return new RegExp('^' + regexpParts.join('') + '$', 'i')
+}
+
+/**
+ * 比较两个路径的优先级（两个路由都能匹配路径时，优先级更高的生效）
+ *
+ * pathA 优先：-1
+ * pathB 优先：1
+ *
+ * 规则：
+ * 1. 挨个 node 比对
+ * 2. 先匹配各节点的类型，text > named > named optional > rest
+ * 3. 节点类型都一致，节点数量多的优先级更高
+ * 4. 节点类型、数量都一样，后出现的覆盖先出现的
+ */
+function pathSorter(pathA: ParsedPath, pathB: ParsedPath) {
+  const typePriorities = [PathNodeType.Text, PathNodeType.Named, PathNodeType.Rest]
+
+  const length = Math.max(pathA.length, pathB.length)
+  for (let i = 0; i < length; i++) {
+    const a = pathA[i]
+    const b = pathB[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 === PathNodeType.Named &&
+      b.type === PathNodeType.Named &&
+      a.optional !== b.optional
+    ) {
+      return a.optional ? 1 : -1
+    }
+  }
+
+  // 长度、类型都一样，后出现的优先
+  return 1
+}
+
+/**
+ * 返回匹配的路由及匹配上的路径参数
+ */
+export function matchRoutes<R extends BasicRoute>(requestPath: string, routes: R[]) {
+  if (!parsedCache.has(routes)) {
+    // 解析路由路径并按优先级排序
+    const parsedRoutes = routes
+      .map(route => {
+        const parsedPath = parseRoutePath(route.path)
+        const regexp = parsedPathToRegExp(parsedPath)
+        return { parsedPath, regexp, route }
+      })
+      .sort((a, b) => pathSorter(a.parsedPath, b.parsedPath))
+    parsedCache.set(routes, parsedRoutes)
+  }
+
+  requestPath = normalizePath(requestPath)
+  const parsedRoutes = parsedCache.get(routes)!
+  return parsedRoutes
+    .map(({ parsedPath, regexp, route }) => {
+      const match = regexp.exec(requestPath)
+      if (!match) return null
+
+      const pathParameters = matchPathParameters(parsedPath, [...match].slice(1))
+      return { route, pathParameters } as RouteMatch<R>
+    })
+    .filter((matched): matched is Exclude<typeof matched, null> => matched !== null)
+}
+const parsedCache = new WeakMap<
+  BasicRoute[], // eslint-disable-line @typescript-eslint/no-explicit-any
+  { parsedPath: ParsedPath; regexp: RegExp; route: BasicRoute }[] // eslint-disable-line @typescript-eslint/no-explicit-any
+>()
+
+export type BasicRoute = { path: string }
+
+export interface RouteMatch<R> {
+  route: R
+  pathParameters: PathParameters
+}
+
+/**
+ * 把匹配到的路径参数映射成键值对
+ * 没匹配到的内容（optional named node / rest node）值为 undefined
+ */
+function matchPathParameters(parsedPath: ParsedPath, parameterNames: (string | undefined)[]) {
+  const parameters: PathParameters = {}
+  for (const node of parsedPath) {
+    if (node.type === PathNodeType.Text) continue
+    else if (node.type === PathNodeType.Named) parameters[node.name] = parameterNames.shift()!
+    else parameters['*'] = parameterNames.shift()!
+  }
+  return parameters
+}
+export type PathParameters = {
+  [name: string]: string | undefined
+  '*'?: string
+}