@oyolincc/create 0.2.1 → 0.3.0

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

@@ -0,0 +1,118 @@
+import type { ExampleRunnerTaskModel } from '@/modules/example/work-task/tasks'
+import type { 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: WorkerMessagePort
+}
+
+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 interface WorkerMessagePort {
+  postMessage(message: WorkerMessage): void
+  close(): void
+}
+
+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,49 @@
+import type { AppLogger } from '@/shared/app/types'
+import type { RunnerTaskErrorDetails, WorkerMessage, WorkerMessagePort } from '../types'
+import type { WorkSubject } from '../constants'
+
+export function workerLog(
+  messagePort: WorkerMessagePort,
+  level: Extract<WorkerMessage, { type: 'log' }>['level'],
+  message: string,
+  data?: RunnerTaskErrorDetails,
+): void {
+  messagePort.postMessage({ type: 'log', level, message, data } satisfies WorkerMessage)
+}
+
+export function workerProgress(
+  messagePort: WorkerMessagePort,
+  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,9 @@
+import * as v from 'valibot'
+
+export const processExampleInputSchema = v.object({
+  message: v.pipe(v.string(), v.minLength(1)),
+})
+
+export const createExampleInputSchema = v.object({
+  message: v.pipe(v.string(), v.trim(), v.minLength(1), v.maxLength(500)),
+})

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

@@ -0,0 +1,73 @@
+import { type Context, Hono } from 'hono'
+import { describeRoute } from 'hono-openapi'
+import * as v from 'valibot'
+import { examples, vcExamples, type SqliteDBType } from '@repo/db/sqlite/schema'
+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 { createExampleInputSchema, processExampleInputSchema } from './contracts'
+
+const getDb = (context: Context<AppEnv>) => context.get('db') as SqliteDBType
+
+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' }),
+  )
+  .get(
+    '/examples',
+    describeRoute({
+      operationId: 'listExamples',
+      tags: [OpenApiTags.Example],
+      summary: 'List example rows',
+      responses: { 200: { description: 'Example rows' } },
+    }),
+    async (c) => successJson(c, await getDb(c).select(vcExamples.default).from(examples)),
+  )
+  .post(
+    '/examples',
+    describeRoute({
+      operationId: 'createExample',
+      tags: [OpenApiTags.Example],
+      summary: 'Create an example row',
+      responses: { 200: { description: 'Created example row' } },
+    }),
+    generalValidator('json', createExampleInputSchema),
+    async (c) => {
+      const input = c.req.valid('json')
+      const [row] = await getDb(c).insert(examples).values(input).returning(vcExamples.default)
+      return successJson(c, row)
+    },
+  )
+  .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 result = await c.get('workRunner').run({
+        subject: WorkSubject.PROCESS_EXAMPLE,
+        input: c.req.valid('json'),
+      })
+      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,49 @@
+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 }),
+        expect.objectContaining({ type: 'result' }),
+      ]),
+    )
+    port1.close()
+    port2.close()
+  })
+
+  it('serializes a business exception and reports it', async () => {
+    const { port1, port2 } = new MessageChannel()
+    const messages: unknown[] = []
+    port1.on('message', (message) => messages.push(message))
+    const result = await executeExampleTask({ message: '  ' }, port2)
+    await new Promise<void>((resolve) => setImmediate(resolve))
+
+    expect(result).toEqual({
+      ok: false,
+      error: {
+        code: 'EXAMPLE_PROCESS_FAILED',
+        message: 'Message must not be empty',
+        details: { field: 'message' },
+      },
+    })
+    expect(messages).toEqual(
+      expect.arrayContaining([expect.objectContaining({ type: 'error' })]),
+    )
+    port1.close()
+    port2.close()
+  })
+})

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

@@ -0,0 +1,58 @@
+import type { ProcessExampleInput, ProcessExampleOutput } from '@repo/definition/backend'
+import { type WorkSubject } from '@/infra/work-runner/constants'
+import type {
+  DefineRunnerTaskModel,
+  RunnerTaskResult,
+  WorkerMessagePort,
+} from '@/infra/work-runner/types'
+import {
+  isWorkerTaskBusinessError,
+  WorkerTaskBusinessError,
+} from '@/infra/work-runner/utils/business-error'
+import { workerLog, workerProgress } from '@/infra/work-runner/utils/message'
+
+export type ExampleTaskErrorCode = 'EXAMPLE_PROCESS_FAILED'
+
+export type ExampleRunnerTaskModel = DefineRunnerTaskModel<
+  typeof WorkSubject.PROCESS_EXAMPLE,
+  ProcessExampleInput,
+  ProcessExampleOutput,
+  ExampleTaskErrorCode
+>
+
+export async function executeExampleTask(
+  input: ExampleRunnerTaskModel['input'],
+  messagePort: WorkerMessagePort,
+): Promise<RunnerTaskResult<ProcessExampleOutput, ExampleTaskErrorCode>> {
+  try {
+    workerLog(messagePort, 'debug', 'Example task started')
+    workerProgress(messagePort, 0, 'Validating input')
+
+    const original = input.message
+    const normalized = original.trim().replace(/\s+/g, ' ')
+    if (!normalized) {
+      throw new WorkerTaskBusinessError('Message must not be empty', { field: 'message' })
+    }
+
+    workerProgress(messagePort, 100, 'Example task completed')
+    const result = {
+      ok: true,
+      data: { original, normalized, length: normalized.length },
+    } as const
+    messagePort.postMessage({ type: 'result', data: result.data })
+    return result
+  } catch (error) {
+    if (!isWorkerTaskBusinessError(error)) throw error
+
+    const result: RunnerTaskResult<ProcessExampleOutput, ExampleTaskErrorCode> = {
+      ok: false,
+      error: {
+        code: 'EXAMPLE_PROCESS_FAILED',
+        message: error.message,
+        ...(error.details ? { details: error.details } : {}),
+      },
+    }
+    messagePort.postMessage({ type: 'error', error: result.error })
+    return result
+  }
+}

package/templates/hono-server/apps/server/src/shared/app/types.ts

@@ -0,0 +1,44 @@
+import type {
+  CORSConfig,
+  LogBaseConfig,
+  LogPrettyRawConfig,
+  LogRollRawConfig,
+  LogRollSchemaConfig,
+  RuntimeConfig,
+  WorkerConfig,
+} from '@repo/definition/backend'
+import type { AppWorkRunner } from '@/infra/work-runner/types'
+import type { MiddlewareHandler, Context } from 'hono'
+import type { PinoLogger as HonoPinoLogger } from 'hono-pino'
+import type { RequestIdVariables } from 'hono/request-id'
+
+export type AppLogger = HonoPinoLogger
+
+export type LogConfig = {
+  base: LogBaseConfig
+  roll?: LogRollSchemaConfig & LogRollRawConfig
+  pretty?: LogPrettyRawConfig
+}
+
+export type AppConfig = {
+  runtime: RuntimeConfig & { isLocal: boolean }
+  log: LogConfig
+  worker: WorkerConfig
+  middleware: { cors: CORSConfig }
+}
+
+export type AppDependencies = {
+  appConfig: AppConfig
+  loggerHandler: MiddlewareHandler<{ Variables: { logger: AppLogger } }>
+  workRunner: AppWorkRunner
+  db: unknown
+}
+
+export type AppEnv = {
+  Variables: RequestIdVariables & AppDependencies & { logger?: AppLogger }
+}
+
+export type CreateAppOptions = {
+  serverBasePath: string
+  makeDependencies: (c: Context<AppEnv>) => Promise<AppDependencies> | AppDependencies
+}