@oyolincc/create 0.2.1 → 0.3.0

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

@@ -0,0 +1,43 @@
+import { Hono } from 'hono'
+import { contextStorage } from 'hono/context-storage'
+import { csrf } from 'hono/csrf'
+import { secureHeaders } from 'hono/secure-headers'
+import { requestId } from 'hono/request-id'
+import { corsMiddleware } from './middlewares/cors'
+import { exampleRoutes } from './modules/example/routes'
+import type { CreateAppOptions, AppEnv } from './shared/app/types'
+import { E } from './shared/errors/defs'
+import { globalErrorHandler } from './shared/errors/handler'
+import { configureOpenAPI } from './shared/network/openapi'
+import { objectEntries } from './shared/utils'
+
+export const createApp = ({ serverBasePath, makeDependencies }: CreateAppOptions): Hono<AppEnv> => {
+  const app = new Hono<AppEnv>().basePath(serverBasePath)
+
+  app.use('*', async (c, next) => {
+    const deps = await makeDependencies(c)
+    objectEntries(deps).forEach(([key, value]) => c.set(key, value))
+    await next()
+  })
+  app.use(contextStorage())
+  app.use('*', requestId())
+  app.use('*', async (c, next) => {
+    const loggerHandler = c.get('loggerHandler')
+    await loggerHandler(c as never, async () => {
+      c.get('logger')?.assign({ reqId: c.get('requestId') })
+      await next()
+    })
+  })
+  app.use('*', secureHeaders())
+  app.use('*', corsMiddleware())
+  app.use('*', csrf())
+
+  app.route('/', exampleRoutes)
+  configureOpenAPI(app)
+
+  app.notFound(() => {
+    throw E.NORMAL.NOT_FOUND.create()
+  })
+  app.onError(globalErrorHandler)
+  return app
+}

package/templates/hono-server/apps/server/src/config.ts

@@ -0,0 +1,47 @@
+import {
+  corsConfig,
+  logBaseConfig,
+  logPrettyRawConfig,
+  logRollRawConfig,
+  logRollSchemaConfig,
+  runtimeConfig,
+  workerConfig,
+} from '@repo/definition/backend'
+import { getRuntimeKey } from 'hono/adapter'
+import { flatten as flattenValiIssues, isValiError } from 'valibot'
+import type { AppConfig } from '@/shared/app/types'
+
+export function resolveConfig(context: Record<string, unknown>): AppConfig {
+  try {
+    const fromEnv = { context, matchContextKey: 'constantCase' as const }
+    const runtime = runtimeConfig.resolve(fromEnv)
+    const runtimeKey = getRuntimeKey()
+    const isNodejsLike = runtimeKey === 'node' || runtimeKey === 'bun'
+    const log: AppConfig['log'] = { base: logBaseConfig.resolve(fromEnv) }
+
+    if (isNodejsLike) {
+      log.roll = {
+        ...logRollSchemaConfig.resolve(fromEnv),
+        ...logRollRawConfig.resolve(),
+      }
+      log.pretty = logPrettyRawConfig.resolve()
+    }
+
+    return {
+      runtime: { ...runtime, isLocal: runtime.serverEnv === 'local' },
+      log,
+      worker: workerConfig.resolve(fromEnv),
+      middleware: {
+        cors: corsConfig.resolve({
+          context: { domains: context.CORS_DOMAINS },
+          matchContextKey: 'camel',
+        }),
+      },
+    }
+  } catch (error) {
+    if (isValiError(error)) {
+      throw new Error(`[resolveConfig] ${JSON.stringify(flattenValiIssues(error.issues))}`)
+    }
+    throw error
+  }
+}

package/templates/hono-server/apps/server/src/infra/logger/getter.ts

@@ -0,0 +1,74 @@
+import type { AppEnv, AppLogger } from '@/shared/app/types'
+import { hasProp } from '@/shared/utils'
+import { getContext } from 'hono/context-storage'
+
+// 1. 创建无限递归的空代理，用于抹平高级日志库独有的非核心属性/方法（如 logger.bindings(), logger.flush()）
+const dummyFn = () => noopProxy
+const noopProxy: any = new Proxy(dummyFn, {
+  get: () => noopProxy,
+  apply: () => noopProxy,
+})
+
+// 2. 自定义日志级别到 Console 方法的映射
+const mapToConsoleMethod: Record<string, string> = {
+  trace: 'trace',
+  debug: 'debug',
+  info: 'info',
+  warn: 'warn',
+  error: 'error',
+  fatal: 'error', // Console 没有 fatal，将其降级映射为 error
+  silent: 'debug', // 理论上不该输出，但做个兜底防崩溃
+}
+
+export const fallbackLogger = new Proxy(console, {
+  get(target, prop, receiver) {
+    if (prop === 'child') {
+      return () => fallbackLogger
+    }
+
+    if (typeof prop === 'string' && hasProp(mapToConsoleMethod, prop)) {
+      const consoleMethod = Reflect.get(target, mapToConsoleMethod[prop], receiver)
+      if (typeof consoleMethod === 'function') {
+        return consoleMethod.bind(target)
+      }
+    }
+
+    const value = Reflect.get(target, prop, receiver)
+    if (typeof value === 'function') {
+      return value.bind(target)
+    }
+
+    // 如果原生具有该属性（不为 undefined），则直接返回
+    if (value !== undefined) {
+      return value
+    }
+
+    // --- 核心改造点 D：未知的扩展属性/链式调用 ---
+    // 比如 logger.bindings().xxx()，返回无限安全代理，杜绝 Cannot read properties of xxx 报错
+    return noopProxy
+  },
+
+  // 拦截写入操作（如业务代码修改 logger.level = 'debug'）
+  set(_target, _prop, _value) {
+    // 静默吞掉修改操作，防止污染原生的 console 对象
+    return true
+  },
+}) as unknown as AppLogger
+
+let rootLogger: AppLogger | undefined
+
+export const setRootLogger = (logger: AppLogger) => {
+  rootLogger = logger
+}
+
+export const getLogger = (): AppLogger => {
+  try {
+    const contextLogger = getContext<AppEnv>().var.logger
+    if (contextLogger) {
+      return contextLogger
+    }
+  } catch {
+    // outside hono context-storage
+  }
+  return rootLogger || fallbackLogger
+}

package/templates/hono-server/apps/server/src/infra/logger/pino.ts

@@ -0,0 +1,126 @@
+import { createRequire } from 'node:module'
+import { isAbsolute, join, resolve } from 'node:path'
+import { type Runtime } from 'hono/adapter'
+import { pinoLogger } from 'hono-pino'
+import pino, { type LoggerOptions } from 'pino'
+import type { AppConfig } from '@/shared/app/types'
+import { serializeErr } from '@/shared/errors/log'
+
+// const pinoInstance = pino({
+//   hooks: {
+//     logMethod(args: any[], method) {
+//       if (
+//         args.length !== 2 ||
+//         args[0] instanceof Error ||
+//         typeof args[1] !== 'string'
+//       ) {
+//         return method.apply(this, args)
+//       }
+//       const firstArg = args[0]
+//       if (firstArg && typeof firstArg === 'object') {
+//         const { context, ...rest } = firstArg
+//         const arg1: any = { p: rest }
+//         if (context) arg1.context = context
+//         return method.apply(this, [{}, args[1]])
+//       }
+//       return method.apply(this, args)
+//     },
+//   },
+// })
+
+export const createPinoOptions = ({
+  isLocal,
+  baseConfig,
+}: {
+  isLocal: boolean
+  baseConfig: AppConfig['log']['base']
+}) => {
+  const pinoOptions: LoggerOptions = {
+    level: baseConfig.loggerLevel || (isLocal ? 'debug' : 'info'),
+    browser: {
+      asObject: true,
+      serialize: ['!stdSerializers.err', 'req', 'res', 'err'],
+    },
+    serializers: {
+      req: (req) => {
+        return {
+          method: req.method,
+          url: req.url,
+          headers: {
+            'content-type': req.headers?.['content-type'],
+            'user-agent': req.headers?.['user-agent'],
+            referer: req.headers?.['referer'],
+          },
+        }
+      },
+      res: (res) => {
+        return {
+          status: res.status,
+          headers: {
+            'content-type': res.headers?.['content-type'],
+            'content-length': res.headers?.['content-length'],
+          },
+        }
+      },
+      err: serializeErr,
+    },
+  }
+
+  return pinoOptions
+}
+
+export const createPinoLogger = ({
+  isLocal,
+  logBase,
+  runtime,
+  logRoll,
+  logPretty,
+}: {
+  isLocal: boolean
+  logBase: AppConfig['log']['base']
+  runtime: Runtime
+  logRoll?: AppConfig['log']['roll']
+  logPretty?: AppConfig['log']['pretty']
+}) => {
+  const pinoOptions = createPinoOptions({ isLocal, baseConfig: logBase })
+  const level = pinoOptions.level
+  if (runtime === 'node' || runtime === 'bun') {
+    if (isLocal && logPretty) {
+      try {
+        createRequire(import.meta.url).resolve('pino-pretty')
+        pinoOptions.transport = { target: 'pino-pretty', level, options: logPretty }
+      } catch {
+        console.warn('[logger] pino-pretty is not installed; falling back to JSON stdout')
+      }
+    } else if (logRoll) {
+      const { loggerDir, loggerFileBase } = logRoll
+      pinoOptions.transport = {
+        targets: [
+          {
+            target: 'pino-roll',
+            level,
+            options: {
+              ...logRoll,
+              file: join(
+                isAbsolute(loggerDir) ? loggerDir : resolve(process.cwd(), loggerDir),
+                loggerFileBase,
+              ),
+            },
+          },
+          { target: 'pino/file', level, options: { destination: 1 } },
+        ],
+      }
+    }
+  }
+  const rootLogger = pino(pinoOptions)
+  const loggerHandler = pinoLogger({
+    pino: rootLogger,
+    // access log 只记请求完成；错误细节由 onError 走 serializers.err。
+    // 默认在 c.error 时升 error 且 msg=error.message，会打出一条无结构的重复 error。
+    http: {
+      onResLevel: () => 'info',
+      onResMessage: () => 'Request completed',
+    },
+  })
+  return { rootLogger, loggerHandler }
+}

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

@@ -0,0 +1,23 @@
+// 所有工作任务标识
+export const WorkSubject = Object.freeze({
+  PROCESS_EXAMPLE: 'PROCESS_EXAMPLE',
+} as const)
+export type WorkSubject = (typeof WorkSubject)[keyof typeof WorkSubject]
+
+export const WorkerErrorCode = Object.freeze({
+  /** Worker 等待队列已满。 */
+  QUEUE_FULL: 'WORKER_QUEUE_FULL',
+  /** Worker 任务从提交到完成超过允许时限。 */
+  TASK_TIMEOUT: 'WORKER_TASK_TIMEOUT',
+  /** Worker 任务被取消。 */
+  TASK_ABORTED: 'WORKER_TASK_ABORTED',
+  /** Worker 任务内部错误。 */
+  TASK_INTERNAL: 'WORKER_TASK_INTERNAL',
+  /** Worker 未知错误。 */
+  UNKNOWN: 'UNKNOWN',
+  /** Worker 异常退出或 Pool 暂时没有可用 Worker。 */
+  WORKER_UNAVAILABLE: 'WORKER_UNAVAILABLE',
+  /** Worker Pool 已进入关闭流程，无法接受新任务。 */
+  WORKER_CLOSED: 'WORKER_CLOSED',
+} as const)
+export type WorkerErrorCode = (typeof WorkerErrorCode)[keyof typeof WorkerErrorCode]

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

@@ -0,0 +1,40 @@
+import { hasProp } from '@/shared/utils'
+import { WorkerErrorCode } from './constants'
+import type { RunnerTaskError, RunnerTaskErrorDetails } from './types'
+
+const workerErrorCodes = Object.values(WorkerErrorCode)
+
+export class WorkerTaskError extends Error {
+  readonly code: WorkerErrorCode
+  readonly details?: RunnerTaskErrorDetails
+
+  constructor(
+    code: WorkerErrorCode,
+    message: string,
+    details?: RunnerTaskErrorDetails,
+    cause?: unknown,
+  ) {
+    super(message, { cause })
+    this.name = 'WorkerTaskError'
+    this.code = code
+    this.details = details
+  }
+
+  serialize(): RunnerTaskError<WorkerErrorCode> {
+    return {
+      code: this.code,
+      message: this.message,
+      ...(this.details ? { details: this.details } : {}),
+      ...(this.cause ? { cause: this.cause } : {}),
+    }
+  }
+}
+
+export function isWorkerTaskError(error: unknown): error is WorkerTaskError {
+  return (
+    error instanceof WorkerTaskError ||
+    (error instanceof Error &&
+      hasProp(error, 'code') &&
+      workerErrorCodes.includes(error.code as WorkerErrorCode))
+  )
+}

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

@@ -0,0 +1,13 @@
+/** WORKER 打包入口 */
+import type { RunnerTaskInvocation } from '../types'
+import {
+  executeExampleTask as runExampleTask,
+  type ExampleRunnerTaskModel,
+} from '@/modules/example/work-task/tasks'
+
+export function executeExampleTask({
+  input,
+  messagePort,
+}: RunnerTaskInvocation<ExampleRunnerTaskModel['input']>): ReturnType<typeof runExampleTask> {
+  return runExampleTask(input, messagePort).finally(() => messagePort.close())
+}

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

@@ -0,0 +1,42 @@
+import { executeExampleTask } from '../example/worker-entry'
+import { getLogger } from '@/infra/logger/getter'
+import { WorkSubject } from '../constants'
+import type {
+  AppWorkRunner,
+  RunnerTaskParams,
+  RunnerTaskRunOptions,
+  RunnerTaskRunResult,
+  WorkerMessage,
+  WorkerMessagePort,
+} from '../types'
+import { handleWorkerMessage } from '../utils/message'
+
+function createMessagePort(subject: WorkSubject): WorkerMessagePort {
+  const logger = getLogger()
+  return {
+    postMessage(message: WorkerMessage) {
+      handleWorkerMessage(message, logger, { subject })
+    },
+    close() {},
+  }
+}
+
+export class PassThroughWorkRunner implements AppWorkRunner {
+  async run<TSubject extends WorkSubject>(
+    taskParams: RunnerTaskParams<TSubject>,
+    options?: RunnerTaskRunOptions,
+  ): Promise<RunnerTaskRunResult<TSubject>> {
+    if (taskParams.subject !== WorkSubject.PROCESS_EXAMPLE) {
+      throw new Error(`[PassThroughWorkRunner] task name not found: ${String(taskParams.subject)}`)
+    }
+
+    options?.signal?.throwIfAborted()
+
+    return executeExampleTask({
+      input: taskParams.input,
+      messagePort: createMessagePort(taskParams.subject),
+    }) as Promise<RunnerTaskRunResult<TSubject>>
+  }
+
+  async shutdown(): Promise<void> {}
+}

package/templates/hono-server/apps/server/src/infra/work-runner/piscina/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 '../example/worker-entry'
+import { handleWorkerMessage } from '../utils/message'
+
+const taskNameMap = {
+  [WorkSubject.PROCESS_EXAMPLE]: 'executeExampleTask',
+} satisfies Partial<Record<WorkSubject, keyof typeof ExampleWorker>>
+
+export class PiscinaWorkRunner implements AppWorkRunner {
+  static #instance: PiscinaWorkRunner | null = null
+  readonly #pool: Piscina
+  readonly #config: WorkerConfig
+
+  private constructor(config: WorkerConfig) {
+    if (!config) {
+      throw new Error('[PiscinaWorkRunner] 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): PiscinaWorkRunner {
+    if (!this.#instance) {
+      getLogger().info({ worker: config }, 'PiscinaWorkRunner initialized')
+      this.#instance = new PiscinaWorkRunner(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(`[PiscinaWorkRunner] 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 (PiscinaWorkRunner.#instance === this) PiscinaWorkRunner.#instance = null
+  }
+}