@lota-sdk/core 0.1.5

package/src/workers/utils/sandbox-error.ts

@@ -0,0 +1,5 @@
+export function toSandboxedWorkerError(error: unknown, context?: string): Error {
+  const base = error instanceof Error ? error : new Error(String(error))
+  if (context) base.message = `${context}: ${base.message}`
+  return base
+}

package/src/workers/worker-utils.ts

@@ -0,0 +1,182 @@
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import type { Job, Worker } from 'bullmq'
+
+import { chatLogger } from '../config/logger'
+
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 10_000
+const MAX_TRACE_STRING_CHARS = 2_000
+const MAX_TRACE_ARRAY_ITEMS = 12
+const MAX_TRACE_OBJECT_KEYS = 24
+const MAX_TRACE_DEPTH = 4
+
+export function getWorkerPath(workerName: string): string {
+  return fileURLToPath(new URL(path.join('.', workerName), import.meta.url))
+}
+
+export interface WorkerHandle {
+  worker: Worker
+  shutdown: () => Promise<void>
+}
+
+interface TracedWorkerJobLike {
+  id?: unknown
+  name: string
+  attemptsMade: number | null | undefined
+  data?: unknown
+}
+
+function truncateTraceString(value: string, maxChars = MAX_TRACE_STRING_CHARS): string {
+  if (value.length <= maxChars) return value
+  return `${value.slice(0, maxChars - 3)}...`
+}
+
+function normalizeTraceValue(value: unknown, depth = 0): unknown {
+  if (value === null || value === undefined) return value
+  if (typeof value === 'string') return truncateTraceString(value)
+  if (typeof value === 'number' || typeof value === 'boolean') return value
+  if (typeof value === 'bigint') return value.toString()
+  if (typeof value === 'symbol') return value.description ? `Symbol(${value.description})` : 'Symbol()'
+  if (typeof value === 'function') return value.name ? `[function ${value.name}]` : '[function anonymous]'
+  if (value instanceof Date) return value.toISOString()
+
+  if (depth >= MAX_TRACE_DEPTH) {
+    if (Array.isArray(value)) return `[array(${value.length})]`
+    return '[object]'
+  }
+
+  if (Array.isArray(value)) {
+    return value.slice(0, MAX_TRACE_ARRAY_ITEMS).map((item) => normalizeTraceValue(item, depth + 1))
+  }
+
+  if (!(value instanceof Date) && typeof value === 'object') {
+    const record = value as Record<string, unknown>
+    return Object.fromEntries(
+      Object.entries(record)
+        .slice(0, MAX_TRACE_OBJECT_KEYS)
+        .map(([key, entryValue]) => [key, normalizeTraceValue(entryValue, depth + 1)]),
+    )
+  }
+
+  return '[unknown]'
+}
+
+function serializeTraceValue(value: unknown): string {
+  const serialized = JSON.stringify(normalizeTraceValue(value))
+  return truncateTraceString(serialized || 'null')
+}
+
+function traceTextValue(value: unknown): string {
+  if (typeof value === 'string') return truncateTraceString(value)
+  if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+    return truncateTraceString(String(value))
+  }
+  if (value instanceof Date) return value.toISOString()
+  return serializeTraceValue(value)
+}
+
+export function buildWorkerObservationMetadata(
+  queueName: string,
+  job: { id?: unknown; name: string; attemptsMade: number | null | undefined },
+): Record<string, string> {
+  return {
+    queue: traceTextValue(queueName),
+    job_name: traceTextValue(job.name),
+    ...(job.id !== undefined ? { job_id: traceTextValue(job.id) } : {}),
+    ...(job.attemptsMade !== null && job.attemptsMade !== undefined
+      ? { attempts_made: traceTextValue(job.attemptsMade) }
+      : {}),
+  }
+}
+
+export const attachWorkerEvents = (worker: Worker, name: string, logger: typeof chatLogger = chatLogger) => {
+  worker.on('ready', () => {
+    logger.info`${name} worker ready`
+  })
+
+  worker.on('active', (job) => {
+    logger.debug`${name} job active (${job.id})`
+  })
+
+  worker.on('completed', (job) => {
+    logger.debug`${name} job completed (${job.id})`
+  })
+
+  worker.on('failed', (job: Job | undefined, error) => {
+    const attemptsMade = job?.attemptsMade
+    const attempts = job?.opts.attempts
+    const failedReason = job?.failedReason
+    const stacktrace = job?.stacktrace
+
+    const attemptInfo =
+      typeof attemptsMade === 'number' || typeof attempts === 'number'
+        ? ` attempt=${attemptsMade ?? '?'}${attempts ? `/${attempts}` : ''}`
+        : ''
+
+    const reasonInfo = typeof failedReason === 'string' && failedReason.length > 0 ? ` reason="${failedReason}"` : ''
+
+    const latestStack =
+      Array.isArray(stacktrace) && stacktrace.length > 0 ? stacktrace.at(-1)?.trim() || undefined : undefined
+    const stackInfo = latestStack ? ` stacktrace="${latestStack}"` : ''
+
+    logger.error`${name} job failed (${job?.id})${attemptInfo}:${reasonInfo}${stackInfo} ${error}`
+  })
+
+  worker.on('error', (error) => {
+    logger.error`${name} worker error: ${error}`
+  })
+
+  worker.on('stalled', (jobId) => {
+    logger.warn`${name} job stalled (${jobId})`
+  })
+}
+
+export const createWorkerShutdown = (worker: Worker, name: string, logger: typeof chatLogger = chatLogger) => {
+  return async () => {
+    logger.info`Shutting down ${name} worker`
+    await worker.close()
+  }
+}
+
+export function createTracedWorkerProcessor<TJob extends TracedWorkerJobLike>(
+  _queueName: string,
+  processor: (job: TJob) => Promise<void>,
+): (job: TJob) => Promise<void> {
+  return async (job: TJob) => processor(job)
+}
+
+export const registerShutdownSignals = ({
+  name,
+  shutdown,
+  logger = chatLogger,
+  timeoutMs = DEFAULT_SHUTDOWN_TIMEOUT_MS,
+}: {
+  name: string
+  shutdown: () => Promise<void>
+  logger?: typeof chatLogger
+  timeoutMs?: number
+}) => {
+  let shuttingDown = false
+
+  const handleSignal = () => {
+    if (shuttingDown) return
+    shuttingDown = true
+    const timeout = setTimeout(() => {
+      logger.warn`Forced shutdown after ${timeoutMs}ms`
+      process.exit(0)
+    }, timeoutMs)
+
+    shutdown()
+      .catch((err: unknown) => {
+        logger.error`Failed to shutdown ${name} worker: ${err}`
+      })
+      .finally(() => {
+        clearTimeout(timeout)
+        process.exit(0)
+      })
+  }
+
+  process.once('SIGINT', () => handleSignal())
+  process.once('SIGTERM', () => handleSignal())
+}