starlight-server 0.0.1

package/src/router/parameters.ts

@@ -0,0 +1,172 @@
+/**
+ * 实现通过 query / body parameters 的解析和验证
+ */
+import { success } from '@anjianshi/utils'
+import { type Request, HTTPError } from '@/http/index.js'
+import { type Validator, type CommonOptions } from '@/validators/common.js'
+import * as validators from '@/validators/index.js'
+import { type Route } from './router.js'
+
+/**
+ * ----------------------------------------
+ * 类型定义
+ * ----------------------------------------
+ */
+
+/**
+ * 请求参数定义
+ */
+export interface Parameter {
+  /** 字段名 */
+  name: string
+
+  /** 文字描述  */
+  describe?: string
+
+  type: ParameterDataType
+
+  /** 默认值，应与 type 匹配。若指定，则不再需要 required 规则。 */
+  defaults?: unknown
+
+  /** 是否允许为 undefined  */
+  required?: boolean
+
+  /** 是否允许为 null */
+  nullable?: boolean
+
+  /** 验证规则，会传给 type 对应的 validator */
+  validate?: Record<string, unknown>
+}
+
+export type BasicDataType = 'string' | 'number' | 'boolean'
+
+type BasicParameter = Pick<Parameter, 'type' | 'validate' | 'required' | 'nullable' | 'defaults'>
+
+/**
+ * 请求参数的数据类型定义
+ */
+export type ParameterDataType =
+  | BasicDataType
+  | { array: BasicParameter }
+  | { record: BasicParameter } // 对应 object validator 的 value 类型
+  | { object: Record<string, BasicParameter> } // 对应 object validator 的 struct 类型
+
+/**
+ * ----------------------------------------
+ * 基础功能实现
+ * ----------------------------------------
+ */
+
+/**
+ * 基于 parameter 定义验证、格式化数据
+ */
+function validateParameters<T>(parameters: Parameter[], rawData: Record<string, unknown>) {
+  const result = {} as Record<string, unknown>
+  for (const parameter of parameters) {
+    const validator = getValidatorOfParameter(parameter)
+    const validateRes = validator.validate(parameter.name, rawData[parameter.name])
+    if (validateRes.success) result[parameter.name] = validateRes.data
+    else return validateRes
+  }
+  return success(result as T)
+}
+
+/**
+ * 获取指定 parameter 的 validator
+ */
+function getValidatorOfParameter(parameter: BasicParameter) {
+  if (!validatorCache.has(parameter)) {
+    const validatorConstructor = getValidatorConstructor(parameter.type) as typeof validators.any
+    const options = {
+      null: parameter.nullable,
+      void: typeof parameter.required === 'boolean' ? parameter.required : undefined,
+      defaults: parameter.defaults,
+      ...(parameter.validate ?? {}),
+    }
+    const validator = validatorConstructor(options)
+    validatorCache.set(parameter, validator)
+  }
+  return validatorCache.get(parameter)!
+}
+const validatorCache = new WeakMap<BasicParameter, ReturnType<typeof validators.any>>()
+
+/**
+ * 取得与参数类型对应的 validator constructor
+ */
+function getValidatorConstructor(type: ParameterDataType): (options: CommonOptions) => Validator {
+  if (typeof type === 'string') return validators[type]
+
+  if ('array' in type) {
+    const itemValidator = getValidatorOfParameter(type.array)
+    return validators.array.bind(null, itemValidator)
+  }
+
+  if ('record' in type) {
+    const itemValidator = getValidatorOfParameter(type.record)
+    return validators.object.bind(null, itemValidator)
+  }
+
+  const struct: Record<string, Validator> = {}
+  for (const [key, innerParameter] of Object.entries(type.object)) {
+    struct[key] = getValidatorOfParameter(innerParameter)
+  }
+  return validators.object.bind(null, struct)
+}
+
+/**
+ * ----------------------------------------
+ * 与请求内容对接
+ * ----------------------------------------
+ */
+
+/**
+ * 验证 query 内容
+ */
+export function parseQuery<T>(route: Route, request: Request) {
+  if (!route.query) throw new HTTPError(500, 'Call parseQuery() need query parameter definition.')
+
+  const values: Record<string, unknown> = {}
+  for (const parameter of route.query) {
+    values[parameter.name] = getQueryParameterValue(request, parameter)
+  }
+
+  const res = validateParameters<T>(route.query, values)
+  if (res.success) return res.data
+  throw new HTTPError(400, res.error)
+}
+
+function getQueryParameterValue(request: Request, parameter: Parameter) {
+  // array
+  if (typeof parameter.type === 'object' && 'array' in parameter.type) {
+    return request.query.getAll(parameter.name + '[]')
+  }
+
+  // undefined
+  const raw = request.query.get(parameter.name)
+  if (raw === null || raw === '') return undefined
+
+  // basic type
+  if (typeof parameter.type === 'string') return raw
+
+  // object
+  try {
+    return JSON.parse(raw) as unknown
+  } catch (error) {
+    throw new HTTPError(400, `Invalid JSON value for query parameter "${parameter.name}".`)
+  }
+}
+
+/**
+ * 验证 body 内容
+ */
+export async function parseJSONBody<T>(route: Route, request: Request) {
+  if (!route.body) throw new HTTPError(500, 'call parseJSONBody() need body parameter definition.')
+
+  const body = await request.body.json()
+  if (typeof body !== 'object' || body === null || Array.isArray(body))
+    throw new HTTPError(400, 'Invalid JSON body, should be an object.')
+
+  const res = validateParameters<T>(route.body, body as Record<string, unknown>)
+  if (res.success) return res.data
+  throw new HTTPError(400, res.error)
+}

package/src/router/router.ts

@@ -0,0 +1,233 @@
+import { type RequiredFields } from '@anjianshi/utils'
+import { type Request, type ResponseUtils, HTTPError } from '@/http/index.js'
+import { getMethodFromCORSPreflight, outputCORSHeaders, type CORSOptions } from './cors.js'
+import { matchRoutes, type PathParameters, type RouteMatch } from './match.js'
+import { parseQuery, parseJSONBody, type BasicDataType, type Parameter } from './parameters.js'
+
+/**
+ * -----------------------------------------
+ * 类型定义
+ * -----------------------------------------
+ */
+
+/**
+ * 请求上下文（由 Router 生成并传给请求处理函数）
+ */
+export interface BaseContext {
+  request: Request
+  response: ResponseUtils
+  parseQuery: <T>() => T
+  parseBody: <T>() => Promise<T>
+}
+
+/**
+ * 请求处理函数
+ */
+export type RouteHandler<
+  Ctx extends BaseContext = BaseContext,
+  PathP extends PathParameters = PathParameters,
+> = (context: Ctx, pathParameters: PathP) => unknown
+
+/**
+ * 路由定义
+ *
+ * 相比 RawRoute：
+ * - 有默认值的字段均填充了默认值
+ * - method 一定为全大写
+ */
+export type Route<
+  Ctx extends BaseContext = BaseContext,
+  PathP extends PathParameters = PathParameters,
+> = RequiredFields<RawRoute<Ctx, PathP>, 'describe' | 'category' | 'method'>
+
+export interface RawRoute<
+  Ctx extends BaseContext = BaseContext,
+  PathP extends PathParameters = PathParameters,
+> {
+  /** 接口路径。支持变量（/abc/:xxx/def），详见 src/router/match.ts */
+  path: string
+
+  /** 接口描述  */
+  describe?: string
+
+  /** 接口类别 */
+  category?: string
+
+  /** 接口 HTTP Method，有 body 定义的默认为 POST，否则默认为 GET */
+  method?: string
+
+  /** Query String 定义  */
+  query?: Parameter[]
+
+  /** JSON Request Body 定义 */
+  body?: Parameter[]
+
+  /**
+   * JSON 返回内容定义（返回的不是 JSON 时（如纯文本、二进制文件），不定义此项）
+   * - 若指定的是 ResponseDataType[]，代表有多种可能返回的类型。例如 ['string' | 'null'] 可能返回字符串也可能返回 null
+   */
+  response?: ResponseDataType | ResponseDataType[]
+
+  /**
+   * 指定此接口的 CORS 配置
+   * 不指定则由 router.getCORSOptions() 提供
+   */
+  cors?: CORSOptions
+
+  handler: RouteHandler<Ctx, PathP>
+}
+
+/**
+ * JSON 响应内容的类型定义
+ * { array: ResponseDataType[] } 代表数组元素有多种可能的类型
+ */
+export type ResponseDataType =
+  | BasicDataType
+  | 'null'
+  | { array: ResponseDataType | ResponseDataType[] }
+  | { object: ResponseObjectItemType[] }
+  | { ref: string; summary?: string; description?: string } // 引用预注册了的类型，以重用类型定义
+
+/**
+ * JSON object 相应内容的字段定义
+ */
+export interface ResponseObjectItemType {
+  /** 字段名 */
+  name: string
+
+  /** 文字描述  */
+  describe?: string
+
+  /** 值类型。ResponseDataType[] 代表有多种可能的类型 */
+  type: ResponseDataType | ResponseDataType[]
+}
+
+/**
+ * -----------------------------------------
+ * Router 类
+ * -----------------------------------------
+ */
+
+export abstract class Router<Ctx extends BaseContext = BaseContext> {
+  /**
+   * 路由列表
+   */
+  readonly routes: Route<Ctx>[] = []
+
+  /**
+   * 注册路由
+   */
+  register<P = Record<string, never>>(
+    method: string,
+    path: string,
+    handler: RouteHandler<Ctx, PathParameters & P>,
+  ): void
+  register<P extends Record<string, string>>(raw: RawRoute<Ctx, PathParameters & P>): void
+  register<P extends PathParameters = PathParameters>(
+    raw: RawRoute<Ctx, PathParameters & P> | string,
+    path?: string,
+    handler?: RouteHandler<Ctx, PathParameters & P>,
+  ) {
+    const rawRoute: RawRoute<Ctx, PathParameters & P> =
+      typeof raw === 'string' ? { method: raw, path: path!, handler: handler! } : raw
+    const route: Route<Ctx, PathParameters & P> = {
+      describe: '',
+      category: '',
+      ...rawRoute,
+      method: (rawRoute.method ?? (rawRoute.body ? 'POST' : 'GET')).toUpperCase(),
+    }
+    this.routes.push(route as Route<Ctx>)
+  }
+
+  /**
+   * 响应请求
+   */
+  readonly handle = async (request: Request, response: ResponseUtils) => {
+    const matched = this.match(request, response)
+    if (matched === null) return
+
+    const baseContext = getBaseContext(matched.route as Route, request, response)
+    await this.executeWithContext(baseContext, matched.route, matched.pathParameters)
+  }
+
+  /**
+   * 匹配路由，成功返回路由对象，失败抛出 HTTPError，提前结束处理返回 null
+   */
+  protected match(request: Request, response: ResponseUtils) {
+    const matches = matchRoutes(request.path, this.routes)
+    if (!matches.length) throw new HTTPError(404)
+
+    const methodFromPreflight = getMethodFromCORSPreflight(request)
+    const isPreflight = methodFromPreflight !== null
+
+    const method = methodFromPreflight ?? request.method
+    const methodMatched = matches.find(match => match.route.method === method)
+    if (!methodMatched) throw new HTTPError(405)
+
+    const corsOptions = methodMatched.route.cors ?? this.getCORSOptions(request, methodMatched)
+    outputCORSHeaders(response, corsOptions, isPreflight)
+    if (isPreflight) {
+      response.nodeResponse.end('')
+      return null
+    }
+
+    return methodMatched
+  }
+
+  /**
+   * 为未指定 CORS 配置的 route 提供默认配置
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  getCORSOptions(request: Request, routeMatch: RouteMatch<Route<Ctx>>) {
+    return false
+  }
+
+  /**
+   * 完善 context 对象并执行 route
+   * 注意：handler 在很多时候都是异步的，要用 await 等待执行完成
+   */
+  protected abstract executeWithContext(
+    baseContext: BaseContext,
+    route: Route<Ctx>,
+    pathParameters: PathParameters,
+  ): void | Promise<void>
+
+  /**
+   * response 定义中可引用的数据类型
+   */
+  readonly responseReferences: Record<string, ResponseDataType> = {}
+
+  /**
+   * 注册 response 定义中引用的数据类型
+   */
+  registerResponseReference(id: string, type: ResponseDataType) {
+    this.responseReferences[id] = type
+  }
+}
+
+/**
+ * ------------------------
+ * 默认实现
+ * ------------------------
+ */
+
+/**
+ * 基础 Context 实现
+ */
+function getBaseContext(route: Route, request: Request, response: ResponseUtils) {
+  return {
+    request,
+    response,
+    parseQuery: <T>() => parseQuery<T>(route, request),
+    parseBody: async <T>() => parseJSONBody<T>(route, request),
+  }
+}
+
+/**
+ * 默认的 Router 实现
+ */
+export class DefaultRouter extends Router {
+  async executeWithContext(baseContext: BaseContext, route: Route, pathParameters: PathParameters) {
+    await route.handler(baseContext, pathParameters)
+  }
+}

package/src/swagger/index.ts

@@ -0,0 +1,184 @@
+// import fsPromise from 'node:fs/promises'
+// import path from 'node:path'
+// import { getAbsoluteFSPath } from 'swagger-ui-dist'
+// import { HTTPError } from '@/http/index.js'
+// import {
+//   type Router,
+//   type PathParameters,
+//   type BaseContext,
+//   type ResponseDataType,
+// } from '@/router/index.js'
+// import { normalizePath } from '@/router/match.js'
+// import type { OpenAPI, Schema, PathItem } from './openapi-spec.js'
+
+// export function registerSwaggerRoute(
+//   router: Router,
+//   endpoint: string = '/swagger',
+//   customFields: OpenAPICustomFields = { info: { title: 'API Document', version: '0.0.1' } },
+// ) {
+//   router.register('GET', normalizePath(endpoint) + '/*', pageRoute)
+//   router.register(
+//     'GET',
+//     normalizePath(endpoint) + '/api-swagger.json',
+//     apiRoute.bind(null, router, customFields),
+//   )
+// }
+
+// /**
+//  * ---------------------------------
+//  * swagger 页面路由
+//  * ---------------------------------
+//  */
+// async function pageRoute({ response }: BaseContext, pathParameters: PathParameters) {
+//   const file = (pathParameters['*'] ?? '') || 'index.html'
+
+//   const swaggerDir = getAbsoluteFSPath()
+//   const abspath = path.join(swaggerDir, file)
+//   if (!cache.has(abspath)) {
+//     try {
+//       const stat = await fsPromise.stat(abspath)
+//       if (!stat.isFile()) throw new HTTPError(404)
+//     } catch (e) {
+//       throw new HTTPError(404)
+//     }
+//     const content = await fsPromise.readFile(abspath)
+//     const replacemented = replacement(abspath, content)
+//     cache.set(abspath, replacemented)
+//   }
+//   response.text(cache.get(abspath)!)
+// }
+
+// const cache = new Map<string, Buffer | string>()
+
+// function replacement(abspath: string, content: Buffer) {
+//   if (/swagger-initializer.js/.exec(abspath)) {
+//     return content
+//       .toString()
+//       .replace('https://petstore.swagger.io/v2/swagger.json', './api-swagger.json')
+//     // .replace('SwaggerUIBundle({', 'SwaggerUIBundle({\n    defaultModelsExpandDepth: 1,\n    defaultModelExpandDepth: 1,')
+//   }
+//   return content
+// }
+
+// /**
+//  * ---------------------------------
+//  * swagger API 路由
+//  * ---------------------------------
+//  */
+// type OpenAPICustomFields = Omit<OpenAPI, 'openapi' | 'paths' | 'components'>
+
+// function apiRoute(router: Router, customFields: OpenAPICustomFields, { response }: BaseContext) {
+//   const swaggerJSON: OpenAPI = {
+//     ...customFields,
+//     openapi: '3.1.0',
+//     paths: makePaths(router),
+//     components: {
+//       schemas: makeRefs(router),
+//     },
+//   }
+//   response.json(swaggerJSON)
+// }
+
+// function makeRefs(router: Router) {
+//   const schemas: Record<string, Schema> = {}
+//   for (const [id, type] of Object.entries(router.responseReferences)) {
+//     schemas[id] = responseDataType2Schema(type)
+//   }
+//   return schemas
+// }
+
+// function makePaths(router: Router) {
+//   const paths: Record<string, PathItem> = {}
+//   return paths
+// }
+
+// function responseDataType2Schema(type: ResponseDataType): Schema {
+//   if (type === 'null') return { nullable: true }
+//   if (typeof type === 'object' && 'array' in type && type.array.includes('null')) {
+//     return {
+//       nullable: true,
+//       ...responseDataType2Schema(type as ResponseDataType.filter(v => v !== 'null') as ResponseDataType),
+//     }
+//   }
+
+//   const nullable = type === 'null' || (Array.isArray(type) && type.includes('null'))
+//   return {
+//     nullable,
+//   }
+// }
+
+// type Obj = { [k: string]: unknown }
+// function string(desc?: string, options?: Obj) {
+//   return { type: 'string', description: desc, ...(options ?? {}) }
+// }
+// function number(desc?: string, options?: Obj) {
+//   return { type: 'number', description: desc, ...(options ?? {}) }
+// }
+// function boolean(desc?: string, options?: Obj) {
+//   return { type: 'boolean', description: desc, ...(options ?? {}) }
+// }
+// function object(properties: unknown, extra?: Obj) {
+//   return { type: 'object', properties, ...(extra ?? {}) }
+// }
+// function array(items: unknown, extra?: Obj) {
+//   return { type: 'array', items, ...(extra ?? {}) }
+// }
+
+// function ref(name: string) {
+//   return { $ref: '#/components/schemas/' + name }
+// }
+
+// function jsonSchema(schema: string | Obj) {
+//   return {
+//     content: {
+//       'application/json': {
+//         schema: typeof schema === 'string' ? ref(schema) : schema,
+//       },
+//     },
+//   }
+// }
+
+// function route(params: {
+//   category: string
+//   describe: string
+//   path: string
+//   body?: string | Obj
+//   response?: string | Obj
+// }) {
+//   return {
+//     [params.path]: {
+//       post: {
+//         tags: [params.category],
+//         summary: params.describe,
+//         operationId: params.path,
+//         requestBody: params.body !== undefined ? jsonSchema(params.body) : undefined,
+//         responses: {
+//           default: {
+//             description: 'OK',
+//             ...jsonSchema(params.response ?? object({})),
+//           },
+//         },
+//       },
+//     },
+//   }
+// }
+
+// function response(schema: unknown) {
+//   return {
+//     type: 'object',
+//     properties: {
+//       success: boolean(undefined, { enum: [true] }),
+//       data: schema,
+//     },
+//   }
+// }
+
+// function pageResp(itemSchema: unknown) {
+//   return response({
+//     type: 'object',
+//     properties: {
+//       total: number(),
+//       list: array(itemSchema),
+//     },
+//   })
+// }