create-bubbles 0.1.23 → 0.1.24

package/template-vp-monorepo-react-hono/apps/server/src/config/env.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod'
+
+const redisUrlSchema = z
+  .string()
+  .url()
+  .refine((value) => value.startsWith('redis://') || value.startsWith('rediss://'), {
+    message: 'must use the redis:// or rediss:// protocol',
+  })
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
+  APP_NAME: z.string().min(1).default('bubbles-server'),
+  HOST: z.string().min(1).default('0.0.0.0'),
+  PORT: z.coerce.number().int().min(1).max(65_535).default(10_000),
+  CORS_ORIGINS: z
+    .string()
+    .default('http://localhost:9999')
+    .transform((value) =>
+      value
+        .split(',')
+        .map((origin) => origin.trim())
+        .filter(Boolean),
+    )
+    .refine((origins) => origins.length > 0, { message: 'must contain at least one origin' }),
+  DATABASE_URL: z.string().url().default('postgresql://postgres:ml@localhost:5432/postgres'),
+  DATABASE_POOL_MAX: z.coerce.number().int().min(1).max(100).default(10),
+  REDIS_URL: redisUrlSchema.default('redis://:ml@localhost:6379/0'),
+  REDIS_CONNECT_TIMEOUT_MS: z.coerce.number().int().min(100).default(5000),
+  JOB_QUEUE_NAME: z.string().min(1).default('jobs'),
+  JOB_QUEUE_PREFIX: z.string().min(1).default('bubbles'),
+  JOB_WORKER_CONCURRENCY: z.coerce.number().int().min(1).max(100).default(5),
+  SHUTDOWN_TIMEOUT_MS: z.coerce.number().int().min(1000).default(10_000),
+})
+
+export type AppEnv = z.infer<typeof envSchema>
+
+let cachedEnv: AppEnv | undefined
+
+export function getEnv(): AppEnv {
+  if (cachedEnv) return cachedEnv
+
+  const result = envSchema.safeParse(process.env)
+
+  if (!result.success) {
+    const details = result.error.issues
+      .map((issue) => (issue.path.join('.') || 'environment') + ': ' + issue.message)
+      .join('; ')
+
+    throw new Error('Invalid server environment: ' + details)
+  }
+
+  cachedEnv = result.data
+  return cachedEnv
+}

package/template-vp-monorepo-react-hono/apps/server/src/index.bun.ts

@@ -0,0 +1,60 @@
+import 'dotenv/config'
+import { createApp } from './app.js'
+import { appLogger } from './common/logger.js'
+import { getEnv } from './config/env.js'
+import { closeDatabase } from './infrastructure/database/client.js'
+import { closeRedis } from './infrastructure/redis/client.js'
+import { closeJobsQueue } from './modules/jobs/jobs.queue.js'
+import { closeAll, withShutdownTimeout } from './runtime/shutdown.js'
+
+async function bootstrap(): Promise<void> {
+  const env = getEnv()
+  const app = createApp()
+  const server = Bun.serve({
+    hostname: env.HOST,
+    port: env.PORT,
+    development: env.NODE_ENV !== 'production',
+    fetch: (request) => app.fetch(request),
+  })
+  let shuttingDown = false
+
+  appLogger.info('Bun HTTP server started', {
+    address: server.url.toString(),
+  })
+
+  const shutdown = async (reason: string, exitCode = 0): Promise<void> => {
+    if (shuttingDown) return
+    shuttingDown = true
+    process.exitCode = exitCode
+    appLogger.info('Stopping Bun HTTP process', { reason })
+
+    await withShutdownTimeout('http-bun', async () => {
+      await closeAll([
+        async () => {
+          await server.stop(false)
+        },
+      ])
+      await closeAll([closeJobsQueue, closeRedis, closeDatabase])
+    })
+  }
+
+  process.once('SIGINT', () => void shutdown('SIGINT'))
+  process.once('SIGTERM', () => void shutdown('SIGTERM'))
+  process.once('uncaughtException', (error) => {
+    appLogger.error('Uncaught Bun exception', { error: error.message, stack: error.stack })
+    void shutdown('uncaughtException', 1)
+  })
+  process.once('unhandledRejection', (reason) => {
+    appLogger.error('Unhandled Bun rejection', {
+      error: reason instanceof Error ? reason.message : String(reason),
+    })
+    void shutdown('unhandledRejection', 1)
+  })
+}
+
+void bootstrap().catch((error: unknown) => {
+  appLogger.error('Bun HTTP process failed to start', {
+    error: error instanceof Error ? error.message : String(error),
+  })
+  process.exitCode = 1
+})

package/template-vp-monorepo-react-hono/apps/server/src/index.ts

@@ -0,0 +1,73 @@
+import 'dotenv/config'
+import { serve } from '@hono/node-server'
+import type { ServerType } from '@hono/node-server'
+import { createApp } from './app.js'
+import { appLogger } from './common/logger.js'
+import { getEnv } from './config/env.js'
+import { closeDatabase } from './infrastructure/database/client.js'
+import { closeRedis } from './infrastructure/redis/client.js'
+import { closeJobsQueue } from './modules/jobs/jobs.queue.js'
+import { closeAll, withShutdownTimeout } from './runtime/shutdown.js'
+
+function closeServer(server: ServerType): Promise<void> {
+  return new Promise((resolve, reject) => {
+    server.close((error) => {
+      if (error) {
+        reject(error)
+        return
+      }
+
+      resolve()
+    })
+  })
+}
+
+async function bootstrap(): Promise<void> {
+  const env = getEnv()
+  const app = createApp()
+  const server = serve(
+    {
+      fetch: app.fetch,
+      hostname: env.HOST,
+      port: env.PORT,
+    },
+    (info) => {
+      appLogger.info('HTTP server started', {
+        address: 'http://' + info.address + ':' + info.port,
+      })
+    },
+  )
+  let shuttingDown = false
+
+  const shutdown = async (reason: string, exitCode = 0): Promise<void> => {
+    if (shuttingDown) return
+    shuttingDown = true
+    process.exitCode = exitCode
+    appLogger.info('Stopping HTTP process', { reason })
+
+    await withShutdownTimeout('http', async () => {
+      await closeAll([() => closeServer(server)])
+      await closeAll([closeJobsQueue, closeRedis, closeDatabase])
+    })
+  }
+
+  process.once('SIGINT', () => void shutdown('SIGINT'))
+  process.once('SIGTERM', () => void shutdown('SIGTERM'))
+  process.once('uncaughtException', (error) => {
+    appLogger.error('Uncaught exception', { error: error.message, stack: error.stack })
+    void shutdown('uncaughtException', 1)
+  })
+  process.once('unhandledRejection', (reason) => {
+    appLogger.error('Unhandled rejection', {
+      error: reason instanceof Error ? reason.message : String(reason),
+    })
+    void shutdown('unhandledRejection', 1)
+  })
+}
+
+void bootstrap().catch((error: unknown) => {
+  appLogger.error('HTTP process failed to start', {
+    error: error instanceof Error ? error.message : String(error),
+  })
+  process.exitCode = 1
+})

package/template-vp-monorepo-react-hono/apps/server/src/infrastructure/database/client.ts

@@ -0,0 +1,46 @@
+import { drizzle, type NodePgDatabase } from 'drizzle-orm/node-postgres'
+import { Pool } from 'pg'
+import { getEnv } from '../../config/env.js'
+import { appLogger } from '../../common/logger.js'
+import * as schema from './schema/index.js'
+
+export type Database = NodePgDatabase<typeof schema>
+
+let pool: Pool | undefined
+let database: Database | undefined
+
+function getPool(): Pool {
+  if (pool) return pool
+
+  const env = getEnv()
+  pool = new Pool({
+    connectionString: env.DATABASE_URL,
+    max: env.DATABASE_POOL_MAX,
+  })
+  pool.on('error', (error) => {
+    appLogger.error('Unexpected PostgreSQL pool error', { error: error.message })
+  })
+
+  return pool
+}
+
+export function getDatabase(): Database {
+  if (!database) {
+    database = drizzle(getPool(), { schema })
+  }
+
+  return database
+}
+
+export async function checkDatabase(): Promise<void> {
+  await getPool().query('select 1')
+}
+
+export async function closeDatabase(): Promise<void> {
+  if (!pool) return
+
+  const currentPool = pool
+  pool = undefined
+  database = undefined
+  await currentPool.end()
+}

package/template-vp-monorepo-react-hono/apps/server/src/infrastructure/database/schema/index.ts

@@ -0,0 +1 @@
+export * from './job-runs.js'

package/template-vp-monorepo-react-hono/apps/server/src/infrastructure/database/schema/job-runs.ts

@@ -0,0 +1,42 @@
+import {
+  index,
+  integer,
+  jsonb,
+  pgEnum,
+  pgTable,
+  text,
+  timestamp,
+  uuid,
+  varchar,
+} from 'drizzle-orm/pg-core'
+
+export const jobRunStatus = pgEnum('job_run_status', [
+  'queued',
+  'processing',
+  'completed',
+  'failed',
+])
+
+export const jobRuns = pgTable(
+  'job_runs',
+  {
+    id: uuid('id').defaultRandom().primaryKey(),
+    queueName: varchar('queue_name', { length: 100 }).notNull(),
+    jobName: varchar('job_name', { length: 100 }).notNull(),
+    status: jobRunStatus('status').default('queued').notNull(),
+    payload: jsonb('payload').$type<Record<string, unknown>>().notNull(),
+    result: jsonb('result').$type<Record<string, unknown>>(),
+    attempts: integer('attempts').default(0).notNull(),
+    error: text('error'),
+    createdAt: timestamp('created_at', { withTimezone: true }).defaultNow().notNull(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).defaultNow().notNull(),
+    startedAt: timestamp('started_at', { withTimezone: true }),
+    finishedAt: timestamp('finished_at', { withTimezone: true }),
+  },
+  (table) => [
+    index('job_runs_status_created_at_idx').on(table.status, table.createdAt),
+    index('job_runs_queue_name_idx').on(table.queueName),
+  ],
+)
+
+export type JobRun = typeof jobRuns.$inferSelect

package/template-vp-monorepo-react-hono/apps/server/src/infrastructure/queue/connection.ts

@@ -0,0 +1,6 @@
+import type { ConnectionOptions } from 'bullmq'
+import { createRedisOptions } from '../redis/options.js'
+
+export function createQueueConnection(role: 'queue' | 'worker'): ConnectionOptions {
+  return createRedisOptions(role)
+}

package/template-vp-monorepo-react-hono/apps/server/src/infrastructure/redis/client.ts

@@ -0,0 +1,39 @@
+import { Redis } from 'ioredis'
+import { appLogger } from '../../common/logger.js'
+import { createRedisOptions } from './options.js'
+
+let redis: Redis | undefined
+
+export function getRedis(): Redis {
+  if (redis) return redis
+
+  redis = new Redis(createRedisOptions('cache'))
+  redis.on('error', (error: Error) => {
+    appLogger.error('Redis connection error', { error: error.message })
+  })
+
+  return redis
+}
+
+export async function checkRedis(): Promise<void> {
+  const client = getRedis()
+
+  if (client.status === 'wait') {
+    await client.connect()
+  }
+
+  await client.ping()
+}
+
+export async function closeRedis(): Promise<void> {
+  if (!redis) return
+
+  const client = redis
+  redis = undefined
+
+  try {
+    await client.quit()
+  } catch {
+    client.disconnect()
+  }
+}

package/template-vp-monorepo-react-hono/apps/server/src/infrastructure/redis/options.ts

@@ -0,0 +1,28 @@
+import type { RedisOptions } from 'ioredis'
+import { getEnv } from '../../config/env.js'
+
+export type RedisRole = 'cache' | 'queue' | 'worker'
+
+export function createRedisOptions(role: RedisRole): RedisOptions {
+  const env = getEnv()
+  const redisUrl = new URL(env.REDIS_URL)
+  const databasePath = redisUrl.pathname.slice(1)
+  const database = databasePath ? Number.parseInt(databasePath, 10) : 0
+
+  if (Number.isNaN(database)) {
+    throw new Error('REDIS_URL contains an invalid database number')
+  }
+
+  return {
+    host: redisUrl.hostname,
+    port: Number.parseInt(redisUrl.port || '6379', 10),
+    username: redisUrl.username ? decodeURIComponent(redisUrl.username) : undefined,
+    password: redisUrl.password ? decodeURIComponent(redisUrl.password) : undefined,
+    db: database,
+    tls: redisUrl.protocol === 'rediss:' ? {} : undefined,
+    connectTimeout: env.REDIS_CONNECT_TIMEOUT_MS,
+    connectionName: env.APP_NAME + ':' + role,
+    lazyConnect: role === 'cache',
+    maxRetriesPerRequest: role === 'worker' ? null : 1,
+  }
+}

package/template-vp-monorepo-react-hono/apps/server/src/modules/health/health.routes.ts

@@ -0,0 +1,17 @@
+import { Hono } from 'hono'
+import { apiFailure, apiSuccess } from '../../common/http/response.js'
+import { getLiveness, getReadiness } from './health.service.js'
+
+export const healthRoutes = new Hono()
+
+healthRoutes.get('/live', (context) => context.json(apiSuccess(getLiveness())))
+
+healthRoutes.get('/ready', async (context) => {
+  const readiness = await getReadiness()
+
+  if (readiness.status === 'ok') {
+    return context.json(apiSuccess(readiness))
+  }
+
+  return context.json(apiFailure(503, '服务尚未就绪', readiness), 503)
+})

package/template-vp-monorepo-react-hono/apps/server/src/modules/health/health.service.ts

@@ -0,0 +1,59 @@
+import { appLogger } from '../../common/logger.js'
+import { checkDatabase } from '../../infrastructure/database/client.js'
+import { checkRedis } from '../../infrastructure/redis/client.js'
+
+interface DependencyHealth {
+  status: 'up' | 'down'
+  latencyMs: number
+}
+
+async function inspectDependency(
+  name: string,
+  check: () => Promise<void>,
+): Promise<DependencyHealth> {
+  const startedAt = performance.now()
+
+  try {
+    await check()
+    return {
+      status: 'up',
+      latencyMs: Math.round(performance.now() - startedAt),
+    }
+  } catch (error) {
+    appLogger.warn('Health dependency check failed', {
+      dependency: name,
+      error: error instanceof Error ? error.message : String(error),
+    })
+
+    return {
+      status: 'down',
+      latencyMs: Math.round(performance.now() - startedAt),
+    }
+  }
+}
+
+export function getLiveness() {
+  return {
+    status: 'ok' as const,
+    timestamp: new Date().toISOString(),
+    uptimeSeconds: Math.round(process.uptime()),
+  }
+}
+
+export async function getReadiness() {
+  const [database, redis] = await Promise.all([
+    inspectDependency('postgres', checkDatabase),
+    inspectDependency('redis', checkRedis),
+  ])
+  const isReady = database.status === 'up' && redis.status === 'up'
+
+  return {
+    status: isReady ? ('ok' as const) : ('error' as const),
+    timestamp: new Date().toISOString(),
+    uptimeSeconds: Math.round(process.uptime()),
+    dependencies: {
+      database,
+      redis,
+    },
+  }
+}

package/template-vp-monorepo-react-hono/apps/server/src/modules/jobs/jobs.queue.ts

@@ -0,0 +1,46 @@
+import { Queue } from 'bullmq'
+import { getEnv } from '../../config/env.js'
+import { createQueueConnection } from '../../infrastructure/queue/connection.js'
+import { DEMO_JOB_NAME, type DemoJobData, type DemoJobResult } from './jobs.types.js'
+
+let jobsQueue: Queue<DemoJobData, DemoJobResult> | undefined
+
+export function getJobsQueue(): Queue<DemoJobData, DemoJobResult> {
+  if (jobsQueue) return jobsQueue
+
+  const env = getEnv()
+  jobsQueue = new Queue<DemoJobData, DemoJobResult>(env.JOB_QUEUE_NAME, {
+    connection: createQueueConnection('queue'),
+    prefix: env.JOB_QUEUE_PREFIX,
+    defaultJobOptions: {
+      attempts: 3,
+      backoff: {
+        type: 'exponential',
+        delay: 1000,
+      },
+      removeOnComplete: {
+        age: 3600,
+        count: 1000,
+      },
+      removeOnFail: {
+        age: 86_400,
+        count: 5000,
+      },
+    },
+  })
+
+  return jobsQueue
+}
+
+export async function enqueueDemoJob(data: DemoJobData): Promise<string | undefined> {
+  const job = await getJobsQueue().add(DEMO_JOB_NAME, data, { jobId: data.jobRunId })
+  return job.id
+}
+
+export async function closeJobsQueue(): Promise<void> {
+  if (!jobsQueue) return
+
+  const queue = jobsQueue
+  jobsQueue = undefined
+  await queue.close()
+}

package/template-vp-monorepo-react-hono/apps/server/src/modules/jobs/jobs.repository.ts

@@ -0,0 +1,101 @@
+import { eq } from 'drizzle-orm'
+import { AppError } from '../../common/errors/app-error.js'
+import { getDatabase } from '../../infrastructure/database/client.js'
+import { jobRuns, type JobRun } from '../../infrastructure/database/schema/index.js'
+
+interface CreateJobRunInput {
+  queueName: string
+  jobName: string
+  payload: Record<string, unknown>
+}
+
+function requireJobRun(jobRun: JobRun | undefined, id?: string): JobRun {
+  if (jobRun) return jobRun
+
+  throw new AppError({
+    status: 404,
+    message: id ? '任务记录不存在: ' + id : '任务记录创建失败',
+  })
+}
+
+export async function createJobRun(input: CreateJobRunInput): Promise<JobRun> {
+  const [jobRun] = await getDatabase().insert(jobRuns).values(input).returning()
+  return requireJobRun(jobRun)
+}
+
+export async function findJobRun(id: string): Promise<JobRun | undefined> {
+  const [jobRun] = await getDatabase().select().from(jobRuns).where(eq(jobRuns.id, id)).limit(1)
+  return jobRun
+}
+
+export async function markJobRunProcessing(id: string, attempts: number): Promise<JobRun> {
+  const [jobRun] = await getDatabase()
+    .update(jobRuns)
+    .set({
+      status: 'processing',
+      attempts,
+      error: null,
+      startedAt: new Date(),
+      finishedAt: null,
+      updatedAt: new Date(),
+    })
+    .where(eq(jobRuns.id, id))
+    .returning()
+
+  return requireJobRun(jobRun, id)
+}
+
+export async function markJobRunQueuedForRetry(
+  id: string,
+  attempts: number,
+  error: string,
+): Promise<JobRun> {
+  const [jobRun] = await getDatabase()
+    .update(jobRuns)
+    .set({
+      status: 'queued',
+      attempts,
+      error: error.slice(0, 10_000),
+      startedAt: null,
+      finishedAt: null,
+      updatedAt: new Date(),
+    })
+    .where(eq(jobRuns.id, id))
+    .returning()
+
+  return requireJobRun(jobRun, id)
+}
+
+export async function markJobRunCompleted(
+  id: string,
+  result: Record<string, unknown>,
+): Promise<JobRun> {
+  const [jobRun] = await getDatabase()
+    .update(jobRuns)
+    .set({
+      status: 'completed',
+      result,
+      error: null,
+      finishedAt: new Date(),
+      updatedAt: new Date(),
+    })
+    .where(eq(jobRuns.id, id))
+    .returning()
+
+  return requireJobRun(jobRun, id)
+}
+
+export async function markJobRunFailed(id: string, error: string): Promise<JobRun> {
+  const [jobRun] = await getDatabase()
+    .update(jobRuns)
+    .set({
+      status: 'failed',
+      error: error.slice(0, 10_000),
+      finishedAt: new Date(),
+      updatedAt: new Date(),
+    })
+    .where(eq(jobRuns.id, id))
+    .returning()
+
+  return requireJobRun(jobRun, id)
+}

package/template-vp-monorepo-react-hono/apps/server/src/modules/jobs/jobs.routes.ts

@@ -0,0 +1,46 @@
+import { Hono } from 'hono'
+import { AppError } from '../../common/errors/app-error.js'
+import { apiSuccess } from '../../common/http/response.js'
+import { enqueueDemoJobSchema, jobRunIdSchema } from './jobs.schemas.js'
+import { createDemoJob, getJobRun } from './jobs.service.js'
+
+export const jobsRoutes = new Hono()
+
+jobsRoutes.post('/demo', async (context) => {
+  let body: unknown
+
+  try {
+    body = await context.req.json()
+  } catch {
+    throw new AppError({
+      status: 400,
+      message: '请求体必须是合法的 JSON',
+    })
+  }
+
+  const result = enqueueDemoJobSchema.safeParse(body)
+
+  if (!result.success) {
+    throw new AppError({
+      status: 422,
+      message: '请求参数校验失败',
+      details: result.error.flatten(),
+    })
+  }
+
+  const jobRun = await createDemoJob(result.data.payload)
+  return context.json(apiSuccess(jobRun, '任务已入队'), 201)
+})
+
+jobsRoutes.get('/:id', async (context) => {
+  const id = jobRunIdSchema.safeParse(context.req.param('id'))
+
+  if (!id.success) {
+    throw new AppError({
+      status: 400,
+      message: '任务 ID 格式不正确',
+    })
+  }
+
+  return context.json(apiSuccess(await getJobRun(id.data)))
+})

package/template-vp-monorepo-react-hono/apps/server/src/modules/jobs/jobs.schemas.ts

@@ -0,0 +1,9 @@
+import { z } from 'zod'
+
+export const enqueueDemoJobSchema = z
+  .object({
+    payload: z.record(z.string(), z.unknown()).default({}),
+  })
+  .strict()
+
+export const jobRunIdSchema = z.string().uuid()