@platformatic/runtime 3.4.1 → 3.5.1

package/lib/worker/controller.js

@@ -0,0 +1,302 @@
+import {
+  ensureLoggableError,
+  FileWatcher,
+  kHandledError,
+  listRecognizedConfigurationFiles,
+  loadConfiguration,
+  loadConfigurationModule
+} from '@platformatic/foundation'
+import debounce from 'debounce'
+import { EventEmitter } from 'node:events'
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { getActiveResourcesInfo } from 'node:process'
+import { workerData } from 'node:worker_threads'
+import { getGlobalDispatcher, setGlobalDispatcher } from 'undici'
+import { ApplicationAlreadyStartedError, RuntimeNotStartedError } from '../errors.js'
+import { getApplicationUrl } from '../utils.js'
+
+function fetchApplicationUrl (application, key) {
+  if (!key.endsWith('_URL') || !application.id) {
+    return null
+  }
+
+  return getApplicationUrl(application.id)
+}
+
+export class Controller extends EventEmitter {
+  #starting
+  #started
+  #listening
+  #watch
+  #fileWatcher
+  #debouncedRestart
+  #context
+  #lastELU
+
+  constructor (
+    appConfig,
+    workerId,
+    telemetryConfig,
+    loggerConfig,
+    serverConfig,
+    metricsConfig,
+    hasManagementApi,
+    watch
+  ) {
+    super()
+    this.appConfig = appConfig
+    this.applicationId = this.appConfig.id
+    this.workerId = workerId
+    this.#watch = watch
+    this.#starting = false
+    this.#started = false
+    this.#listening = false
+    this.capability = null
+    this.#fileWatcher = null
+    this.#lastELU = performance.eventLoopUtilization()
+
+    this.#context = {
+      controller: this,
+      applicationId: this.applicationId,
+      workerId: this.workerId,
+      directory: this.appConfig.path,
+      dependencies: this.appConfig.dependencies,
+      isEntrypoint: this.appConfig.entrypoint,
+      isProduction: this.appConfig.isProduction,
+      telemetryConfig,
+      metricsConfig,
+      loggerConfig,
+      serverConfig,
+      worker: workerData?.worker,
+      hasManagementApi: !!hasManagementApi,
+      fetchApplicationUrl: fetchApplicationUrl.bind(null, appConfig)
+    }
+  }
+
+  getStatus () {
+    if (this.#starting) return 'starting'
+    if (this.#started) return 'started'
+    return 'stopped'
+  }
+
+  async updateContext (context) {
+    this.#context = { ...this.#context, ...context }
+    if (this.capability) {
+      await this.capability.updateContext(context)
+    }
+  }
+
+  // Note: capability's init() is executed within start
+  async init () {
+    try {
+      const appConfig = this.appConfig
+
+      if (appConfig.isProduction && !process.env.NODE_ENV) {
+        process.env.NODE_ENV = 'production'
+      }
+
+      // Before returning the base application, check if there is any file we recognize
+      // and the user just forgot to specify in the configuration.
+      if (!appConfig.config) {
+        const candidate = listRecognizedConfigurationFiles().find(f => existsSync(resolve(appConfig.path, f)))
+
+        if (candidate) {
+          appConfig.config = resolve(appConfig.path, candidate)
+        }
+      }
+
+      if (appConfig.config) {
+        // Parse the configuration file the first time to obtain the schema
+        const unvalidatedConfig = await loadConfiguration(appConfig.config, null, {
+          onMissingEnv: this.#context.fetchApplicationUrl
+        })
+        const pkg = await loadConfigurationModule(appConfig.path, unvalidatedConfig)
+        this.capability = await pkg.create(appConfig.path, appConfig.config, this.#context)
+        // We could not find a configuration file, we use the bundle @platformatic/basic with the runtime to load it
+      } else {
+        const pkg = await loadConfigurationModule(resolve(import.meta.dirname, '../..'), {}, '@platformatic/basic')
+        this.capability = await pkg.create(appConfig.path, {}, this.#context)
+      }
+
+      this.#updateDispatcher()
+    } catch (err) {
+      if (err.validationErrors) {
+        globalThis.platformatic.logger.error(
+          { err: ensureLoggableError(err) },
+          'The application threw a validation error.'
+        )
+
+        throw err
+      } else {
+        this.#logAndThrow(err)
+      }
+    }
+  }
+
+  async start () {
+    if (this.#starting || this.#started) {
+      throw new ApplicationAlreadyStartedError()
+    }
+
+    this.#starting = true
+
+    try {
+      await this.capability.init?.()
+      this.emit('init')
+    } catch (err) {
+      this.#logAndThrow(err)
+    }
+
+    this.emit('starting')
+
+    if (this.capability.status === 'stopped') {
+      return
+    }
+
+    if (this.#watch) {
+      const watchConfig = await this.capability.getWatchConfig()
+
+      if (watchConfig.enabled !== false) {
+        /* c8 ignore next 4 */
+        this.#debouncedRestart = debounce(() => {
+          this.capability.log({ message: 'files changed', level: 'debug' })
+          this.emit('changed')
+        }, 100) // debounce restart for 100ms
+
+        this.#startFileWatching(watchConfig)
+      }
+    }
+
+    const listen = !!this.appConfig.useHttp
+
+    try {
+      await this.capability.start({ listen })
+      this.#listening = listen
+      /* c8 ignore next 5 */
+    } catch (err) {
+      this.capability.log({ message: err.message, level: 'debug' })
+      this.#starting = false
+      throw err
+    }
+
+    this.#started = true
+    this.#starting = false
+    this.emit('started')
+  }
+
+  async stop (force = false, dependents = []) {
+    if (!force && (!this.#started || this.#starting)) {
+      throw new RuntimeNotStartedError()
+    }
+
+    this.emit('stopping')
+    await this.#stopFileWatching()
+    await this.capability.waitForDependentsStop(dependents)
+    await this.capability.stop()
+
+    this.#started = false
+    this.#starting = false
+    this.#listening = false
+    this.emit('stopped')
+  }
+
+  async listen () {
+    // This server is not an entrypoint or already listened in start. Behave as no-op.
+    if (!this.appConfig.entrypoint || this.appConfig.useHttp || this.#listening) {
+      return
+    }
+
+    await this.capability.start({ listen: true })
+  }
+
+  async getMetrics ({ format }) {
+    const dispatcher = getGlobalDispatcher()
+    if (globalThis.platformatic?.onHttpStatsFree && dispatcher?.stats) {
+      for (const url in dispatcher.stats) {
+        const { free, connected, pending, queued, running, size } = dispatcher.stats[url]
+        globalThis.platformatic.onHttpStatsFree(url, free || 0)
+        globalThis.platformatic.onHttpStatsConnected(url, connected || 0)
+        globalThis.platformatic.onHttpStatsPending(url, pending || 0)
+        globalThis.platformatic.onHttpStatsQueued(url, queued || 0)
+        globalThis.platformatic.onHttpStatsRunning(url, running || 0)
+        globalThis.platformatic.onHttpStatsSize(url, size || 0)
+      }
+    }
+    globalThis.platformatic.onActiveResourcesEventLoop(getActiveResourcesInfo().length)
+    return this.capability.getMetrics({ format })
+  }
+
+  async getHealth () {
+    const currentELU = performance.eventLoopUtilization()
+    const elu = performance.eventLoopUtilization(currentELU, this.#lastELU).utilization
+    this.#lastELU = currentELU
+
+    const { heapUsed, heapTotal } = process.memoryUsage()
+
+    return {
+      elu,
+      heapUsed,
+      heapTotal
+    }
+  }
+
+  #startFileWatching (watch) {
+    if (this.#fileWatcher) {
+      return
+    }
+
+    const fileWatcher = new FileWatcher({
+      path: watch.path,
+      /* c8 ignore next 2 */
+      allowToWatch: watch?.allow,
+      watchIgnore: watch?.ignore || []
+    })
+
+    fileWatcher.on('update', this.#debouncedRestart)
+
+    fileWatcher.startWatching()
+    this.capability.log({ message: 'start watching files', level: 'debug' })
+    this.#fileWatcher = fileWatcher
+  }
+
+  async #stopFileWatching () {
+    const watcher = this.#fileWatcher
+
+    if (watcher) {
+      this.capability.log({ message: 'stop watching files', level: 'debug' })
+      await watcher.stopWatching()
+      this.#fileWatcher = null
+    }
+  }
+
+  #logAndThrow (err) {
+    globalThis.platformatic.logger.error(
+      { err: ensureLoggableError(err) },
+      err[kHandledError] ? err.message : 'The application threw an error.'
+    )
+
+    throw err
+  }
+
+  #updateDispatcher () {
+    const telemetryConfig = this.#context.telemetryConfig
+    const telemetryId = telemetryConfig?.applicationName
+
+    const interceptor = dispatch => {
+      return function InterceptedDispatch (opts, handler) {
+        if (telemetryId) {
+          opts.headers = {
+            ...opts.headers,
+            'x-plt-telemetry-id': telemetryId
+          }
+        }
+        return dispatch(opts, handler)
+      }
+    }
+
+    const dispatcher = getGlobalDispatcher().compose(interceptor)
+
+    setGlobalDispatcher(dispatcher)
+  }
+}

package/lib/worker/http-cache.js

@@ -0,0 +1,171 @@
+import { randomUUID } from 'node:crypto'
+import { Readable, Writable } from 'node:stream'
+import { interceptors } from 'undici'
+import { kITC } from './symbols.js'
+
+const kCacheIdHeader = Symbol('cacheIdHeader')
+const CACHE_ID_HEADER = 'x-plt-http-cache-id'
+
+const noop = () => {}
+
+export class RemoteCacheStore {
+  #onRequest
+  #onCacheHit
+  #onCacheMiss
+  #logger
+
+  constructor (opts = {}) {
+    this.#onRequest = opts.onRequest ?? noop
+    this.#onCacheHit = opts.onCacheHit ?? noop
+    this.#onCacheMiss = opts.onCacheMiss ?? noop
+    this.#logger = opts.logger
+  }
+
+  async get (request) {
+    try {
+      this.#onRequest(request)
+    } catch (err) {
+      this.#logger.error(err, 'Error in onRequest http cache hook')
+    }
+
+    const itc = globalThis[kITC]
+    if (!itc) return
+
+    const sanitizedRequest = this.#sanitizeRequest(request)
+
+    const cachedValue = await itc.send('getHttpCacheValue', {
+      request: sanitizedRequest
+    })
+    if (!cachedValue) {
+      try {
+        this.#onCacheMiss(request)
+      } catch (err) {
+        this.#logger.error(err, 'Error in onCacheMiss http cache hook')
+      }
+      return
+    }
+
+    const readable = new Readable({ read () {} })
+    readable.push(cachedValue.payload)
+    readable.push(null)
+
+    try {
+      this.#onCacheHit(request, cachedValue.response)
+    } catch (err) {
+      this.#logger.error(err, 'Error in onCacheHit http cache hook')
+    }
+
+    return {
+      ...cachedValue.response,
+      body: readable
+    }
+  }
+
+  createWriteStream (key, value) {
+    const cacheEntryId = value.headers?.[kCacheIdHeader]
+    if (cacheEntryId) {
+      key = { ...key, id: cacheEntryId }
+      value.headers = { ...value.headers, [CACHE_ID_HEADER]: cacheEntryId }
+    }
+
+    const itc = globalThis[kITC]
+    if (!itc) throw new Error('Cannot write to cache without an ITC instance')
+
+    const acc = []
+
+    key = this.#sanitizeRequest(key)
+
+    return new Writable({
+      write (chunk, encoding, callback) {
+        acc.push(chunk)
+        callback()
+      },
+      final (callback) {
+        let payload
+        if (acc.length > 0 && typeof acc[0] === 'string') {
+          payload = acc.join('')
+        } else {
+          payload = Buffer.concat(acc)
+        }
+        itc
+          .send('setHttpCacheValue', { request: key, response: value, payload })
+          .then(() => callback())
+          .catch(err => callback(err))
+      }
+    })
+  }
+
+  delete (request) {
+    const itc = globalThis[kITC]
+    if (!itc) throw new Error('Cannot delete from cache without an ITC instance')
+
+    request = this.#sanitizeRequest(request)
+    itc.send('deleteHttpCacheValue', { request })
+    // TODO: return a Promise
+  }
+
+  #sanitizeRequest (request) {
+    return {
+      id: request.id,
+      origin: request.origin,
+      method: request.method,
+      path: request.path,
+      headers: request.headers
+    }
+  }
+}
+
+export function httpCacheInterceptor (interceptorOpts) {
+  const originalInterceptor = interceptors.cache(interceptorOpts)
+
+  // AsyncLocalStorage that contains a client http request span
+  // Exists only when the nodejs capability telemetry is enabled
+  const clientSpansAls = globalThis.platformatic.clientSpansAls
+
+  return originalDispatch => {
+    const dispatch = (opts, handler) => {
+      const originOnResponseStart = handler.onResponseStart.bind(handler)
+      handler.onResponseStart = (ac, statusCode, headers, statusMessage) => {
+        // Setting a potentially cache entry id when cache miss happens
+        headers[kCacheIdHeader] = randomUUID()
+        return originOnResponseStart(ac, statusCode, headers, statusMessage)
+      }
+
+      return originalDispatch(opts, handler)
+    }
+
+    const dispatcher = originalInterceptor(dispatch)
+
+    return (opts, handler) => {
+      const originOnResponseStart = handler.onResponseStart.bind(handler)
+      handler.onResponseStart = (ac, statusCode, headers, statusMessage) => {
+        const cacheEntryId = headers[kCacheIdHeader] ?? headers[CACHE_ID_HEADER]
+        const isCacheHit = headers.age !== undefined
+
+        if (cacheEntryId) {
+          // Setting a cache id header on cache hit
+          headers[CACHE_ID_HEADER] = cacheEntryId
+          delete headers[kCacheIdHeader]
+
+          if (clientSpansAls) {
+            try {
+              const { span } = clientSpansAls.getStore()
+              if (span) {
+                span.setAttribute('http.cache.id', cacheEntryId)
+                span.setAttribute('http.cache.hit', isCacheHit.toString())
+              }
+            } catch (err) {
+              interceptorOpts.logger.error(err, 'Error setting cache id on span')
+            }
+          }
+        }
+        return originOnResponseStart(ac, statusCode, headers, statusMessage)
+      }
+
+      if (!clientSpansAls) {
+        return dispatcher(opts, handler)
+      }
+      return clientSpansAls.run({ span: null }, () => dispatcher(opts, handler))
+    }
+  }
+}

package/lib/worker/interceptors.js

@@ -1,17 +1,197 @@
-'use strict'
+import { createTelemetryThreadInterceptorHooks } from '@platformatic/telemetry'
+import { createRequire } from 'node:module'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { parentPort, workerData } from 'node:worker_threads'
+import { Agent, Client, Pool, setGlobalDispatcher } from 'undici'
+import { wire } from 'undici-thread-interceptor'
+import { RemoteCacheStore, httpCacheInterceptor } from './http-cache.js'
+import { kInterceptors } from './symbols.js'
 
-const { pathToFileURL } = require('node:url')
+export async function setDispatcher (runtimeConfig) {
+  const threadDispatcher = createThreadInterceptor(runtimeConfig)
+  const threadInterceptor = threadDispatcher.interceptor
+
+  let cacheInterceptor = null
+  if (runtimeConfig.httpCache) {
+    cacheInterceptor = createHttpCacheInterceptor(runtimeConfig)
+  }
+
+  let userInterceptors = []
+  if (Array.isArray(runtimeConfig.undici?.interceptors)) {
+    const _require = createRequire(join(workerData.dirname, 'package.json'))
+    userInterceptors = await loadInterceptors(_require, runtimeConfig.undici.interceptors)
+  }
+
+  const dispatcherOpts = await getDispatcherOpts(runtimeConfig.undici)
+
+  setGlobalDispatcher(
+    new Agent(dispatcherOpts).compose([threadInterceptor, ...userInterceptors, cacheInterceptor].filter(Boolean))
+  )
+
+  return { threadDispatcher }
+}
+
+export async function updateUndiciInterceptors (undiciConfig) {
+  const updatableInterceptors = globalThis[kInterceptors]
+  if (!updatableInterceptors) return
+
+  if (Array.isArray(undiciConfig?.interceptors)) {
+    for (const interceptorConfig of undiciConfig.interceptors) {
+      const { module, options } = interceptorConfig
+
+      const interceptorCtx = updatableInterceptors[module]
+      if (!interceptorCtx) continue
+
+      const { createInterceptor, updateInterceptor } = interceptorCtx
+      updateInterceptor(createInterceptor(options))
+    }
+  } else {
+    for (const key of ['Agent', 'Pool', 'Client']) {
+      const interceptorConfigs = undiciConfig.interceptors[key]
+      if (!interceptorConfigs) continue
+
+      for (const interceptorConfig of interceptorConfigs) {
+        const { module, options } = interceptorConfig
+
+        const interceptorCtx = updatableInterceptors[key][module]
+        if (!interceptorCtx) continue
+
+        const { createInterceptor, updateInterceptor } = interceptorCtx
+        updateInterceptor(createInterceptor(options))
+      }
+    }
+  }
+}
+
+function createUpdatableInterceptor (originInterceptor) {
+  let originalDispatcher = null
+  let originalDispatch = null
+
+  function updatableInterceptor (dispatch) {
+    originalDispatch = dispatch
+    originalDispatcher = originInterceptor(dispatch)
+
+    return function dispatcher (opts, handler) {
+      return originalDispatcher(opts, handler)
+    }
+  }
+
+  function updateInterceptor (newInterceptor) {
+    originalDispatcher = newInterceptor(originalDispatch)
+  }
+
+  return { updatableInterceptor, updateInterceptor }
+}
+
+async function loadInterceptors (_require, interceptorsConfigs, key) {
+  return Promise.all(
+    interceptorsConfigs.map(async interceptorConfig => {
+      return loadInterceptor(_require, interceptorConfig, key)
+    })
+  )
+}
+
+async function loadInterceptor (_require, interceptorConfig, key) {
+  let updatableInterceptors = globalThis[kInterceptors]
+  if (!updatableInterceptors) {
+    updatableInterceptors = {}
+    globalThis[kInterceptors] = updatableInterceptors
+  }
+
+  const { module, options } = interceptorConfig
 
-async function loadInterceptor (_require, module, options) {
   const url = pathToFileURL(_require.resolve(module))
-  const interceptor = (await import(url)).default
-  return interceptor(options)
+  const createInterceptor = (await import(url)).default
+  const interceptor = createInterceptor(options)
+
+  const { updatableInterceptor, updateInterceptor } = createUpdatableInterceptor(interceptor)
+
+  const interceptorCtx = { createInterceptor, updateInterceptor }
+
+  if (key !== undefined) {
+    if (!updatableInterceptors[key]) {
+      updatableInterceptors[key] = {}
+    }
+    updatableInterceptors[key][module] = interceptorCtx
+  } else {
+    updatableInterceptors[module] = interceptorCtx
+  }
+
+  return updatableInterceptor
+}
+
+async function getDispatcherOpts (undiciConfig) {
+  const dispatcherOpts = { ...undiciConfig }
+
+  const interceptorsConfigs = undiciConfig?.interceptors
+  if (!interceptorsConfigs || Array.isArray(interceptorsConfigs)) {
+    return dispatcherOpts
+  }
+
+  const _require = createRequire(join(workerData.dirname, 'package.json'))
+
+  const clientInterceptors = []
+  const poolInterceptors = []
+
+  for (const key of ['Agent', 'Pool', 'Client']) {
+    const interceptorConfig = undiciConfig.interceptors[key]
+    if (!interceptorConfig) continue
+
+    const interceptors = await loadInterceptors(_require, interceptorConfig, key)
+    if (key === 'Agent') {
+      clientInterceptors.push(...interceptors)
+      poolInterceptors.push(...interceptors)
+    }
+    if (key === 'Pool') {
+      poolInterceptors.push(...interceptors)
+    }
+    if (key === 'Client') {
+      clientInterceptors.push(...interceptors)
+    }
+  }
+
+  dispatcherOpts.factory = (origin, opts) => {
+    return opts && opts.connections === 1
+      ? new Client(origin, opts).compose(clientInterceptors)
+      : new Pool(origin, opts).compose(poolInterceptors)
+  }
+
+  return dispatcherOpts
 }
 
-function loadInterceptors (_require, interceptors) {
-  return Promise.all(interceptors.map(async ({ module, options }) => {
-    return loadInterceptor(_require, module, options)
-  }))
+function createThreadInterceptor (runtimeConfig) {
+  const telemetry = runtimeConfig.telemetry
+
+  const telemetryHooks = telemetry ? createTelemetryThreadInterceptorHooks() : {}
+
+  const threadDispatcher = wire({
+    // Specifying the domain is critical to avoid flooding the DNS
+    // with requests for a domain that's never going to exist.
+    domain: '.plt.local',
+    port: parentPort,
+    timeout: runtimeConfig.applicationTimeout,
+    ...telemetryHooks
+  })
+  return threadDispatcher
 }
 
-module.exports = loadInterceptors
+function createHttpCacheInterceptor (runtimeConfig) {
+  const cacheInterceptor = httpCacheInterceptor({
+    store: new RemoteCacheStore({
+      onRequest: opts => {
+        globalThis.platformatic?.onHttpCacheRequest?.(opts)
+      },
+      onCacheHit: opts => {
+        globalThis.platformatic?.onHttpCacheHit?.(opts)
+      },
+      onCacheMiss: opts => {
+        globalThis.platformatic?.onHttpCacheMiss?.(opts)
+      },
+      logger: globalThis.platformatic.logger
+    }),
+    methods: runtimeConfig.httpCache.methods ?? ['GET', 'HEAD'],
+    logger: globalThis.platformatic.logger
+  })
+  return cacheInterceptor
+}