nmtjs 0.15.0-beta.2 → 0.15.0-beta.20

package/src/runtime/server/server.ts

@@ -0,0 +1,155 @@
+import type EventEmitter from 'node:events'
+import type { Worker } from 'node:worker_threads'
+
+import type { Logger } from '@nmtjs/core'
+import { createLogger } from '@nmtjs/core'
+
+import type {
+  Store,
+  ThreadPortMessageTypes,
+  WorkerThreadError,
+} from '../types.ts'
+import type { ServerConfig } from './config.ts'
+import { createStoreClient } from '../store/index.ts'
+import { ApplicationServerApplications } from './applications.ts'
+import { ApplicationServerJobs } from './jobs.ts'
+import { ApplicationServerProxy } from './proxy.ts'
+
+export type ApplicationServerRunOptions = {
+  applications: string[]
+  scheduler: boolean
+  jobs: boolean
+}
+
+export type ApplicationWorkerReadyEvent = {
+  application: string
+  threadId: number
+  hosts?: ThreadPortMessageTypes['ready']['hosts']
+}
+
+export type ApplicationWorkerErrorEvent = {
+  application: string
+  threadId: number
+  error: WorkerThreadError
+}
+
+export type ApplicationServerWorkerConfig = {
+  path: string
+  workerData?: any
+  worker?: (worker: Worker) => any
+  events?: EventEmitter<{
+    worker: [Worker]
+    'worker-ready': [ApplicationWorkerReadyEvent]
+    'worker-error': [ApplicationWorkerErrorEvent]
+  }>
+}
+
+export class ApplicationServer {
+  logger: Logger
+
+  applications?: ApplicationServerApplications
+  jobRunners?: ApplicationServerJobs
+
+  proxy?: ApplicationServerProxy
+  store?: Store
+
+  constructor(
+    readonly config: ServerConfig,
+    readonly applicationsConfig: Record<
+      string,
+      { type: 'neemata' | 'custom'; specifier: string }
+    >,
+    readonly workerConfig: ApplicationServerWorkerConfig,
+    readonly runOptions: ApplicationServerRunOptions = {
+      applications: Object.keys(config.applications),
+      scheduler: false,
+      jobs: Boolean(config.jobs?.jobs.size),
+    },
+  ) {
+    this.logger = createLogger(config.logger, 'Server')
+    this.logger.trace(
+      { applications: applicationsConfig, workerConfig, runOptions },
+      'ApplicationServer initialized',
+    )
+  }
+
+  async start() {
+    const { config, logger } = this
+    logger.info('Starting application server...')
+
+    if (config.store) {
+      this.store = await createStoreClient(config.store)
+      await this.store.connect()
+      logger.debug('Store connected')
+    }
+
+    this.applications = new ApplicationServerApplications({
+      logger: this.logger,
+      workerConfig: this.workerConfig,
+      serverConfig: this.config,
+      applicationsConfig: this.applicationsConfig,
+      applications: this.runOptions.applications,
+    })
+
+    if (this.runOptions.jobs) {
+      if (!this.store) {
+        throw new Error(
+          'Jobs feature requires a store configuration. ' +
+            'Please configure `store` in your server config or disable jobs.',
+        )
+      }
+      this.jobRunners = new ApplicationServerJobs({
+        logger: this.logger,
+        workerConfig: this.workerConfig,
+        serverConfig: this.config,
+        store: this.store,
+      })
+    }
+
+    if (this.config.proxy) {
+      this.proxy = new ApplicationServerProxy({
+        logger: this.logger,
+        config: this.config.proxy,
+        applications: this.applications,
+      })
+    }
+
+    await this.applications.start()
+
+    if (this.runOptions.jobs) {
+      await this.jobRunners?.start()
+    }
+
+    if (this.runOptions.scheduler && config.jobs?.scheduler) {
+      throw new Error(
+        'JobsScheduler is currently a work in progress and not available. ' +
+          'Scheduled jobs will be supported in a future release.',
+      )
+    }
+
+    if (this.proxy) {
+      await this.proxy.start()
+    }
+
+    logger.info('Application server started')
+  }
+
+  async stop() {
+    this.logger.info('Stopping application server...')
+
+    // Stop proxy + stop accepting new jobs first
+    await this.proxy?.stop()
+    await this.jobRunners?.stop()
+
+    // Stop applications
+    await this.applications?.stop()
+
+    // Close store connection
+    if (this.store) {
+      this.logger.debug('Closing store...')
+      this.store.disconnect(false)
+    }
+
+    this.logger.info('Application server stopped')
+  }
+}

package/src/runtime/store/index.ts

@@ -0,0 +1,30 @@
+import type { ServerStoreConfig } from '../server/config.ts'
+import type { StoreTypes } from '../types.ts'
+import { StoreType } from '../enums.ts'
+
+export async function createStoreClient<T extends ServerStoreConfig>(
+  config: T,
+): Promise<StoreTypes[T['type']]> {
+  if (config.type === StoreType.Redis) {
+    const { Redis } = await import('ioredis').catch(() => {
+      throw new Error(
+        'ioredis package is not installed. Please install it to use Redis store.',
+      )
+    })
+    return new Redis({
+      ...config.options,
+      lazyConnect: true,
+    }) as StoreTypes[T['type']]
+  } else if (config.type === StoreType.Valkey) {
+    const { Redis } = await import('iovalkey').catch(() => {
+      throw new Error(
+        'iovalkey package is not installed. Please install it to use Valkey store.',
+      )
+    })
+    return new Redis({
+      ...config.options,
+      lazyConnect: true,
+    }) as StoreTypes[T['type']]
+  }
+  throw new Error('Unsupported store')
+}

package/src/runtime/types.ts

@@ -0,0 +1,93 @@
+import type { HookTypes } from '@nmtjs/core'
+import type { ProxyableTransportType } from '@nmtjs/gateway'
+import type { Redis, RedisOptions } from 'ioredis'
+import type { Redis as Valkey, RedisOptions as ValkeyOptions } from 'iovalkey'
+
+import type { ApplicationConfig } from './application/config.ts'
+import type { BaseRuntime } from './core/runtime.ts'
+import type { LifecycleHook, StoreType } from './enums.ts'
+
+export type WorkerThreadErrorOrigin = 'bootstrap' | 'start' | 'runtime'
+
+export type ThreadErrorMessage = {
+  message: string
+  name?: string
+  stack?: string
+  origin: WorkerThreadErrorOrigin
+  fatal: boolean
+}
+
+export type WorkerThreadError = Error & {
+  origin?: WorkerThreadErrorOrigin
+  fatal?: boolean
+}
+
+export type ServerPortMessageTypes = {
+  stop: undefined
+  task: { id: string; task: WorkerJobTask }
+}
+
+export type ThreadPortMessageTypes = {
+  ready: { hosts?: { type: ProxyableTransportType; url: string }[] }
+  error: ThreadErrorMessage
+  task: { id: string; task: JobTaskResult }
+}
+
+export type ServerPortMessage = {
+  [K in keyof ServerPortMessageTypes]: {
+    type: K
+    data: ServerPortMessageTypes[K]
+  }
+}[keyof ServerPortMessageTypes]
+
+export type ThreadPortMessage = {
+  [K in keyof ThreadPortMessageTypes]: {
+    type: K
+    data: ThreadPortMessageTypes[K]
+  }
+}[keyof ThreadPortMessageTypes]
+
+export interface WorkerTask {
+  type?: string
+  payload?: any
+}
+
+export type WorkerJobTask = { jobId: string; jobName: string; data: any }
+
+export type JobTaskResult = {
+  [K in keyof JobTaskResultTypes]: { type: K } & JobTaskResultTypes[K]
+}[keyof JobTaskResultTypes]
+
+export type JobTaskResultTypes = {
+  success: { result?: unknown }
+  error: { error: any }
+  unrecoverable_error: { error: any }
+  job_not_found: {}
+  queue_job_not_found: {}
+}
+
+export interface LifecycleHookTypes extends HookTypes {
+  [LifecycleHook.BeforeInitialize]: (runtime: BaseRuntime) => any
+  [LifecycleHook.AfterInitialize]: (runtime: BaseRuntime) => any
+  [LifecycleHook.BeforeDispose]: (runtime: BaseRuntime) => any
+  [LifecycleHook.AfterDispose]: (runtime: BaseRuntime) => any
+}
+
+export type ApplicationDefinitionType =
+  | { type: 'neemata'; definition: ApplicationConfig<any, any> }
+  | { type: 'custom'; definition: any }
+
+export interface Applications
+  extends Record<string, ApplicationDefinitionType> {}
+
+export type StoreTypes = {
+  [StoreType.Redis]: Redis
+  [StoreType.Valkey]: Valkey
+}
+export type StoreTypeOptions = {
+  [StoreType.Redis]: RedisOptions
+  [StoreType.Valkey]: ValkeyOptions
+}
+
+export type Store = StoreTypes[StoreType]
+export type StoreOptions = StoreTypeOptions[StoreType]

package/src/runtime/workers/application.ts

@@ -0,0 +1,209 @@
+import type { Dependant } from '@nmtjs/core'
+import type { GatewayOptions, Transport } from '@nmtjs/gateway'
+import { Gateway } from '@nmtjs/gateway'
+import { JsonFormat } from '@nmtjs/json-format/server'
+import { ProtocolFormats } from '@nmtjs/protocol/server'
+
+import type { ApplicationConfig } from '../application/config.ts'
+import type {
+  AnyFilter,
+  AnyGuard,
+  AnyMiddleware,
+  AnyProcedure,
+  AnyRouter,
+  kDefaultProcedure as kDefaultProcedureKey,
+} from '../application/index.ts'
+import type { ServerConfig } from '../server/config.ts'
+import { ApplicationApi } from '../application/api/api.ts'
+import { ApplicationHooks } from '../application/hooks.ts'
+import {
+  isProcedure,
+  isRootRouter,
+  isRouter,
+  kDefaultProcedure,
+  kRootRouter,
+} from '../application/index.ts'
+import { LifecycleHook, WorkerType } from '../enums.ts'
+import { BaseWorkerRuntime } from './base.ts'
+
+export interface ApplicationWorkerRuntimeOptions {
+  name: string
+  path: string
+  transports: { [key: string]: any }
+}
+
+export class ApplicationWorkerRuntime extends BaseWorkerRuntime {
+  api!: ApplicationApi
+  applicationHooks!: ApplicationHooks
+  gateway!: Gateway
+  transports!: GatewayOptions['transports']
+
+  routers = new Map<string | kRootRouter, AnyRouter>()
+  procedures = new Map<
+    string | kDefaultProcedureKey,
+    { procedure: AnyProcedure; path: AnyRouter[] }
+  >()
+  filters = new Set<AnyFilter>()
+  middlewares = new Set<AnyMiddleware>()
+  guards = new Set<AnyGuard>()
+
+  constructor(
+    readonly config: ServerConfig,
+    readonly runtimeOptions: ApplicationWorkerRuntimeOptions,
+    protected appConfig: ApplicationConfig,
+  ) {
+    super(
+      config,
+      {
+        logger: config.logger,
+        name: `Worker ${runtimeOptions.name}`,
+        plugins: appConfig.plugins,
+      },
+      WorkerType.Application,
+    )
+
+    this.applicationHooks = new ApplicationHooks()
+
+    this.api = new ApplicationApi({
+      timeout: this.appConfig.api.timeout,
+      container: this.container,
+      logger: this.logger,
+      filters: this.filters,
+      middlewares: this.middlewares,
+      guards: this.guards,
+      procedures: this.procedures,
+    })
+  }
+
+  async start() {
+    await this.initialize()
+
+    this.transports = {}
+
+    for (const key in this.runtimeOptions.transports) {
+      const options = this.runtimeOptions.transports[key]
+      const { factory, proxyable } = this.appConfig.transports[key] as Transport
+      this.transports[key] = { transport: await factory(options), proxyable }
+    }
+
+    this.gateway = new Gateway({
+      logger: this.logger,
+      container: this.container,
+      hooks: this.lifecycleHooks,
+      formats: new ProtocolFormats([new JsonFormat()]),
+      transports: this.transports,
+      api: this.api,
+      identity: this.appConfig.identity,
+    })
+
+    return await this.gateway.start().finally(async () => {
+      await this.lifecycleHooks.callHook(LifecycleHook.Start)
+    })
+  }
+
+  async stop() {
+    await this.gateway.stop()
+    await this.dispose()
+    await this.lifecycleHooks.callHook(LifecycleHook.Stop)
+  }
+
+  async reload(appConfig: ApplicationConfig): Promise<void> {
+    await this.dispose()
+    this.appConfig = appConfig
+    this.plugins = appConfig.plugins
+    await this.initialize()
+    this.gateway.options.identity =
+      this.appConfig.identity ?? this.gateway.options.identity
+    await this.gateway.reload()
+  }
+
+  async initialize(): Promise<void> {
+    this.registerApi()
+    this.lifecycleHooks.addHooks(this.appConfig.lifecycleHooks)
+    await super.initialize()
+  }
+
+  protected async _initialize(): Promise<void> {
+    await super._initialize()
+
+    for (const hook of this.appConfig.hooks) {
+      this.applicationHooks.hook(hook.name, async (...args: any[]) => {
+        const ctx = await this.container.createContext(hook.dependencies)
+        await hook.handler(ctx, ...args)
+      })
+    }
+  }
+
+  protected async _dispose(): Promise<void> {
+    this.applicationHooks.removeAllHooks()
+    await super._dispose()
+    this.lifecycleHooks.removeHooks(this.appConfig.lifecycleHooks)
+    this.filters.clear()
+    this.middlewares.clear()
+    this.guards.clear()
+    this.routers.clear()
+    this.procedures.clear()
+  }
+
+  protected *_dependents(): Generator<Dependant> {
+    yield* this.appConfig.filters
+    yield* this.appConfig.guards
+    yield* this.appConfig.middlewares
+    yield* this.appConfig.hooks
+    for (const { procedure } of this.procedures.values()) {
+      yield procedure
+      yield* procedure.guards
+      yield* procedure.middlewares
+    }
+  }
+
+  protected registerApi() {
+    const { router, filters, guards, middlewares } = this.appConfig
+
+    if (this.routers.has(kRootRouter)) {
+      throw new Error('Root router already registered')
+    }
+
+    if (!isRootRouter(router)) {
+      throw new Error('Root router must be a root router')
+    }
+
+    this.routers.set(kRootRouter, router)
+    this.registerRouter(router, [])
+
+    if (router.default) {
+      if (!isProcedure(router.default)) {
+        throw new Error('Root router default must be a procedure')
+      }
+      this.procedures.set(kDefaultProcedure, {
+        procedure: router.default,
+        path: [router],
+      })
+    }
+
+    for (const filter of filters) this.filters.add(filter)
+    for (const middleware of middlewares) this.middlewares.add(middleware)
+    for (const guard of guards) this.guards.add(guard)
+  }
+
+  protected registerRouter(router: AnyRouter, path: AnyRouter[] = []) {
+    for (const route of Object.values(router.routes)) {
+      if (isRouter(route)) {
+        const name = route.contract.name
+        if (!name) throw new Error('Nested routers must have a name')
+        if (this.routers.has(name)) {
+          throw new Error(`Router ${String(name)} already registered`)
+        }
+        this.routers.set(name, route)
+        this.registerRouter(route, [...path, router])
+      } else if (isProcedure(route)) {
+        const name = route.contract.name
+        if (!name) throw new Error('Procedures must have a name')
+        if (this.procedures.has(name)) {
+          throw new Error(`Procedure ${name} already registered`)
+        }
+        this.procedures.set(name, { procedure: route, path: [...path, router] })
+      }
+    }
+  }
+}

package/src/runtime/workers/base.ts

@@ -0,0 +1,68 @@
+import type { Injection } from '@nmtjs/core'
+import { CoreInjectables, provide } from '@nmtjs/core'
+
+import type { BaseRuntimeOptions } from '../core/runtime.ts'
+import type { WorkerType } from '../enums.ts'
+import type { ServerConfig } from '../server/config.ts'
+import { BaseRuntime } from '../core/runtime.ts'
+import * as injectables from '../injectables.ts'
+import { JobManager } from '../jobs/manager.ts'
+import { PubSubManager } from '../pubsub/manager.ts'
+
+export abstract class BaseWorkerRuntime extends BaseRuntime {
+  pubsub: PubSubManager
+  jobManager?: JobManager
+
+  constructor(
+    readonly config: ServerConfig,
+    options: BaseRuntimeOptions,
+    readonly workerType: WorkerType,
+  ) {
+    super(options)
+
+    this.pubsub = new PubSubManager({
+      logger: this.logger,
+      container: this.container,
+    })
+
+    if (this.config.store) {
+      this.jobManager = new JobManager(
+        this.config.store,
+        this.config.jobs ? Array.from(this.config.jobs.jobs.values()) : [],
+      )
+    }
+  }
+
+  async initialize(): Promise<void> {
+    const injections: Injection[] = [
+      provide(CoreInjectables.logger, this.logger),
+      provide(injectables.workerType, this.workerType),
+      provide(injectables.pubSubPublish, this.pubsub.publish.bind(this.pubsub)),
+      provide(
+        injectables.pubSubSubscribe,
+        this.pubsub.subscribe.bind(this.pubsub),
+      ),
+    ]
+
+    if (this.config.store) {
+      injections.push(provide(injectables.storeConfig, this.config.store))
+    }
+
+    if (this.jobManager) {
+      injections.push(
+        provide(injectables.jobManager, this.jobManager.publicInstance),
+      )
+    }
+
+    await this.container.provide(injections)
+    await super.initialize()
+  }
+
+  protected async _initialize(): Promise<void> {
+    await this.jobManager?.initialize()
+  }
+
+  protected async _dispose(): Promise<void> {
+    await this.jobManager?.terminate()
+  }
+}

package/src/runtime/workers/job.ts

@@ -0,0 +1,153 @@
+import type { MessagePort } from 'node:worker_threads'
+
+import { UnrecoverableError } from 'bullmq'
+
+import type { JobWorkerPool } from '../enums.ts'
+import type { StepResultEntry } from '../jobs/runner.ts'
+import type { ServerConfig } from '../server/config.ts'
+import type { ServerPortMessage, ThreadPortMessage } from '../types.ts'
+import { LifecycleHook, WorkerType } from '../enums.ts'
+import { jobWorkerPool } from '../injectables.ts'
+import { ApplicationWorkerJobRunner } from '../jobs/runner.ts'
+import { BaseWorkerRuntime } from './base.ts'
+
+export interface JobWorkerRuntimeOptions {
+  poolName: string
+  port: MessagePort
+}
+
+export class JobWorkerRuntime extends BaseWorkerRuntime {
+  jobRunner!: ApplicationWorkerJobRunner
+
+  constructor(
+    readonly config: ServerConfig,
+    readonly runtimeOptions: JobWorkerRuntimeOptions,
+  ) {
+    super(
+      config,
+      { logger: config.logger, name: `Job Worker ${runtimeOptions.poolName}` },
+      WorkerType.Job,
+    )
+  }
+
+  async start() {
+    await this.initialize()
+    await this.lifecycleHooks.callHook(LifecycleHook.Start)
+  }
+
+  async stop() {
+    await this.lifecycleHooks.callHook(LifecycleHook.Stop)
+    await this.dispose()
+  }
+
+  async initialize(): Promise<void> {
+    // Validate all jobs are complete before accepting work
+    if (this.config.jobs) {
+      for (const job of this.config.jobs.jobs.values()) {
+        if (!job.returnHandler) {
+          throw new Error(
+            `Job "${job.name}" is incomplete. Jobs must call .return() to be finalized before use.`,
+          )
+        }
+      }
+    }
+
+    await this.container.provide(
+      jobWorkerPool,
+      this.runtimeOptions.poolName as JobWorkerPool,
+    )
+    await super.initialize()
+  }
+
+  protected async _initialize(): Promise<void> {
+    await super._initialize()
+
+    this.jobRunner = new ApplicationWorkerJobRunner({
+      logger: this.logger,
+      container: this.container,
+      lifecycleHooks: this.lifecycleHooks,
+    })
+
+    this.runtimeOptions.port.on('message', async (msg: ServerPortMessage) => {
+      if (msg.type === 'task') {
+        const { id, task } = msg.data
+        try {
+          const job = this.config.jobs?.jobs.get(task.jobName)
+          if (!job) {
+            this.runtimeOptions.port.postMessage({
+              type: 'task',
+              data: { id, task: { type: 'job_not_found' } },
+            } satisfies ThreadPortMessage)
+            return
+          }
+
+          using cancellationSignal = this.jobManager!.cancellationSignal(
+            job,
+            task.jobId,
+          )
+          const queue = this.jobManager!.getQueue(job).queue
+          const bullJob = await queue.getJob(task.jobId)
+          if (!bullJob) {
+            throw new UnrecoverableError(
+              `Job ${task.jobId} not found in queue (may have been removed)`,
+            )
+          }
+
+          // Load checkpoint from BullMQ progress for resume support
+          const checkpoint = bullJob.progress as
+            | {
+                stepIndex: number
+                result: Record<string, unknown>
+                stepResults: StepResultEntry[]
+                progress: Record<string, unknown>
+              }
+            | undefined
+
+          const result = await this.jobRunner.runJob(job, task.data, {
+            signal: cancellationSignal,
+            queueJob: bullJob,
+            result: checkpoint?.result,
+            stepResults: checkpoint?.stepResults,
+            currentStepIndex: checkpoint?.stepIndex ?? 0,
+            progress: checkpoint?.progress,
+          })
+          this.runtimeOptions.port.postMessage({
+            type: 'task',
+            data: { id, task: { type: 'success', result } },
+          })
+        } catch (error) {
+          if (error instanceof UnrecoverableError) {
+            this.runtimeOptions.port.postMessage({
+              type: 'task',
+              data: {
+                id,
+                task: { type: 'unrecoverable_error', error: error.message },
+              },
+            } satisfies ThreadPortMessage)
+          } else {
+            this.runtimeOptions.port.postMessage({
+              type: 'task',
+              data: { id, task: { type: 'error', error } },
+            } satisfies ThreadPortMessage)
+          }
+        }
+      }
+    })
+  }
+
+  protected async _dispose(): Promise<void> {
+    this.runtimeOptions.port.removeAllListeners('message')
+    await super._dispose()
+  }
+
+  protected *_dependents() {
+    if (this.config.jobs) {
+      for (const job of this.config.jobs.jobs.values()) {
+        yield job
+        // we explicitly DO NOT WANT to yield steps here, so per-job container
+        // resolves them independently each time — creates more isolation
+        // yield* job.steps
+      }
+    }
+  }
+}