wok-server 0.5.0 → 0.6.0

package/src/mvc/handler/restful.ts

@@ -0,0 +1,39 @@
+import { RouterHandler } from '../router'
+
+/**
+ * 构建 restful 风格路由
+ */
+export function restful(opts: {
+  get?: RouterHandler
+  post?: RouterHandler
+  put?: RouterHandler
+  patch?: RouterHandler
+  delete?: RouterHandler
+}): RouterHandler {
+  return async exchange => {
+    const method = (exchange.request.method || '').toLowerCase()
+    let handler: RouterHandler | undefined
+    switch (method) {
+      case 'get':
+        handler = opts.get
+        break
+      case 'post':
+        handler = opts.post
+        break
+      case 'put':
+        handler = opts.put
+        break
+      case 'patch':
+        handler = opts.patch
+        break
+      case 'delete':
+        handler = opts.delete
+        break
+    }
+    if (!handler) {
+      exchange.respondErrMsg(`${method} ${exchange.request.url} not found`, 404)
+      return
+    }
+    await handler(exchange)
+  }
+}

package/src/mvc/handler/sse.ts

@@ -0,0 +1,90 @@
+import { IncomingMessage, ServerResponse } from 'http'
+import { ServerExchange } from '../exchange'
+import { RouterHandler } from '../router'
+
+export interface SseContext {
+  /**
+   * 请求信息
+   */
+  readonly request: IncomingMessage
+  /**
+   * 响应信息
+   */
+  readonly response: ServerResponse
+  /**
+   * 发送 SSE 事件
+   * @param data 事件数据，会被 JSON 序列化
+   * @param event 事件名称，可选。前端可通过 addEventListener 监听
+   * @param id 事件 ID，可选。用于断线重连时的 Last-Event-ID
+   */
+  send(data: any, event?: string, id?: string): void
+  /**
+   * 结束 SSE 连接
+   */
+  close(): void
+}
+
+/**
+ * 创建 SSE (Server-Sent Events) 处理器.
+ * 用于服务端向客户端单向推送实时数据。
+ *
+ * @param opts
+ * @returns
+ */
+export function createSseHandler(opts: {
+  handle: (ctx: SseContext) => Promise<void>
+}): RouterHandler {
+  return async function (exchange: ServerExchange) {
+    const { request, response } = exchange
+
+    response.statusCode = 200
+    response.setHeader('Content-Type', 'text/event-stream')
+    response.setHeader('Cache-Control', 'no-cache')
+    response.setHeader('Connection', 'keep-alive')
+    response.setHeader('X-Accel-Buffering', 'no')
+    response.flushHeaders()
+
+    let isEnded = false
+
+    const ctx: SseContext = {
+      request,
+      response,
+      send(data: any, event?: string, id?: string) {
+        if (isEnded) return
+        if (id !== undefined) {
+          response.write(`id: ${id}\n`)
+        }
+        if (event) {
+          response.write(`event: ${event}\n`)
+        }
+        if (Array.isArray(data)) {
+          for (const item of data) {
+            response.write(`data: ${JSON.stringify(item)}\n`)
+          }
+        } else {
+          response.write(`data: ${JSON.stringify(data)}\n`)
+        }
+        response.write('\n')
+      },
+      close() {
+        if (isEnded) return
+        isEnded = true
+        response.end()
+      }
+    }
+
+    function safeEnd() {
+      if (isEnded) return
+      isEnded = true
+      response.end()
+    }
+
+    request.on('close', safeEnd)
+
+    try {
+      await opts.handle(ctx)
+    } finally {
+      safeEnd()
+    }
+  }
+}

package/src/mvc/handler/upload.ts

@@ -0,0 +1,54 @@
+import { IncomingMessage } from 'http'
+import { ServerExchange } from '../exchange'
+import { QueryString } from '../query'
+import { RouterHandler } from '../router'
+
+/**
+ * 上传请求传输对象.
+ */
+export interface UploadHandlerExchange {
+  /**
+   * 请求信息
+   */
+  request: IncomingMessage
+  /**
+   * querystring 解析结果
+   */
+  query: QueryString
+}
+
+/**
+ * 创建上传处理器. 上传要求一次只能传输一个文件，并且请求正文就是文件二进制内容。
+ * 必须是 post 请求，额外的参数只能通过 queryString 或 header 来传递。
+ * 和 postman 中的 binary 模式是一致的，这样上传文件性能会好一些，但是局限性也很大。
+ *
+ * @param opts
+ * @param <RES> 响应json数据类型
+ * @returns
+ */
+export function createUploadHandler<RES = void>(opts: {
+  /**
+   * 处理请求.
+   * @param body 正文内容
+   * @param exchange 请求传输对象，用于获取请求的基本信息
+   * @returns
+   */
+  handle: (body: Buffer, exchange: UploadHandlerExchange) => 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 = await exchange.bodyBuffer()
+    const res = await opts.handle(body, {
+      request: exchange.request,
+      query: exchange.parseQueryString()
+    })
+    if (!res) {
+      exchange.respond({ statusCode: 200 })
+      return
+    }
+    exchange.respondJson(res)
+  }
+}

package/src/mvc/index.ts

@@ -0,0 +1,48 @@
+import { WokServer, WokServerOpts } from './server'
+
+/**
+ * 服务实例.
+ */
+let SERVER: WokServer | undefined
+
+/**
+ * 删除服务器静态缓存
+ * @param path 路径，必须以斜杠开头，如：/assets/index.js
+ */
+export async function removeServerStaticCache(path: string) {
+  if (SERVER) {
+    SERVER.removeServerStaticCache(path)
+  }
+}
+
+/**
+ * 启动 web服务
+ * @param opts
+ */
+export async function startWebServer(opts: WokServerOpts) {
+  if (SERVER) {
+    throw new Error('The server has already been started!')
+  }
+  SERVER = new WokServer(opts)
+  await SERVER.start()
+}
+/**
+ * 停止 web 服务
+ * @returns
+ */
+export async function stopWebServer() {
+  if (!SERVER) {
+    return
+  }
+  SERVER.stop()
+  SERVER = undefined
+}
+
+process.on('beforeExit', stopWebServer)
+
+export * from './exchange'
+export * from './handler'
+export * from './interceptor'
+export * from './render'
+export * from './router'
+export * from './static'

package/src/mvc/interceptor.ts

@@ -0,0 +1,12 @@
+import { ServerExchange } from './exchange'
+
+/**
+ * 拦截器.
+ */
+export interface Interceptor {
+  /**
+   * @param exchange 传输对象，提供获取请求信息和通用的响应数据功能
+   * @param next 执行后面的流程，可能是下一个拦截器，也可能是路由
+   */
+  (exchange: ServerExchange, next: () => Promise<void>): Promise<void>
+}

package/src/mvc/query.ts

@@ -0,0 +1,36 @@
+import { ParsedUrlQuery, parse } from 'querystring'
+
+export class QueryString {
+  private qs: ParsedUrlQuery
+  constructor(url: string) {
+    const idx = url.indexOf('?')
+    this.qs = idx !== -1 ? parse(url.substring(idx + 1)) : {}
+  }
+  /**
+   * 获取单个字符串值
+   * @param name
+   */
+  getStr(name: string) {
+    const res = this.qs[name]
+    if (!res) {
+      return undefined
+    } else if (typeof res === 'string') {
+      return res
+    } else {
+      return res[0]
+    }
+  }
+  /**
+   * 获取参数的所有值
+   */
+  getStrVals(name: string) {
+    const res = this.qs[name]
+    if (!res) {
+      return undefined
+    } else if (typeof res === 'string') {
+      return [res]
+    } else {
+      return res
+    }
+  }
+}

package/src/mvc/render/file.ts

@@ -0,0 +1,148 @@
+import { createReadStream, existsSync } from 'fs'
+import { stat } from 'fs/promises'
+import { IncomingMessage, ServerResponse } from 'http'
+import { basename } from 'path'
+import { createGzip } from 'zlib'
+import { decideContentType } from '../static'
+import { renderError } from './json'
+
+
+/**
+ * 响应一个文件.
+ * @param request  请求信息
+ * @param response 响应信息
+ * @param filePath 文件路径，如果文件不存在，则会响应 404
+ * @param download 是否下载
+ */
+export async function renderFile(
+  request: IncomingMessage,
+  response: ServerResponse,
+  filePath: string,
+  download = false
+): Promise<void> {
+  if (!existsSync(filePath)) {
+    renderError(response, 'Cannot find file.', 404)
+    return
+  }
+  const fileName = basename(filePath)
+
+  let isDownload = false
+  let contentType: string | undefined
+  if (download) {
+    isDownload = true
+  } else {
+    contentType = decideContentType(fileName)
+    if (!contentType) {
+      isDownload = true
+    }
+  }
+
+  if (isDownload) {
+    response.setHeader('Content-Type', 'application/octet-stream')
+    response.setHeader(
+      'Content-Disposition',
+      `attachment; filename="${encodeURIComponent(fileName)}"`
+    )
+  } else if (contentType) {
+    response.setHeader('Content-Type', contentType)
+  }
+  const statRes = await stat(filePath)
+  // 支持 If-Modified-Since
+  // 由于只是简单的文件映射，没有 etag，不能支持 If-None-Match
+  // 缓存校验只能支持时间的比对，修改时间是文件系统本来就有的
+  if (request.headers['if-modified-since']) {
+    const modifiedSince = new Date(request.headers['if-modified-since'])
+    // 判定日期是否有效
+    if (modifiedSince instanceof Date && !isNaN(modifiedSince.getTime())) {
+      // 比较更改日期，只精确到秒, UTC 格式只精确到秒，但是 mtime 是包含毫秒的
+      const { mtime } = statRes
+      mtime.setMilliseconds(0)
+      if (modifiedSince >= mtime) {
+        response.statusCode = 304
+        response.setHeader('Last-Modified', statRes.mtime.toUTCString())
+        response.end()
+        return
+      }
+    }
+  }
+
+  // 支持 Range
+  // https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/Range
+  const rangeHeader = request.headers['range']
+  if (!rangeHeader) {
+    response.setHeader('Last-Modified', statRes.mtime.toUTCString())
+    return streamFile(filePath, request, response)
+  }
+  // 解析，range 示例：bytes=200-1000, 2000-6576, 19000-
+  // 多段的情况，暂时不做支持，非常麻烦，段数多还可能会有效率问题
+  // 如果不是字节范围不是以字节为单位，暂时也不做支持
+  const ranges = rangeHeader.split(',')
+  let range = ranges.length ? ranges[0] : undefined
+  if (!range) {
+    return streamFile(filePath, request, response)
+  }
+  range = range.trim()
+  if (!range.startsWith('bytes=')) {
+    return streamFile(filePath, request, response)
+  }
+  range = range.substring(6)
+  const strs = range.split('-')
+  let start = strs[0] ? parseInt(strs[0], 10) : NaN
+  let end = strs[1] ? parseInt(strs[1], 10) : NaN
+  // 解析文件
+  if (isNaN(start) || start < 0) {
+    // 范围不合法，返回 416
+    renderError(response, `Range not satisfiable，start is ${start}`, 416)
+    return
+  }
+  if (isNaN(end)) {
+    end = statRes.size - 1
+  } else if (end > statRes.size - 1) {
+    // 范围不合法，返回 416
+    renderError(
+      response,
+      `Range not satisfiable，end must not be greater than ${statRes.size - 1}`,
+      416
+    )
+    return
+  }
+  // 注：Range 和 Content-Range 还有 createReadStream 中的字节范围，都是前后全包含的
+  // Content-Range: bytes 42-1233/1234
+  response.setHeader('Content-Range', `bytes ${start}-${end}/${statRes.size}`)
+  return streamFile(filePath, request, response, { start, end })
+}
+
+function streamFile(
+  filePath: string,
+  request: IncomingMessage,
+  response: ServerResponse,
+  opts?: { start?: number; end?: number }
+): Promise<void> {
+  return new Promise<void>((res, rej) => {
+    if (opts && typeof opts.start === 'number') {
+      // 部分返回 206
+      response.statusCode = 206
+    } else {
+      // 全部返回 200
+      response.statusCode = 200
+    }
+    // 支持 gzip
+    const acceptEncoding = request.headers['accept-encoding'] as string
+    if (acceptEncoding) {
+      // Accept-Encoding: br;q=1.0, gzip;q=0.8, *;q=0.1
+      const acceptEncodings = acceptEncoding
+        .trim()
+        .split(',')
+        .map(item => item.trim())
+        .map(item => item.split(';')[0])
+      if (acceptEncodings.includes('gzip') || acceptEncodings.includes('*')) {
+        response.setHeader('Content-Encoding', 'gzip')
+        createReadStream(filePath, opts).pipe(createGzip()).pipe(response)
+        response.once('finish', res).once('error', rej)
+        return
+      }
+    }
+    createReadStream(filePath, opts).pipe(response)
+    response.once('finish', res).once('error', rej)
+  })
+}

package/src/mvc/render/html/html.ts

@@ -0,0 +1,187 @@
+import { CSSStyleDeclaration } from './style'
+
+/**
+ * 全局属性.
+ * https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes
+ */
+export interface GlobalAttrs {
+  accesskey?: string
+  id?: string
+  autocapitalize?: 'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters'
+  autofocus?: boolean
+  class?: string
+  contenteditable?: boolean | 'plaintext-only'
+  dir?: 'ltr' | 'rtl' | 'auto'
+  draggable?: boolean
+  enterkeyhint?: string
+  hidden?: string
+  inert?: boolean
+  inputmode?: 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url'
+  is?: string
+  itemid?: string
+  itemprop?: string
+  itemref?: string
+  itemscope?: string
+  itemtype?: string
+  lang?: string
+  nonce?: string
+  part?: string
+  popover?: string
+  role?: string
+  slot?: string
+  spellcheck?: string
+  style?: CSSStyleDeclaration | string
+  tabindex?: string
+  title?: string
+  translate?: 'yes' | 'no'
+  virtualkeyboardpolicy?: 'auto' | 'manual'
+}
+/**
+ * 子元素选项，子元素可以是一个标签也可以是字符串（表示文本，对应 TextNode）。子元素列表
+ * 可以传一个数组，也可以传一个函数，函数的参数是一个添加函数，通过这个添加函数来
+ * 动态添加子元素.
+ */
+export type SubElementsOpt =
+  | Array<HtmlTag | string>
+  | ((add: (...child: Array<HtmlTag | string>) => void) => void)
+
+export interface HtmlAttrs extends GlobalAttrs {
+  [key: string]: any
+}
+/**
+ * 标签定义
+ */
+export interface HtmlTag {
+  /**
+   * 标签名称
+   */
+  tag: string
+  /**
+   * 是否自闭合标签，自闭合符合是不渲染子元素内容的，如 <br/>
+   */
+  selfClosing?: boolean
+  /**
+   * 属性
+   */
+  attrs?: HtmlAttrs
+  /**
+   * 子元素.
+   */
+  children?: SubElementsOpt
+}
+
+function encodeAttrs(attrs: HtmlAttrs) {
+  return Object.entries(attrs)
+    .map(entry => {
+      const [name, value] = entry
+      return { name, value }
+    })
+    .filter(attr => attr.value !== undefined)
+    .map(attr => {
+      const { name } = attr
+      const value = attr.value as any
+      if (name === 'style') {
+        if (typeof value === 'string') {
+          return value
+        }
+        const style = value as CSSStyleDeclaration
+        return Object.entries(style)
+          .map<string>(entry => `${entry[0]}:${entry[1]}`)
+          .join(';')
+      }
+      if (typeof value === 'boolean' && value) {
+        return `${name}`
+      }
+      if (typeof value === 'string') {
+        return `${name}="${value.replace(/"/g, '&quot;')}"`
+      }
+      return `${name}="${value}"`
+    })
+    .join(' ')
+}
+/**
+ * 将标签编码
+ */
+function encodeTag(tag: HtmlTag) {
+  if (tag.selfClosing) {
+    if (tag.attrs) {
+      return `<${tag.tag} ${encodeAttrs(tag.attrs)}/>`
+    }
+    return `<${tag.tag}/>`
+  }
+  let html = ''
+  html += `<${tag.tag}`
+  if (tag.attrs) {
+    html += ` ${encodeAttrs(tag.attrs)}>`
+  } else {
+    html += '>'
+  }
+  if (tag.children) {
+    if (Array.isArray(tag.children)) {
+      html += tag.children
+        .map(subTag => (typeof subTag === 'string' ? subTag : encodeTag(subTag)))
+        .join('')
+    } else {
+      const children: Array<HtmlTag | string> = []
+      tag.children((...child) => {
+        children.push(...child)
+      })
+      html += children
+        .map(subTag => (typeof subTag === 'string' ? subTag : encodeTag(subTag)))
+        .join('')
+    }
+  }
+  html += `</${tag.tag}>`
+  return html
+}
+
+/**
+ * html 结构
+ */
+export interface HtmlStuct {
+  /**
+   * 语言，根元素上的属性 lang ，示例：<html lang="zh">
+   */
+  lang?: string
+  /**
+   * head 标签内容
+   */
+  head: SubElementsOpt
+  /**
+   * body 标签内容
+   */
+  body:
+    | {
+        /**
+         * 属性
+         */
+        attrs?: HtmlAttrs
+        /**
+         * 子元素.
+         */
+        children: SubElementsOpt
+      }
+    | SubElementsOpt
+}
+/**
+ * 生成 html 代码
+ * @param html
+ */
+export function generateHtmlCode(html: HtmlStuct): string {
+  return encodeTag({
+    tag: 'html',
+    attrs: { lang: html.lang },
+    children: [
+      { tag: 'head', children: html.head },
+      {
+        tag: 'body',
+        attrs:
+          Array.isArray(html.body) || typeof html.body === 'function' ? undefined : html.body.attrs,
+        children:
+          Array.isArray(html.body) || typeof html.body === 'function'
+            ? html.body
+            : html.body.children
+      }
+    ]
+  })
+}

package/src/mvc/render/html/index.ts

@@ -0,0 +1,16 @@
+import { ServerResponse } from 'http'
+import { HtmlStuct, generateHtmlCode } from './html'
+
+/**
+ * 渲染 html
+ * @param response
+ * @param html
+ * @param status
+ */
+export function renderHtml(response: ServerResponse, html: HtmlStuct | string, status = 200) {
+  response.statusCode = status
+  response.setHeader('content-type', 'text/html; charset=utf-8')
+  response.end(typeof html === 'string' ? html : generateHtmlCode(html))
+}
+
+export * from './html'