wok-server 0.4.13 → 0.6.0

package/src/mongodb/manager/index.ts

@@ -0,0 +1,80 @@
+import { Db, MongoClient, ReadConcernLike, ReadPreferenceLike, WriteConcern } from 'mongodb'
+import { MongoDBConfig } from '../config'
+import { MongoDBException } from '../exception'
+import { BaseMongoManager } from './base'
+import { MongoTxSession } from './tx'
+import { MongoStrictTxSession } from './tx-strict'
+
+/**
+ * mysql 分页查询结果
+ */
+export interface MongoPage<T> {
+  total: number
+  list: T[]
+}
+
+/**
+ * mongodb 管理器，目前尚未实现事务的处理.
+ */
+export class MongoDBManager extends BaseMongoManager {
+  /**
+   * mongodb 管理器构建
+   * @param db 库
+   */
+  constructor(config: MongoDBConfig, db: Db, private readonly client: MongoClient) {
+    super(config, db)
+  }
+  /**
+   * 事务操作。mongodb 的版本必须在 4.0 以上，连接的必须是副本集节点或分片集群的mongos节点。
+   * @param ops 操作逻辑，所有事务相关的操作都必须使用函数提供的 session 对象
+   * @param opts mongo 事务选项
+   */
+  async tx<T>(
+    ops: (session: MongoTxSession) => Promise<T>,
+    opts?: {
+      /** 超时时间，单位毫秒，设置后会覆盖全局设置，设置为0表示不限制 */
+      timeout?: number
+      /** A default read concern for commands in this transaction */
+      readConcern?: ReadConcernLike
+      /** A default writeConcern for commands in this transaction */
+      writeConcern?: WriteConcern
+      /** A default read preference for commands in this transaction */
+      readPreference?: ReadPreferenceLike
+    }
+  ): Promise<T> {
+    const timeout =
+      opts && typeof opts.timeout === 'number' ? opts.timeout : this.config.transactionTimeout
+    const nativeSession = this.client.startSession()
+    nativeSession.startTransaction(opts)
+    const txSesssion = this.config.transactionStrict
+      ? new MongoStrictTxSession(this.config, this.db, nativeSession)
+      : new MongoTxSession(this.config, this.db, nativeSession)
+    try {
+      const result =
+        timeout > 0
+          ? await Promise.race([
+              ops(txSesssion),
+              new Promise<T>((resolve, reject) => {
+                setTimeout(() => {
+                  // 立即中止会话，防止再有后续操作
+                  txSesssion.abort()
+                  reject(new MongoDBException('Transaction timeout !'))
+                }, timeout)
+              })
+            ])
+          : await ops(txSesssion)
+      await nativeSession.commitTransaction()
+      return result
+    } catch (error) {
+      await nativeSession.abortTransaction()
+      // 将原错误抛出，如果有需要，调用处可对异常做进一步的处理
+      throw error
+    } finally {
+      // 无论如何中止会话，离开事务，会话就不能再被使用
+      txSesssion.abort()
+      await nativeSession.endSession()
+    }
+  }
+}
+
+export { BaseMongoManager, MongoTxSession }

package/src/mongodb/manager/tx-strict.ts

@@ -0,0 +1,153 @@
+import { ClientSession, Db, Document, Filter, UpdateFilter } from 'mongodb'
+import { MongoCollection } from '../collection'
+import { MongoDBConfig } from '../config'
+import { MongoDocId, MongoDocWithId } from '../doc'
+import { MongoDBException } from '../exception'
+import { MongoPage } from './base'
+import { MongoTxSession } from './tx'
+
+/**
+ * 严格事务会话
+ */
+export class MongoStrictTxSession extends MongoTxSession {
+  #opsCount = 0
+  constructor(config: MongoDBConfig, db: Db, session: ClientSession) {
+    super(config, db, session)
+  }
+  /**
+   * 为操作计数，检查是否操作次数过多.
+   */
+  #checkAndAddOpsCount() {
+    if (this.#opsCount >= 10) {
+      throw new MongoDBException('Too many operations in a strict transaction.')
+    }
+    this.#opsCount++
+  }
+
+  findById<T extends Document>(
+    coll: MongoCollection<T>,
+    id: MongoDocId
+  ): Promise<MongoDocWithId<T> | null> {
+    this.#checkAndAddOpsCount()
+    return super.findById(coll, id)
+  }
+
+  findByIdIn<T extends Document>(
+    coll: MongoCollection<T>,
+    ids: MongoDocId[]
+  ): Promise<MongoDocWithId<T>[]> {
+    if (ids.length > 100) {
+      throw new MongoDBException(
+        `The augument ids length(${ids.length}) passed to findByIdIn in a strict transaction is too large .`
+      )
+    }
+    this.#checkAndAddOpsCount()
+    return super.findByIdIn(coll, ids)
+  }
+
+  existsBy<T extends Document>(
+    coll: MongoCollection<T>,
+    filter: Filter<MongoDocWithId<T>>
+  ): Promise<boolean> {
+    this.#checkAndAddOpsCount()
+    return super.existsBy(coll, filter)
+  }
+
+  deleteById<T extends Document>(coll: MongoCollection<T>, id: MongoDocId): Promise<boolean> {
+    this.#checkAndAddOpsCount()
+    return super.deleteById(coll, id)
+  }
+
+  deleteOne<T extends Document>(coll: MongoCollection<T>, filter: Partial<T>): Promise<boolean> {
+    this.#checkAndAddOpsCount()
+    return super.deleteOne(coll, filter)
+  }
+
+  deleteMany<T extends Document>(
+    coll: MongoCollection<T>,
+    filter: Filter<MongoDocWithId<T>>
+  ): Promise<number> {
+    throw new MongoDBException('Prohibited to use deleteMany in a strict transaction.')
+  }
+
+  findAll<T extends Document>(coll: MongoCollection<T>): Promise<MongoDocWithId<T>[]> {
+    throw new MongoDBException('Prohibited to use findAll in a strict transaction.')
+  }
+
+  findFirst<T extends Document>(
+    coll: MongoCollection<T>,
+    filter: Filter<MongoDocWithId<T>>
+  ): Promise<MongoDocWithId<T> | null> {
+    this.#checkAndAddOpsCount()
+    return super.findFirst(coll, filter)
+  }
+
+  insert<T extends Document>(
+    coll: MongoCollection<T>,
+    data: T & { _id?: MongoDocId | undefined }
+  ): Promise<MongoDocWithId<T>> {
+    this.#checkAndAddOpsCount()
+    return super.insert(coll, data)
+  }
+
+  insertMany<T extends Document>(
+    coll: MongoCollection<T>,
+    list: (T & { _id?: MongoDocId | undefined })[]
+  ): Promise<MongoDocWithId<T>[]> {
+    throw new MongoDBException('Prohibited to use insertMany in a strict transaction.')
+  }
+
+  update<T extends Document>(
+    coll: MongoCollection<T>,
+    data: MongoDocWithId<T>
+  ): Promise<MongoDocWithId<T>> {
+    this.#checkAndAddOpsCount()
+    return super.update(coll, data)
+  }
+
+  partialUpdate<T extends Document>(
+    coll: MongoCollection<T>,
+    id: MongoDocId,
+    updator: UpdateFilter<T>
+  ): Promise<boolean> {
+    this.#checkAndAddOpsCount()
+    return super.partialUpdate(coll, id, updator)
+  }
+
+  updateMany<T extends Document>(
+    coll: MongoCollection<T>,
+    filter: Filter<MongoDocWithId<T>>,
+    updator: UpdateFilter<T>
+  ): Promise<number> {
+    throw new MongoDBException('Prohibited to use updateMany in a strict transaction.')
+  }
+
+  find<T extends Document>(
+    coll: MongoCollection<T>,
+    filter: Filter<MongoDocWithId<T>>,
+    opts?:
+      | {
+          offset?: number | undefined
+          limit?: number | undefined
+          orderBy?: ['_id' | keyof T, 'asc' | 'desc'][] | undefined
+        }
+      | undefined
+  ): Promise<MongoDocWithId<T>[]> {
+    throw new MongoDBException('Prohibited to use find in a strict transaction.')
+  }
+
+  count<T extends Document>(
+    coll: MongoCollection<T>,
+    filter: Filter<MongoDocWithId<T>>
+  ): Promise<number> {
+    throw new MongoDBException('Prohibited to use count in a strict transaction.')
+  }
+
+  paginate<T extends Document>(
+    coll: MongoCollection<T>,
+    filter: Filter<MongoDocWithId<T>>,
+    opts: { pn: number; pz: number; orderBy?: ['_id' | keyof T, 'asc' | 'desc'][] | undefined }
+  ): Promise<MongoPage<MongoDocWithId<T>>> {
+    throw new MongoDBException('Prohibited to use paginate in a strict transaction.')
+  }
+}

package/src/mongodb/manager/tx.ts

@@ -0,0 +1,34 @@
+import { ClientSession, Db } from 'mongodb'
+import { MongoDBConfig } from '../config'
+import { MongoDBException } from '../exception'
+import { BaseMongoManager } from './base'
+/**
+ * 事务会话
+ */
+export class MongoTxSession extends BaseMongoManager {
+  /**
+   * 中止标识
+   */
+  #aborted = false
+
+  constructor(config: MongoDBConfig, db: Db, session: ClientSession) {
+    super(config, db, session)
+  }
+
+  protected timingQuery<T, D extends { op: string; coll: string }>(opts: {
+    query: () => Promise<T>
+    desc: () => D
+  }): Promise<T> {
+    if (this.#aborted) {
+      throw new MongoDBException('Session has been aborted!')
+    }
+    return super.timingQuery(opts)
+  }
+
+  /**
+   * 中止，被中止后的会话不能再进行任何操作
+   */
+  abort() {
+    this.#aborted = true
+  }
+}

package/src/mongodb/migration.ts

@@ -0,0 +1,66 @@
+import { Db } from 'mongodb'
+import { MongoDBException } from './exception'
+import { getLogger } from '../log'
+
+/**
+ * 迁移版本，是一个函数，可以在函数的内部通过 mongodb 驱动提升的 api 来完成操作。
+ * 注：驱动里有些 api 是没有的，和 mongodb 的脚本有区分，但是有些是可以通过 db.command() 来替代的。
+ */
+export type MongoMigrationVersion = (db: Db) => Promise<void>
+
+/**
+ * 迁移
+ * @param db
+ * @param versionList
+ */
+export async function migrate(db: Db, versionList: MongoMigrationVersion[]) {
+  let currentVersion = await getCurrentVersion(db)
+  // 逐个执行，迁移执行的逻辑是无法提供事务支持的
+  // 版本管理代码是自定义的，无法做到强制绑定 session
+  // 一旦出错，只能手动处理数据库，然后再重新执行程序，和 mysql 一样
+  for (let idx = 0; idx < versionList.length; idx++) {
+    if (idx <= currentVersion) {
+      continue
+    }
+    const migrationVersion = versionList[idx]
+    getLogger().info(`MongoDB migrating, version: ${idx}`)
+    await migrationVersion(db)
+    await updateVersion(db, idx)
+  }
+}
+
+/**
+ * 版本管理集合.
+ */
+interface VersionColl {
+  _id: string
+  version: number
+}
+
+const VERSION_COLLECTION_NAME = 'db_version'
+const VERSION_RECORD_ID = 'db_version'
+
+async function getCurrentVersion(db: Db): Promise<number> {
+  const res = await db
+    .collection<VersionColl>(VERSION_COLLECTION_NAME)
+    .findOne({ _id: VERSION_RECORD_ID })
+  return res ? res.version : -1
+}
+
+/**
+ * 更新版本号
+ * @param db
+ * @param version
+ */
+async function updateVersion(db: Db, version: number) {
+  const collection = db.collection<VersionColl>(VERSION_COLLECTION_NAME)
+  const res = await collection.findOne({ _id: VERSION_RECORD_ID })
+  if (res) {
+    const rs = await collection.updateOne({ _id: VERSION_RECORD_ID }, { $set: { version } })
+    if (rs.modifiedCount !== 1) {
+      throw new MongoDBException('Failed to update version.')
+    }
+  } else {
+    await collection.insertOne({ _id: VERSION_RECORD_ID, version: version })
+  }
+}

package/src/mvc/access-log.ts

@@ -0,0 +1,33 @@
+import { getLogger } from '../log'
+import { formatDateTime } from '../log/date'
+import { Interceptor } from './interceptor'
+
+/**
+ * 访问日志拦截器，记录请求信息
+ * @param exchange
+ * @param next
+ */
+export const accessLogInterceptor: Interceptor = async (exchange, next) => {
+  const start = new Date().getTime()
+  exchange.response.once('close', () => {
+    const userAgent = exchange.request.headers['user-agent']
+    const referer = exchange.request.headers['referer']
+    const ip = exchange.request.socket.remoteAddress
+    const { url, method } = exchange.request
+    const status = exchange.response.statusCode
+    const rt = new Date().getTime() - start
+    getLogger().info(
+      `[access-log]${JSON.stringify({
+        method,
+        url,
+        ip,
+        userAgent,
+        referer,
+        start: formatDateTime(new Date(start)),
+        rt,
+        status
+      })}`
+    )
+  })
+  await next()
+}

package/src/mvc/config.ts

@@ -0,0 +1,70 @@
+import { generateConfig } from '../config'
+import { max, min, notBlank, notNull } from '../validation'
+
+/**
+ * mvc 模块配置.
+ */
+export interface WebConfig {
+  /**
+   * 端口号
+   */
+  port: number
+  /**
+   * 超时时间
+   */
+  timeout: number
+  /**
+   * 是否开启访问日志.
+   */
+  accessLog: boolean
+  /**
+   * 跨域允许的源域名
+   */
+  corsAllowOrigin: string
+  /**
+   * 跨域允许的消息头
+   */
+  corsAllowHeaders: string
+  /**
+   * 跨域允许的请求方法
+   */
+  corsAllowMethods: string
+  /**
+   * 是否激活安全传输层
+   */
+  tlsEnable: boolean
+  /**
+   * pem 格式证书公钥文件路径
+   */
+  tlsCert: string
+  /**
+   * pem 格式证书私钥文件路径
+   */
+  tlsKey: string
+}
+
+export function getConfig() {
+  return generateConfig<WebConfig>(
+    {
+      port: 8080,
+      timeout: 30000,
+      accessLog: false,
+      corsAllowHeaders: '*',
+      corsAllowMethods: '*',
+      corsAllowOrigin: '*',
+      tlsEnable: false,
+      tlsKey: '',
+      tlsCert: ''
+    },
+    'SERVER',
+    {
+      port: [notNull(), min(80), max(65535)],
+      timeout: [notNull(), min(1000), max(600000)],
+      accessLog: [notNull()],
+      corsAllowOrigin: [notBlank()],
+      corsAllowHeaders: [notBlank()],
+      corsAllowMethods: [notBlank()],
+      tlsEnable: [notNull()]
+    }
+  )
+}

package/src/mvc/exchange.ts

@@ -0,0 +1,126 @@
+import { IncomingMessage, ServerResponse } from 'http'
+import { QueryString } from './query'
+import { HtmlStuct, renderError, renderFile, renderHtml, renderJson } from './render'
+import { renderText } from './render/text'
+
+/**
+ * 服务的数据交换对象.
+ */
+export class ServerExchange {
+  #bufferPromise?: Promise<Buffer>
+
+  constructor(readonly request: IncomingMessage, readonly response: ServerResponse) {}
+
+  bodyBuffer(): Promise<Buffer> {
+    if (this.#bufferPromise) {
+      return this.#bufferPromise
+    }
+    this.#bufferPromise = new Promise<Buffer>((resolve, reject) => {
+      if (this.request.readableEnded) {
+        throw new Error('Request has ended!')
+      }
+      let body: Buffer[] = []
+      this.request
+        .resume()
+        .on('error', reject)
+        .on('data', chunk => body.push(chunk))
+        .on('end', () => resolve(Buffer.concat(body)))
+    })
+    return this.#bufferPromise
+  }
+
+  async bodyText(): Promise<string> {
+    const buffer = await this.bodyBuffer()
+    return buffer.toString('utf-8')
+  }
+
+  async bodyJson<T>(): Promise<T> {
+    const buffer = await this.bodyBuffer()
+    const bodyText = buffer.toString('utf-8')
+    if (!bodyText || !bodyText.trim()) {
+      return {} as any
+    }
+    return JSON.parse(bodyText)
+  }
+  /**
+   * 响应纯文本
+   * @param text 文本内容
+   * @param status 状态码，可选，默认 200
+   */
+  respondText(text: string, status?: number) {
+    renderText(this.response, text, status)
+  }
+
+  /**
+   * 响应 json
+   * @param json 任意可被 json 序列化的对象
+   * @param status 状态码，可选，默认 200
+   */
+  respondJson(json: any, status?: number) {
+    renderJson(this.response, json, status)
+  }
+  /**
+   * 响应错误信息提示，提供一个统一的格式封装，json 格式
+   * @param message 消息
+   * @param status 状态码，默认 400 ，表示业务错误
+   * @returns
+   */
+  respondErrMsg(message: string, status?: number) {
+    renderError(this.response, message, status)
+  }
+  /**
+   * 响应文件
+   * @param filePath 文件路径，绝对路径
+   * @param download 是否下载模式
+   * @returns
+   */
+  respondFile(filePath: string, download?: boolean) {
+    return renderFile(this.request, this.response, filePath, download)
+  }
+  /**
+   * 响应 html
+   * @param html html 内容，一个特定结构的对象或者是字符串
+   * @param status 状态码，可选，默认 200
+   */
+  respondHtml(html: HtmlStuct | string, status?: number) {
+    renderHtml(this.response, html, status)
+  }
+
+  /**
+   * 响应
+   * @param opts
+   */
+  respond(opts: {
+    /**
+     * 状态码.
+     */
+    statusCode: number
+    /**
+     * 响应正文内容.
+     */
+    body?: string | Buffer | Uint8Array
+    /**
+     * 自定义消息头
+     */
+    headers?: Record<string, string>
+  }) {
+    this.response.statusCode = opts.statusCode
+    if (opts.headers) {
+      for (const key in opts.headers) {
+        this.response.setHeader(key, opts.headers[key])
+      }
+    }
+    if (opts.body) {
+      this.response.write(opts.body)
+    }
+    this.response.end()
+  }
+
+  /**
+   * 解析 queryString
+   * @returns
+   */
+  parseQueryString() {
+    return new QueryString(this.request.url || '')
+  }
+}

package/src/mvc/handler/index.ts

@@ -0,0 +1,4 @@
+export * from './json'
+export * from './upload'
+export * from './restful'
+export * from './sse'

package/src/mvc/handler/json.ts

@@ -0,0 +1,96 @@
+import { IncomingMessage } from 'http'
+import { getCache } from '../../cache'
+import { getI18n } from '../../i18n'
+import { validate, ValidationOpts } from '../../validation'
+import { ServerExchange } from '../exchange'
+import { RouterHandler } from '../router'
+
+export interface JsonHandlerExchange {
+  /**
+   * 请求信息
+   */
+  request: IncomingMessage
+}
+
+/**
+ * 创建 json 处理器..
+ * @param <REQ> 表示请求的 json 数据格式类型
+ * @param <RES> 表示响应的类型，可选，如果不需要响应 json 数据，则方法可以不返回任何值
+ * @param opts
+ * @returns
+ */
+export function createJsonHandler<REQ, RES = void>(opts: {
+  /**
+   * 缓存设置，通过框架的 cache 模块来缓存响应信息，只能缓存有效的响应信息，如果没有响应正文则不会进行缓存,
+   * 参数和 handle 是一样的
+   * @param body
+   * @param exchange
+   * @returns 返回缓存的 key 和缓存秒数
+   */
+  cache?: (
+    body: REQ,
+    exchange: JsonHandlerExchange
+  ) =>
+    | Promise<{ key: string; expiresInSeconds?: number }>
+    | { key: string; expiresInSeconds?: number }
+  /**
+   * 校验信息，可选，用于检查请求信息.对于一些特殊情况，无法使用校验器的，可以在 handle 中继续处理.
+   */
+  validation?: ValidationOpts<REQ> | (() => ValidationOpts<REQ>)
+  /**
+   * 处理请求.
+   * @param body 正文内容
+   * @param exchange 请求传输对象，用于获取请求的基本信息
+   * @returns
+   */
+  handle: (body: REQ, exchange: JsonHandlerExchange) => Promise<RES>
+}): RouterHandler {
+  return async function (exchange: ServerExchange) {
+    if (!exchange.request.method || exchange.request.method.toUpperCase() !== 'POST') {
+      exchange.respondErrMsg('Method Not Allowed', 405)
+      return
+    }
+    const body: REQ = await exchange.bodyJson()
+    if (opts.validation) {
+      // 切换语言
+      getI18n().switchByRequest(exchange.request.headers)
+      if (typeof opts.validation === 'function') {
+        validate(body, opts.validation())
+      } else {
+        validate(body, opts.validation)
+      }
+    }
+    // 缓存处理
+    if (opts.cache) {
+      const cacheInfo = await opts.cache(body, exchange)
+      const buffer = getCache().get(cacheInfo.key)
+      if (buffer && buffer instanceof Buffer) {
+        renderJsonBuffer(exchange, buffer)
+      } else {
+        const res = await opts.handle(body, { request: exchange.request })
+        if (!res) {
+          // 无结果不缓存
+          exchange.respond({ statusCode: 200 })
+          return
+        }
+        const buffer = Buffer.from(JSON.stringify(res), 'utf-8')
+        getCache().put(cacheInfo.key, buffer, cacheInfo.expiresInSeconds)
+        renderJsonBuffer(exchange, buffer)
+      }
+      return
+    }
+    const res = await opts.handle(body, { request: exchange.request })
+    if (!res) {
+      exchange.respond({ statusCode: 200 })
+      return
+    }
+    exchange.respondJson(res)
+  }
+}
+
+function renderJsonBuffer(exchange: ServerExchange, buffer: Buffer) {
+  const { response } = exchange
+  response.setHeader('content-type', 'application/json; charset=UTF-8')
+  response.statusCode = 200
+  response.end(buffer)
+}