@oyolincc/create 0.0.0-dev-20260513110237 → 0.0.0-dev-20260918103756

package/templates/hono-server/apps/server/src/infra/work-runner/example/runner.ts

@@ -0,0 +1,185 @@
+import { type WorkerConfig } from '@repo/definition/backend'
+import type {
+  AppWorkRunner,
+  RunnerTaskInvocation,
+  RunnerTaskParams,
+  RunnerTaskRunOptions,
+  RunnerTaskRunResult,
+  WorkerMessage,
+} from '../types'
+import { WorkerErrorCode, WorkSubject } from '../constants'
+import { isWorkerTaskError, WorkerTaskError } from '../errors'
+import Piscina from 'piscina'
+import path from 'node:path'
+import { MessageChannel, type MessagePort } from 'node:worker_threads'
+import workersDir from 'virtual:workers'
+import { getLogger } from '@/infra/logger/getter'
+import type * as ExampleWorker from './worker-entry'
+import { handleWorkerMessage } from '../utils/message'
+
+const taskNameMap = {
+  [WorkSubject.PROCESS_EXAMPLE]: 'executeExampleTask',
+} satisfies Partial<Record<WorkSubject, keyof typeof ExampleWorker>>
+
+export class ExampleWorkRunner implements AppWorkRunner {
+  static #instance: ExampleWorkRunner | null = null
+  readonly #pool: Piscina
+  readonly #config: WorkerConfig
+
+  private constructor(config: WorkerConfig) {
+    if (!config) {
+      throw new Error('[ExampleWorkRunner] config is required')
+    }
+    this.#pool = new Piscina({
+      filename: path.join(workersDir, 'example-worker.mjs'),
+      minThreads: config.minThreads,
+      maxThreads: config.maxThreads,
+      concurrentTasksPerWorker: config.concurrentTasksPerWorker,
+      maxQueue: config.maxQueue,
+    })
+    this.#config = config
+  }
+
+  public static getInstance(config: WorkerConfig): ExampleWorkRunner {
+    if (!this.#instance) {
+      getLogger().info({ worker: config }, 'ExampleWorkRunner initialized')
+      this.#instance = new ExampleWorkRunner(config)
+    }
+    return this.#instance
+  }
+
+  async run<TSubject extends WorkSubject>(
+    taskParams: RunnerTaskParams<TSubject>,
+    options?: RunnerTaskRunOptions,
+  ): Promise<RunnerTaskRunResult<TSubject>> {
+    const targetName = taskNameMap[taskParams.subject]
+    if (!targetName) {
+      throw new Error(`[ExampleWorkRunner] task name not found: ${taskParams.subject}`)
+    }
+
+    let timeoutTimer: ReturnType<typeof setTimeout> | undefined
+    let result: RunnerTaskRunResult<TSubject>
+    let workerMessagePort: MessagePort | undefined
+
+    const { signal: optSignal, transferList } = options || {}
+    const logger = getLogger()
+    // pool当前状态
+    const poolStats = {
+      idleThreads: this.#pool.idleThreads,
+      threads: this.#pool.threads.length,
+      queueSize: this.#pool.queueSize,
+    }
+    logger.assign({
+      pool: poolStats,
+      subject: taskParams.subject,
+    })
+
+    try {
+      optSignal?.throwIfAborted()
+
+      // 判断队列已满
+      const enableQueue = this.#pool.options.maxQueue > 0
+      if (
+        (enableQueue && poolStats.queueSize >= this.#pool.options.maxQueue) ||
+        (!enableQueue && poolStats.idleThreads <= 0)
+      ) {
+        throw new WorkerTaskError(WorkerErrorCode.QUEUE_FULL, 'Worker queue is full', {
+          enableQueue,
+          queueSize: poolStats.queueSize,
+          maxQueue: this.#config.maxQueue,
+        })
+      }
+
+      logger.debug('Worker task dispatching')
+
+      // 建立收发端
+      const { port1: messagePort, port2 } = new MessageChannel()
+      workerMessagePort = port2
+      messagePort.on('message', (message: WorkerMessage) =>
+        handleWorkerMessage(message, logger, { subject: taskParams.subject }),
+      )
+      messagePort.unref()
+
+      // 设置任务信号和超时
+      let taskSignal = optSignal
+      let timeoutPromise: Promise<never> | undefined
+      if (this.#config.workerTaskTimeoutMs > 0) {
+        const timeoutController = new AbortController()
+        taskSignal = optSignal
+          ? AbortSignal.any([optSignal, timeoutController.signal])
+          : timeoutController.signal
+        timeoutPromise = new Promise<never>((_, reject) => {
+          timeoutTimer = setTimeout(() => {
+            const error = new WorkerTaskError(
+              WorkerErrorCode.TASK_TIMEOUT,
+              `Worker task timed out after ${this.#config.workerTaskTimeoutMs}ms`,
+              { timeoutMs: this.#config.workerTaskTimeoutMs },
+            )
+            reject(error)
+            timeoutController.abort(error)
+          }, this.#config.workerTaskTimeoutMs)
+          timeoutTimer.unref()
+        })
+      }
+
+      // 开始调用
+      const invocation: RunnerTaskInvocation<(typeof taskParams)['input']> = {
+        input: taskParams.input,
+        messagePort: workerMessagePort,
+      }
+      const taskPromise = this.#pool.run(invocation, {
+        name: targetName,
+        signal: taskSignal,
+        transferList: [...(transferList || []), workerMessagePort],
+      }) as Promise<RunnerTaskRunResult<TSubject>>
+
+      result = timeoutPromise
+        ? await Promise.race([taskPromise, timeoutPromise])
+        : await taskPromise
+    } catch (error) {
+      if (isWorkerTaskError(error)) {
+        result = {
+          ok: false,
+          error: error.serialize(),
+        }
+      } else if (error instanceof Error && error.name === 'AbortError') {
+        result = {
+          ok: false,
+          error: new WorkerTaskError(
+            WorkerErrorCode.TASK_ABORTED,
+            error.message,
+            undefined,
+          ).serialize(),
+        }
+      } else {
+        result = {
+          ok: false,
+          error: new WorkerTaskError(
+            WorkerErrorCode.UNKNOWN,
+            'Worker task failed unexpectedly',
+            undefined,
+            error,
+          ).serialize(),
+        }
+      }
+    } finally {
+      if (timeoutTimer) clearTimeout(timeoutTimer)
+      try {
+        workerMessagePort?.close()
+      } catch {
+        // 忽略已 transfer/detached 端口的 close 异常
+      }
+    }
+
+    logger[result.ok ? 'info' : 'error'](
+      { subject: taskParams.subject, ok: result.ok },
+      `Worker task ${result.ok ? 'completed' : 'failed'}`,
+    )
+    return result
+  }
+
+  async shutdown(): Promise<void> {
+    await this.#pool.close()
+    if (ExampleWorkRunner.#instance === this) ExampleWorkRunner.#instance = null
+  }
+}

package/templates/hono-server/apps/server/src/infra/work-runner/example/worker-entry.ts

@@ -0,0 +1,34 @@
+/** WORKER 打包入口 */
+import type { RunnerTaskInvocation, RunnerTaskResult } from '../types'
+import {
+  executeExampleTask as runExampleTask,
+  type ExampleRunnerTaskModel,
+} from '@/modules/example/work-task/tasks'
+import { isWorkerTaskBusinessError } from '../utils/business-error'
+
+export async function executeExampleTask({
+  input,
+  messagePort,
+}: RunnerTaskInvocation<ExampleRunnerTaskModel['input']>): Promise<
+  RunnerTaskResult<ExampleRunnerTaskModel['output'], ExampleRunnerTaskModel['errorCode']>
+> {
+  try {
+    const result = await runExampleTask(input, messagePort)
+    messagePort.postMessage({ type: 'result', data: result.data })
+    return result
+  } catch (error) {
+    if (!isWorkerTaskBusinessError(error)) throw error
+    const result = {
+      ok: false,
+      error: {
+        code: 'EXAMPLE_PROCESS_FAILED' as const,
+        message: error.message,
+        ...(error.details ? { details: error.details } : {}),
+      },
+    }
+    messagePort.postMessage({ type: 'error', error: result.error })
+    return result
+  } finally {
+    messagePort.close()
+  }
+}

package/templates/hono-server/apps/server/src/infra/work-runner/types.ts

@@ -0,0 +1,113 @@
+import type { ExampleRunnerTaskModel } from '@/modules/example/work-task/tasks'
+import type { MessagePort, Transferable } from 'node:worker_threads'
+import type { WorkerErrorCode, WorkSubject } from './constants'
+
+// export const WorkerInvocationType = Object.freeze({
+//   READY: 'READY',
+//   TASK: 'TASK',
+// } as const)
+// export type WorkerInvocationType = (typeof WorkerInvocationType)[keyof typeof WorkerInvocationType]
+
+// export const WorkerSignalType = Object.freeze({
+//   STARTED: 'started',
+// } as const)
+// export type WorkerSignalType = (typeof WorkerSignalType)[keyof typeof WorkerSignalType]
+
+export type DefineRunnerTaskModel<
+  TSubject extends WorkSubject,
+  TInput,
+  TOutput,
+  TTaskErrorCode extends string = string,
+> = {
+  subject: TSubject
+  input: TInput
+  output: TOutput
+  errorCode: TTaskErrorCode | WorkerErrorCode
+}
+
+export type AnyRunnerTaskModel = ExampleRunnerTaskModel
+
+export type GetRunnerTaskModel<TSubject extends WorkSubject> = Extract<
+  AnyRunnerTaskModel,
+  { subject: TSubject }
+>
+
+export type RunnerTaskParams<TSubject extends WorkSubject> = Pick<
+  GetRunnerTaskModel<TSubject>,
+  'input' | 'subject'
+>
+export type RunnerTaskInput<TSubject extends WorkSubject> = GetRunnerTaskModel<TSubject>['input']
+export type RunnerTaskOutput<TSubject extends WorkSubject> = GetRunnerTaskModel<TSubject>['output']
+export type RunnerTaskErrorCode<TSubject extends WorkSubject> =
+  GetRunnerTaskModel<TSubject>['errorCode']
+
+export type RunnerTaskInvocation<TInput> = {
+  input: TInput
+  messagePort: MessagePort
+}
+
+export type RunnerTaskJsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly RunnerTaskJsonValue[]
+  | { readonly [key: string]: RunnerTaskJsonValue }
+
+/** Worker 通信中的错误详情必须保持为可结构化克隆、可 JSON 序列化的普通数据。 */
+export type RunnerTaskErrorDetails = Readonly<Record<string, RunnerTaskJsonValue>>
+
+export type WorkerMessage =
+  | {
+      type: 'log'
+      level: 'debug' | 'info' | 'warn' | 'error'
+      message: string
+      data?: RunnerTaskErrorDetails
+    }
+  | {
+      type: 'progress'
+      value: number
+      message?: string
+    }
+  | {
+      type: 'result'
+      data: RunnerTaskJsonValue
+    }
+  | {
+      type: 'error'
+      error: RunnerTaskError
+    }
+
+export type RunnerTaskError<TCode extends string = string> = {
+  code: TCode
+  /** 仅供服务端诊断，不应直接作为 HTTP 响应文案。 */
+  message: string
+  details?: RunnerTaskErrorDetails
+  cause?: unknown
+}
+
+export type RunnerTaskResult<TData, TCode extends string = string> =
+  | { ok: true; data: TData }
+  | { ok: false; error: RunnerTaskError<TCode> }
+
+export type RunnerTaskRunResult<TSubject extends WorkSubject> = RunnerTaskResult<
+  RunnerTaskOutput<TSubject>,
+  RunnerTaskErrorCode<TSubject>
+>
+
+export type RunnerTaskRunOptions = {
+  signal?: AbortSignal
+  transferList?: Transferable[]
+}
+
+export interface AppWorkRunner {
+  run<TSubject extends WorkSubject>(
+    task: RunnerTaskParams<TSubject>,
+    options?: RunnerTaskRunOptions,
+  ): Promise<RunnerTaskRunResult<TSubject>>
+  shutdown(): Promise<void>
+}
+
+// 已识别的公共 Worker 错误 Code 由具体任务与业务错误 Code 组合：
+// 队列满、任务超时、Worker 暂不可用等返回失败 DTO；
+// 未识别的 Piscina 异常和程序缺陷仍保持 Promise rejection，不能在此兜底吞掉。

package/templates/hono-server/apps/server/src/infra/work-runner/utils/business-error.ts

@@ -0,0 +1,19 @@
+import { hasProp } from '@/shared/utils'
+import type { RunnerTaskErrorDetails } from '../types'
+
+export class WorkerTaskBusinessError extends Error {
+  readonly details?: RunnerTaskErrorDetails
+
+  constructor(message: string, details?: RunnerTaskErrorDetails, cause?: unknown) {
+    super(message, { cause })
+    this.name = 'WorkerTaskBusinessError'
+    this.details = details
+  }
+}
+
+export function isWorkerTaskBusinessError(error: unknown): error is WorkerTaskBusinessError {
+  return (
+    error instanceof WorkerTaskBusinessError ||
+    (error instanceof Error && hasProp(error, 'name') && error.name === 'WorkerTaskBusinessError')
+  )
+}

package/templates/hono-server/apps/server/src/infra/work-runner/utils/message.ts

@@ -0,0 +1,46 @@
+import type { AppLogger } from '@/shared/app/types'
+import type { RunnerTaskErrorDetails, WorkerMessage } from '../types'
+import type { MessagePort } from 'node:worker_threads'
+import type { WorkSubject } from '../constants'
+
+export function workerLog(
+  messagePort: MessagePort,
+  level: Extract<WorkerMessage, { type: 'log' }>['level'],
+  message: string,
+  data?: RunnerTaskErrorDetails,
+): void {
+  messagePort.postMessage({ type: 'log', level, message, data } satisfies WorkerMessage)
+}
+
+export function workerProgress(messagePort: MessagePort, value: number, message?: string): void {
+  messagePort.postMessage({ type: 'progress', value, message } satisfies WorkerMessage)
+}
+
+export function handleWorkerMessage(
+  message: WorkerMessage,
+  logger: AppLogger,
+  context: {
+    subject: WorkSubject
+  },
+): void {
+  switch (message.type) {
+    case 'log':
+      logger[message.level]({ subject: context.subject, worker: message.data }, message.message)
+      break
+    case 'progress':
+      logger.debug(
+        { subject: context.subject, progress: message.value },
+        message.message || 'Worker progress',
+      )
+      break
+    case 'result':
+      logger.debug({ subject: context.subject }, 'Worker result delivered')
+      break
+    case 'error':
+      logger.warn(
+        { subject: context.subject, workerError: message.error },
+        'Worker error delivered',
+      )
+      break
+  }
+}

package/templates/hono-server/apps/server/src/infra/work-runner/utils/transfer.ts

@@ -0,0 +1,144 @@
+import { isMarkedAsUntransferable } from 'node:worker_threads'
+
+export interface TransferableResult<T> {
+  value: T
+  transferable?: ArrayBuffer
+}
+
+/**
+ * 排除不需要遍历其属性的原生系统对象（交由 V8 结构化克隆内部处理）
+ */
+function isCloneableLeaf(value: unknown): boolean {
+  return (
+    value instanceof Date ||
+    value instanceof RegExp ||
+    value instanceof Error ||
+    (typeof URL !== 'undefined' && value instanceof URL)
+  )
+}
+
+/**
+ * 转换 ArrayBufferView
+ */
+export function toTransferable<T extends ArrayBufferView>(view: T): TransferableResult<T> {
+  const buffer = view.buffer
+
+  // 1. SharedArrayBuffer 或已显式标记为不可转移的 Buffer，原样返回（由系统克隆）
+  if (!(buffer instanceof ArrayBuffer) || isMarkedAsUntransferable(buffer)) {
+    return { value: view }
+  }
+
+  // 2. 独占且干净的 Buffer：直接转移，零拷贝
+  if (view.byteOffset === 0 && view.byteLength === buffer.byteLength) {
+    return { value: view, transferable: buffer }
+  }
+
+  // 3. 处于切片/池化状态：切片降级，提取独立 ArrayBuffer
+  const newBuffer = buffer.slice(view.byteOffset, view.byteOffset + view.byteLength)
+
+  // 4. 重新包装 View，修复 Node.js Buffer 的构造函数废弃警告
+  let newView: T
+  if (typeof Buffer !== 'undefined' && Buffer.isBuffer(view)) {
+    newView = Buffer.from(newBuffer) as unknown as T
+  } else {
+    const Ctor = view.constructor as new (buf: ArrayBuffer) => T
+    newView = new Ctor(newBuffer)
+  }
+
+  return {
+    value: newView,
+    transferable: newBuffer,
+  }
+}
+
+/**
+ * 【主入口】：深层提取 Transferables
+ */
+export function extractTransferables(input: any): {
+  input: any
+  transferList: ArrayBuffer[]
+} {
+  const transferables = new Set<ArrayBuffer>()
+  const extracted = new WeakMap<object, unknown>()
+
+  function extract(value: any): any {
+    if (!value || typeof value !== 'object') return value
+
+    // 命中缓存（环状引用 / 重复对象）
+    const cached = extracted.get(value)
+    if (cached !== undefined) return cached
+
+    // 裸 ArrayBuffer
+    if (value instanceof ArrayBuffer) {
+      if (!isMarkedAsUntransferable(value)) {
+        transferables.add(value)
+      }
+      extracted.set(value, value)
+      return value
+    }
+
+    // ArrayBufferView (Buffer, TypedArray, DataView)
+    if (ArrayBuffer.isView(value)) {
+      const { value: transferableView, transferable } = toTransferable(value)
+      if (transferable) {
+        transferables.add(transferable)
+      }
+      extracted.set(value, transferableView)
+      return transferableView
+    }
+
+    // 遇到原生特殊对象，直接跳过深入遍历
+    if (isCloneableLeaf(value)) {
+      extracted.set(value, value)
+      return value
+    }
+
+    // 场景 4：普通数组
+    if (Array.isArray(value)) {
+      const array: unknown[] = []
+      extracted.set(value, array)
+      for (let i = 0; i < value.length; i++) {
+        array.push(extract(value[i]))
+      }
+      return array
+    }
+
+    // 场景 5：Map 和 Set
+    if (value instanceof Map) {
+      const map = new Map()
+      extracted.set(value, map)
+      for (const [k, v] of value) {
+        map.set(extract(k), extract(v))
+      }
+      return map
+    }
+    if (value instanceof Set) {
+      const set = new Set()
+      extracted.set(value, set)
+      for (const v of value) {
+        set.add(extract(v))
+      }
+      return set
+    }
+
+    // 场景 6：普通对象 & 自定义类实例（支持 Symbol 键）
+    const proto = Object.getPrototypeOf(value)
+    if (proto === null || proto === Object.prototype || (proto && proto.constructor !== Object)) {
+      const object: Record<string | symbol, unknown> = {}
+      extracted.set(value, object)
+
+      const keys = Reflect.ownKeys(value)
+      for (const key of keys) {
+        object[key] = extract(value[key as keyof typeof value])
+      }
+      return object
+    }
+
+    return value
+  }
+
+  return {
+    input: extract(input),
+    transferList: [...transferables],
+  }
+}

package/templates/hono-server/apps/server/src/middlewares/cors.ts

@@ -0,0 +1,26 @@
+import type { AppEnv } from '@/shared/app/types'
+import { cors } from 'hono/cors'
+import { createMiddleware } from 'hono/factory'
+
+export const corsMiddleware = () => {
+  return createMiddleware<AppEnv>(async (c, next) => {
+    const corsConfig = c.get('appConfig')
+    const domains = corsConfig.middleware.cors.domains
+    const middleware = cors({
+      origin: (origin) => {
+        const isAllowedDomain = domains.some((domain) => {
+          try {
+            return domain === '*' || new URL(origin).host === domain
+          } catch {
+            return false
+          }
+        })
+        return isAllowedDomain ? origin : null
+      },
+      allowHeaders: ['Content-Type'],
+      allowMethods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+      credentials: true,
+    })
+    return middleware(c, next)
+  })
+}

package/templates/hono-server/apps/server/src/modules/example/contracts.ts

@@ -0,0 +1,5 @@
+import * as v from 'valibot'
+
+export const processExampleInputSchema = v.object({
+  message: v.pipe(v.string(), v.minLength(1)),
+})

package/templates/hono-server/apps/server/src/modules/example/routes.ts

@@ -0,0 +1,46 @@
+import { Hono } from 'hono'
+import { describeRoute } from 'hono-openapi'
+import * as v from 'valibot'
+import type { AppEnv } from '@/shared/app/types'
+import { WorkSubject } from '@/infra/work-runner/constants'
+import { E } from '@/shared/errors/defs'
+import { jsonResponse, OpenApiTags } from '@/shared/network/openapi'
+import { successJson } from '@/shared/network/utils'
+import { generalValidator } from '@/shared/network/validator'
+import { processExampleInputSchema } from './contracts'
+
+export const exampleRoutes = new Hono<AppEnv>()
+  .get(
+    '/health',
+    describeRoute({
+      operationId: 'getHealth',
+      tags: [OpenApiTags.System],
+      summary: 'Health check',
+      responses: { 200: jsonResponse(v.object({ data: v.object({ status: v.string() }) })) },
+    }),
+    (c) => successJson(c, { status: 'ok' }),
+  )
+  .post(
+    '/examples/process',
+    describeRoute({
+      operationId: 'processExample',
+      tags: [OpenApiTags.Example],
+      summary: 'Process an example message in the worker pool',
+      responses: { 200: jsonResponse(v.object({ data: v.object({ normalized: v.string() }) })) },
+    }),
+    generalValidator('json', processExampleInputSchema),
+    async (c) => {
+      const input = c.req.valid('json')
+      const result = await c.get('exampleWorkRunner').run({
+        subject: WorkSubject.PROCESS_EXAMPLE,
+        input,
+      })
+      if (!result.ok) {
+        throw E.NORMAL.INTERNAL.create({
+          cause: result.error,
+          extensions: { workerCode: result.error.code },
+        })
+      }
+      return successJson(c, result.data)
+    },
+  )

package/templates/hono-server/apps/server/src/modules/example/work-task/tasks.test.ts

@@ -0,0 +1,37 @@
+import { MessageChannel } from 'node:worker_threads'
+import { describe, expect, it } from 'vite-plus/test'
+import { executeExampleTask } from './tasks'
+
+describe('Example worker task', () => {
+  it('normalizes a message and reports progress', async () => {
+    const { port1, port2 } = new MessageChannel()
+    const messages: unknown[] = []
+    port1.on('message', (message) => messages.push(message))
+    const result = await executeExampleTask({ message: '  hello   worker  ' }, port2)
+    await new Promise<void>((resolve) => setImmediate(resolve))
+
+    expect(result).toEqual({
+      ok: true,
+      data: { original: '  hello   worker  ', normalized: 'hello worker', length: 12 },
+    })
+    expect(messages).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ type: 'log' }),
+        expect.objectContaining({ type: 'progress', value: 100 }),
+      ]),
+    )
+    port1.close()
+    port2.close()
+  })
+
+  it('preserves a business exception model', async () => {
+    const { port1, port2 } = new MessageChannel()
+    await expect(executeExampleTask({ message: '  ' }, port2)).rejects.toMatchObject({
+      name: 'WorkerTaskBusinessError',
+      message: 'Message must not be empty',
+      details: { field: 'message' },
+    })
+    port1.close()
+    port2.close()
+  })
+})