nmtjs 0.15.0-beta.2 → 0.15.0-beta.21

package/src/runtime/server/jobs.ts

@@ -0,0 +1,250 @@
+import type { Logger } from '@nmtjs/core'
+import type { RedisClient } from 'bullmq'
+import { Queue, UnrecoverableError, Worker } from 'bullmq'
+
+import type { AnyJob } from '../jobs/job.ts'
+import type { JobsUI } from '../jobs/ui.ts'
+import type { JobTaskResult, Store, WorkerJobTask } from '../types.ts'
+import type { ServerConfig } from './config.ts'
+import type { ApplicationServerWorkerConfig } from './server.ts'
+import { JobWorkerPool } from '../enums.ts'
+import { getJobQueueName } from '../jobs/manager.ts'
+import { createJobsUI } from '../jobs/ui.ts'
+import { Pool } from './pool.ts'
+
+export class JobRunnersPool extends Pool {
+  protected runIndex = 0
+
+  async run(task: WorkerJobTask): Promise<JobTaskResult> {
+    if (this.threads.length === 0) {
+      throw new Error('No job runner threads available')
+    }
+
+    if (this.runIndex >= this.threads.length) {
+      this.runIndex = 0
+    }
+
+    const thread = this.threads[this.runIndex]!
+    this.runIndex++
+    return await thread.run(task)
+  }
+}
+
+export class ApplicationServerJobs {
+  /**
+   * BullMQ workers - one per job (dedicated queues)
+   */
+  queueWorkers = new Set<Worker>()
+  ui?: JobsUI
+  protected uiQueues: Queue[] = []
+
+  jobs: Map<string, AnyJob>
+
+  /**
+   * Shared resource pools by pool type (Io, Compute).
+   * All jobs of a given pool type share the same pool for resource management.
+   */
+  protected pools = new Map<JobWorkerPool, JobRunnersPool>()
+
+  constructor(
+    readonly params: {
+      logger: Logger
+      serverConfig: ServerConfig
+      workerConfig: ApplicationServerWorkerConfig
+      store: Store
+    },
+  ) {
+    this.jobs = params.serverConfig.jobs
+      ? params.serverConfig.jobs.jobs
+      : new Map()
+  }
+
+  async start() {
+    const { logger, serverConfig, workerConfig, store } = this.params
+    const jobsConfig = serverConfig.jobs
+
+    if (!jobsConfig) {
+      logger.debug('Jobs are not configured, skipping')
+      return
+    }
+
+    if (jobsConfig.ui) {
+      const hostname = jobsConfig.ui.hostname ?? '127.0.0.1'
+      const port = jobsConfig.ui.port ?? 3000
+
+      this.uiQueues = [...this.jobs.values()].map(
+        (job) =>
+          new Queue(getJobQueueName(job), {
+            connection: store as unknown as RedisClient,
+          }),
+      )
+
+      this.ui = createJobsUI(this.uiQueues)
+
+      await new Promise<void>((resolve, reject) => {
+        if (!this.ui) return reject(new Error('Jobs UI server is missing'))
+        this.ui.once('error', reject)
+        this.ui.listen(port, hostname, resolve)
+      })
+
+      const address = this.ui.address()
+      const resolved =
+        address && typeof address !== 'string'
+          ? { hostname: address.address, port: address.port }
+          : { hostname, port }
+
+      logger.info({ ...resolved }, 'Jobs UI started')
+    }
+
+    // Step 1: Initialize shared resource pools (Io, Compute)
+    const poolTypes = Object.values(JobWorkerPool)
+
+    for (const poolType of poolTypes) {
+      const poolConfig = jobsConfig.pools[poolType]
+      if (!poolConfig) continue
+
+      const pool = new JobRunnersPool({
+        path: workerConfig.path,
+        worker: workerConfig.worker,
+        workerData: { ...workerConfig.workerData },
+      })
+
+      for (let i = 0; i < poolConfig.threads; i++) {
+        pool.add({
+          index: i,
+          name: `job-pool-${poolType}`,
+          workerData: { runtime: { type: 'jobs', jobWorkerPool: poolType } },
+        })
+      }
+
+      await pool.start()
+      this.pools.set(poolType, pool)
+
+      logger.info(
+        {
+          pool: poolType,
+          threads: poolConfig.threads,
+          jobsPerThread: poolConfig.jobs,
+        },
+        'Job runner pool started',
+      )
+    }
+
+    // Step 2: Create a dedicated BullMQ Worker for each job
+    // Calculate how many jobs use each pool for fair concurrency distribution
+    const jobsPerPool = new Map<JobWorkerPool, number>()
+    for (const job of this.jobs.values()) {
+      const count = jobsPerPool.get(job.options.pool) ?? 0
+      jobsPerPool.set(job.options.pool, count + 1)
+    }
+
+    for (const job of this.jobs.values()) {
+      const queueName = getJobQueueName(job)
+      const poolType = job.options.pool
+      const pool = this.pools.get(poolType)
+
+      if (!pool) {
+        logger.warn(
+          { job: job.name, pool: poolType },
+          'No pool configured for job, skipping worker creation',
+        )
+        continue
+      }
+
+      const poolConfig = jobsConfig.pools[poolType]
+      const poolCapacity = poolConfig.threads * poolConfig.jobs
+      const jobCountInPool = jobsPerPool.get(poolType) ?? 1
+      // Use job-specific concurrency if provided, otherwise distribute pool capacity evenly
+      const defaultConcurrency = Math.max(
+        1,
+        Math.floor(poolCapacity / jobCountInPool),
+      )
+      const concurrency = job.options.concurrency ?? defaultConcurrency
+
+      const queueWorker = new Worker(
+        queueName,
+        async (bullJob) => {
+          const task: WorkerJobTask = {
+            jobId: String(bullJob.id ?? ''),
+            jobName: bullJob.name,
+            data: bullJob.data,
+          }
+
+          const result = await pool.run(task)
+          switch (result.type) {
+            case 'success':
+              return result.result
+            case 'unrecoverable_error':
+              throw new UnrecoverableError(
+                typeof result.error === 'string'
+                  ? result.error
+                  : 'Unrecoverable error',
+              )
+            case 'job_not_found':
+            case 'queue_job_not_found':
+              throw new UnrecoverableError(result.type)
+            case 'error':
+              console.error(result.error)
+              throw result.error
+            default:
+              throw new UnrecoverableError('Unknown job task result')
+          }
+        },
+        { connection: store as unknown as RedisClient, concurrency },
+      )
+
+      this.queueWorkers.add(queueWorker)
+      logger.info(
+        { job: job.name, queue: queueName, pool: poolType, concurrency },
+        'Job queue worker started',
+      )
+    }
+  }
+
+  async stop() {
+    const { logger } = this.params
+
+    if (this.ui) {
+      await new Promise<void>((resolve) => {
+        this.ui?.close(() => resolve())
+      }).catch((error) => {
+        logger.warn({ error }, 'Failed to stop Jobs UI server')
+      })
+    }
+
+    await Promise.all(
+      this.uiQueues.map(async (queue) => {
+        try {
+          await queue.close()
+        } catch (error) {
+          logger.warn({ error }, 'Failed to close Jobs UI queue')
+        }
+      }),
+    )
+    this.uiQueues = []
+    this.ui = undefined
+
+    // Stop accepting new jobs first.
+    await Promise.all(
+      [...this.queueWorkers].map(async (worker) => {
+        try {
+          await worker.close()
+        } catch (error) {
+          logger.warn({ error }, 'Failed to close BullMQ worker')
+        }
+      }),
+    )
+    this.queueWorkers.clear()
+
+    await Promise.all(
+      Array.from(this.pools.values()).map(async (pool) => {
+        try {
+          await pool.stop()
+        } catch (error) {
+          logger.warn({ error }, 'Failed to stop job pool')
+        }
+      }),
+    )
+    this.pools.clear()
+  }
+}

package/src/runtime/server/pool.ts

@@ -0,0 +1,260 @@
+import type { MessagePort, WorkerOptions } from 'node:worker_threads'
+import { randomUUID } from 'node:crypto'
+import EventEmitter, { once } from 'node:events'
+import { MessageChannel, Worker } from 'node:worker_threads'
+
+import type {
+  JobTaskResult,
+  ServerPortMessageTypes,
+  ThreadErrorMessage,
+  ThreadPortMessage,
+  ThreadPortMessageTypes,
+  WorkerJobTask,
+  WorkerThreadError,
+} from '../types.ts'
+
+const omitExecArgv = ['--expose-gc']
+
+export type ThreadState =
+  | 'starting'
+  | 'error'
+  | 'terminating'
+  | 'pending'
+  | 'ready'
+
+export class Thread extends EventEmitter<
+  {
+    error: [error: WorkerThreadError]
+    ready: [ThreadPortMessageTypes['ready']]
+    task: [ThreadPortMessageTypes['task']]
+    terminate: []
+  } & {
+    [K in `task-${ThreadPortMessageTypes['task']['id']}`]: [
+      ThreadPortMessageTypes['task']['task'],
+    ]
+  }
+> {
+  worker: Worker
+  state: ThreadState = 'pending'
+  protected readyMessage?: ThreadPortMessageTypes['ready']
+  protected startPromise?: Promise<void>
+
+  constructor(
+    readonly port: MessagePort,
+    workerPath: string,
+    workerOptions: WorkerOptions,
+  ) {
+    super()
+    this.worker = new Worker(workerPath, {
+      ...workerOptions,
+      execArgv: process.execArgv.filter((f) => !omitExecArgv.includes(f)),
+    })
+
+    this.port.on('message', (msg: ThreadPortMessage) => {
+      const { type, data } = msg
+      switch (type) {
+        case 'ready': {
+          this.state = 'ready'
+          this.readyMessage = data
+          this.emit('ready', data)
+          break
+        }
+        case 'error': {
+          const error = createWorkerThreadError(data as ThreadErrorMessage)
+          this.state = 'error'
+          this.emit('error', error)
+          break
+        }
+        case 'task': {
+          this.emit('task', data as ThreadPortMessageTypes['task'])
+          const { id, task } = data as ThreadPortMessageTypes['task']
+          this.emit(`task-${id}`, task)
+          break
+        }
+      }
+    })
+
+    this.worker.once('exit', (code) => {
+      if (this.state === 'terminating') return
+      const error = createWorkerThreadError(
+        {
+          message: `Worker thread ${this.worker.threadId} exited unexpectedly with code ${code}`,
+          name: 'WorkerThreadExitError',
+          origin: 'runtime',
+          fatal: code !== 0,
+        },
+        false,
+      )
+      this.state = 'error'
+      this.emit('error', error)
+    })
+  }
+
+  async start() {
+    if (this.state === 'ready') return
+    if (this.startPromise) return this.startPromise
+    switch (this.state) {
+      case 'error':
+      case 'terminating':
+      case 'starting':
+        throw new Error('Cannot start worker thread in current state')
+      case 'pending':
+        break
+    }
+    this.state = 'starting'
+    this.startPromise = new Promise<void>((resolve, reject) => {
+      let settled = false
+      let timer: NodeJS.Timeout
+      const cleanup = () => {
+        if (settled) return
+        settled = true
+        if (timer) clearTimeout(timer)
+        this.off('ready', handleReady)
+        this.off('error', handleError)
+        this.startPromise = undefined
+      }
+      const handleReady = () => {
+        cleanup()
+        resolve()
+      }
+      const handleError = (error: WorkerThreadError) => {
+        cleanup()
+        reject(error)
+      }
+
+      this.once('ready', handleReady)
+      this.once('error', handleError)
+
+      timer = setTimeout(() => {
+        const error = createWorkerThreadError(
+          {
+            message: 'Worker thread did not become ready in time',
+            name: 'WorkerStartupTimeoutError',
+            origin: 'start',
+            fatal: true,
+          },
+          false,
+        )
+        cleanup()
+        this.state = 'error'
+        this.emit('error', error)
+        reject(error)
+      }, 15000)
+    })
+    await this.startPromise
+    this.startPromise = undefined
+  }
+
+  async stop() {
+    switch (this.state) {
+      case 'error':
+      case 'terminating':
+      case 'starting':
+        throw new Error('Cannot stop worker thread in this state')
+      case 'ready':
+      case 'pending': {
+        this.state = 'terminating'
+        // TODO: make timeout configurable
+        const signal = AbortSignal.timeout(10000)
+        const exit = once(this.worker, 'exit', { signal })
+        this.send('stop')
+        this.port.close()
+        try {
+          await exit
+        } catch (err) {
+          console.dir(err)
+          console.warn(
+            `Worker thread ${this.worker.threadId} did not terminate in time, terminating forcefully...`,
+          )
+          await this.worker.terminate()
+        }
+      }
+    }
+  }
+
+  async run(task: WorkerJobTask): Promise<JobTaskResult> {
+    const id = randomUUID()
+    this.send('task', { id, task })
+    const [result] = await once(this, `task-${id}`)
+    return result
+  }
+
+  async send<T extends keyof ServerPortMessageTypes>(
+    type: T,
+    ...[data]: ServerPortMessageTypes[T] extends undefined
+      ? []
+      : [data: ServerPortMessageTypes[T]]
+  ) {
+    this.port.postMessage({ type, data })
+  }
+}
+
+function createWorkerThreadError(
+  message: ThreadErrorMessage,
+  includeStack = true,
+): WorkerThreadError {
+  const error = new Error(message.message) as WorkerThreadError
+  if (message.name) error.name = message.name
+  if (includeStack && message.stack) {
+    error.stack = message.stack
+  }
+  error.origin = message.origin
+  error.fatal = message.fatal
+  return error
+}
+
+export class Pool extends EventEmitter<{
+  workerReady: [worker: Worker]
+  workerTaskResult: [worker: Worker]
+}> {
+  protected readonly threads: Thread[] = []
+
+  constructor(
+    readonly options: {
+      path: string
+      workerData?: any
+      worker?: (worker: Worker) => any
+    },
+  ) {
+    super()
+  }
+
+  add(options: { index: number; name: string; workerData?: any }) {
+    return this.createThread(options)
+  }
+
+  async start() {
+    await Promise.all(this.threads.map((thread) => thread.start()))
+  }
+
+  async stop() {
+    await Promise.all(this.threads.map((thread) => thread.stop()))
+  }
+
+  protected createThread(
+    options: { index: number; name: string; workerData?: any },
+    index?: number,
+  ) {
+    const { port1, port2 } = new MessageChannel()
+    const thread = new Thread(port1, this.options.path, {
+      workerData: {
+        ...this.options.workerData,
+        ...options.workerData,
+        port: port2,
+      },
+      name: `${options.name}-${options.index + 1}`,
+      transferList: [port2],
+    })
+    if (index !== undefined) {
+      this.threads[index] = thread
+    } else {
+      index = this.threads.push(thread) - 1
+    }
+    this.options.worker?.(thread.worker)
+    thread.once('error', (error) => {
+      thread.worker.terminate()
+      this.createThread(options)
+    })
+    return thread
+  }
+}

package/src/runtime/server/proxy.ts

@@ -0,0 +1,118 @@
+import type { Logger } from '@nmtjs/core'
+import { Proxy as NeemataProxy } from '@nmtjs/proxy'
+
+import type {
+  ApplicationProxyUpstream,
+  ApplicationServerApplications,
+} from './applications.ts'
+import type { ServerConfig } from './config.ts'
+
+/**
+ * Transform ApplicationProxyUpstream to the format expected by Rust proxy.
+ */
+function toProxyUpstream(upstream: ApplicationProxyUpstream) {
+  const url = new URL(upstream.url)
+  const isWebSocket = url.protocol === 'wss:' || url.protocol === 'ws:'
+  const secure = url.protocol === 'https:' || url.protocol === 'wss:'
+  const port = url.port ? Number.parseInt(url.port, 10) : secure ? 443 : 80
+
+  return {
+    type: 'port',
+    // WebSocket requires HTTP/1.1 for upgrade
+    transport: isWebSocket ? 'http' : upstream.type,
+    secure,
+    hostname: url.hostname,
+    port,
+  }
+}
+
+export class ApplicationServerProxy {
+  proxyServer: NeemataProxy
+
+  protected readonly onAdd: (application: string, upstream: any) => void
+  protected readonly onRemove: (application: string, upstream: any) => void
+
+  constructor(
+    readonly params: {
+      logger: Logger
+      config: ServerConfig['proxy']
+      applications: ApplicationServerApplications
+    },
+  ) {
+    const { config } = params
+    if (!config) {
+      throw new Error('Proxy config is required')
+    }
+
+    this.proxyServer = new NeemataProxy({
+      listen: `${config.hostname}:${config.port}`,
+      tls: config.tls
+        ? { keyPath: config.tls.key, certPath: config.tls.cert }
+        : undefined,
+      applications: Object.entries(config.applications)
+        .filter(([_, options]) => options !== undefined)
+        .map(([app, options]) => ({
+          name: app,
+          routing: options!.routing,
+          sni: options!.sni,
+        })),
+    })
+
+    this.onAdd = (application, upstream) => {
+      const proxyUpstream = toProxyUpstream(upstream)
+      this.params.logger.debug(
+        { application, upstream: proxyUpstream },
+        'Adding upstream to proxy',
+      )
+      void this.proxyServer
+        .addUpstream(application, proxyUpstream)
+        .catch((error) => {
+          this.params.logger.warn(
+            { error, application, upstream: proxyUpstream },
+            'Failed to add upstream to proxy',
+          )
+        })
+    }
+
+    this.onRemove = (application, upstream) => {
+      const proxyUpstream = toProxyUpstream(upstream)
+      this.params.logger.debug(
+        { application, upstream: proxyUpstream },
+        'Removing upstream from proxy',
+      )
+
+      void this.proxyServer
+        .removeUpstream(application, proxyUpstream)
+        .catch((error) => {
+          this.params.logger.warn(
+            { error, application, upstream: proxyUpstream },
+            'Failed to remove upstream from proxy',
+          )
+        })
+    }
+
+    params.applications.on('add', this.onAdd)
+    params.applications.on('remove', this.onRemove)
+  }
+
+  async start() {
+    const { config } = this.params
+    if (!config) {
+      throw new Error('Proxy config is required')
+    }
+    this.params.logger.info(
+      { hostname: config.hostname, port: config.port, threads: config.threads },
+      'Starting proxy server...',
+    )
+    await this.proxyServer.start()
+  }
+
+  async stop() {
+    this.params.logger.info('Stopping proxy server...')
+
+    this.params.applications.off('add', this.onAdd)
+    this.params.applications.off('remove', this.onRemove)
+
+    await this.proxyServer.stop()
+  }
+}