@platformatic/runtime 0.26.0

package/fixtures/serviceAppThrowsOnStart/platformatic.service.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://platformatic.dev/schemas/v0.20.0/service",
+  "server": {
+    "hostname": "127.0.0.1",
+    "port": 0
+  },
+  "plugins": {
+    "hotReload": true,
+    "paths": [
+      "plugin.js"
+    ]
+  }
+}

package/fixtures/serviceAppThrowsOnStart/plugin.js

@@ -0,0 +1,6 @@
+'use strict'
+
+/** @param {import('fastify').FastifyInstance} app */
+module.exports = async function (app) {
+  throw new Error('boom')
+}

package/help/help.txt

@@ -0,0 +1,5 @@
+Available commands:
+
+* `help` - show this help message.
+* `help <command>` - shows more information about a command.
+* `start` - start the application.

package/help/start.txt

@@ -0,0 +1,5 @@
+Start the Platformatic Runtime with the following command:
+
+``` bash
+ $ platformatic runtime start
+```

package/index.d.ts

@@ -0,0 +1,13 @@
+import { InjectOptions, LightMyRequestResponse } from 'fastify'
+
+export type pltRuntimeBuildServer = {
+  address: string
+  port: number
+  restart: () => Promise<void>
+  stop: () => Promise<void>
+  inject: (opts: InjectOptions | string) => Promise<LightMyRequestResponse>
+}
+
+declare module '@platformatic/runtime' {
+  export function buildServer(opts: object): Promise<pltRuntimeBuildServer>
+}

package/index.js

@@ -0,0 +1,33 @@
+'use strict'
+const ConfigManager = require('@platformatic/config')
+const { platformaticRuntime } = require('./lib/config')
+const { start, startWithConfig } = require('./lib/start')
+
+async function buildServer (options = {}) {
+  if (!options.configManager) {
+    // Instantiate a new config manager from the current options.
+    const cm = new ConfigManager({
+      ...platformaticRuntime.configManagerConfig,
+      source: options
+    })
+    await cm.parseAndValidate()
+
+    if (typeof options === 'string') {
+      options = { configManager: cm }
+    } else {
+      options.configManager = cm
+    }
+  }
+
+  // The transformConfig() function can't be sent between threads.
+  delete options.configManager._transformConfig
+
+  return startWithConfig(options.configManager)
+}
+
+module.exports = {
+  buildServer,
+  platformaticRuntime,
+  schema: platformaticRuntime.schema,
+  start
+}

package/index.test-d.ts

@@ -0,0 +1,18 @@
+import { expectError, expectType } from 'tsd';
+import { LightMyRequestResponse } from 'fastify';
+import { pltRuntimeBuildServer } from '.';
+
+const server: pltRuntimeBuildServer = {
+  address: 'localhost',
+  port: 3000,
+  restart: async () => {},
+  stop: async () => {},
+  inject: async () => ({} as LightMyRequestResponse),
+};
+
+expectType<pltRuntimeBuildServer>(server);
+expectError<pltRuntimeBuildServer>({...server, address: 42 });
+expectError<pltRuntimeBuildServer>({...server, port: 'WRONG' });
+expectError<pltRuntimeBuildServer>({...server, restart: 'WRONG' });
+expectError<pltRuntimeBuildServer>({...server, stop: 'WRONG' });
+expectError<pltRuntimeBuildServer>({...server, inject: 'WRONG' });

package/lib/app.js

@@ -0,0 +1,261 @@
+'use strict'
+const { once } = require('node:events')
+const { dirname } = require('node:path')
+const {
+  addLoggerToTheConfig
+} = require('@platformatic/service')
+const {
+  buildServer,
+  loadConfig
+} = require('@platformatic/start')
+const { FileWatcher } = require('@platformatic/utils')
+
+class PlatformaticApp {
+  #hotReload
+  #loaderPort
+  #restarting
+  #started
+  #originalWatch
+
+  constructor (appConfig, loaderPort) {
+    this.appConfig = appConfig
+    this.config = null
+    this.#hotReload = false
+    this.#loaderPort = loaderPort
+    this.#restarting = false
+    this.server = null
+    this.#started = false
+    this.#originalWatch = null
+  }
+
+  async restart (force) {
+    if (this.#restarting) {
+      return
+    }
+
+    if (!this.#hotReload && !force) {
+      return
+    }
+
+    this.#restarting = true
+    await this.stop()
+
+    /* c8 ignore next 4 - tests may not pass in a MessagePort. */
+    if (this.#loaderPort) {
+      this.#loaderPort.postMessage('plt:clear-cache')
+      await once(this.#loaderPort, 'message')
+    }
+
+    await this.start()
+    this.#restarting = false
+  }
+
+  async start () {
+    if (this.#started) {
+      throw new Error('application is already started')
+    }
+
+    await this.#initializeConfig()
+    const { configManager } = this.config
+    const config = configManager.current
+
+    this.#originalWatch = config.watch
+    config.watch = false
+
+    try {
+      // If this is a restart, have the fastify server restart itself. If this
+      // is not a restart, then create a new server.
+      if (this.#restarting) {
+        await this.server.restart()
+      } else {
+        this.server = await buildServer({
+          ...config,
+          configManager
+        })
+      }
+    } catch (err) {
+      this.#logAndExit(err)
+    }
+
+    this.server.platformatic.configManager = configManager
+    this.server.platformatic.config = config
+
+    if (config.plugins !== undefined && this.#originalWatch !== false) {
+      this.#startFileWatching()
+    }
+
+    this.#started = true
+
+    if (this.appConfig.entrypoint && !this.#restarting) {
+      try {
+        await this.server.start()
+        /* c8 ignore next 5 */
+      } catch (err) {
+        this.server.log.error({ err })
+        process.exit(1)
+      }
+    }
+  }
+
+  async stop () {
+    if (!this.#started) {
+      throw new Error('application has not been started')
+    }
+
+    if (!this.#restarting) {
+      await this.server.close()
+    }
+
+    await this.#stopFileWatching()
+    this.#started = false
+  }
+
+  async handleProcessLevelEvent ({ msg, signal, err }) {
+    if (msg === 'plt:start') {
+      await this.start()
+      return
+    }
+
+    if (!this.server) {
+      return false
+    }
+
+    if (msg === 'plt:restart') {
+      await this.restart(true)
+      return
+    }
+
+    if (msg === 'plt:stop') {
+      await this.stop()
+      return
+    }
+
+    if (signal === 'SIGUSR2') {
+      this.server.log.info('reloading configuration')
+      await this.restart()
+      return false
+    }
+
+    if (err) {
+      this.server.log.error({
+        err: {
+          message: err?.message,
+          stack: err?.stack
+        }
+      }, 'exiting')
+    } else if (signal) {
+      this.server.log.info({ signal }, 'received signal')
+    }
+
+    if (this.#started) {
+      await this.stop()
+    }
+  }
+
+  async #initializeConfig () {
+    const appConfig = this.appConfig
+
+    this.config = await loadConfig({}, ['-c', appConfig.config], null, {
+      watch: true,
+      onMissingEnv (key) {
+        return appConfig.localServiceEnvVars.get(key)
+      }
+    })
+    const { args, configManager } = this.config
+
+    if (appConfig._configOverrides instanceof Map) {
+      try {
+        appConfig._configOverrides.forEach((value, key) => {
+          if (typeof key !== 'string') {
+            throw new Error('config path must be a string.')
+          }
+
+          const parts = key.split('.')
+          let next = configManager.current
+          let obj
+
+          for (let i = 0; next !== undefined && i < parts.length; ++i) {
+            obj = next
+            next = obj[parts[i]]
+          }
+
+          if (next !== undefined) {
+            obj[parts.at(-1)] = value
+          }
+        })
+      } catch (err) {
+        configManager.stopWatching()
+        throw err
+      }
+    }
+
+    // Set the logger if not present (and the config supports it).
+    if (configManager.current.server) {
+      addLoggerToTheConfig(configManager.current)
+      configManager.current.server.logger.name = this.appConfig.id
+    }
+
+    this.#hotReload = args.hotReload && this.appConfig.hotReload
+
+    if (configManager.current.plugins) {
+      if (this.#hotReload) {
+        this.#hotReload = configManager.current.plugins.hotReload
+      }
+
+      configManager.current.plugins.hotReload = false
+    }
+
+    configManager.on('update', async (newConfig) => {
+      /* c8 ignore next 4 */
+      this.server.platformatic.config = newConfig
+      this.server.log.debug('config changed')
+      this.server.log.trace({ newConfig }, 'new config')
+      await this.restart()
+    })
+
+    configManager.on('error', (err) => {
+      /* c8 ignore next */
+      this.server.log.error({ err }, 'error reloading the configuration')
+    })
+  }
+
+  #startFileWatching () {
+    const server = this.server
+    const { configManager } = server.platformatic
+    const fileWatcher = new FileWatcher({
+      path: dirname(configManager.fullPath),
+      /* c8 ignore next 2 */
+      allowToWatch: this.#originalWatch?.allow,
+      watchIgnore: this.#originalWatch?.ignore
+    })
+
+    fileWatcher.on('update', async () => {
+      this.server.log.debug('files changed')
+      this.restart()
+    })
+
+    fileWatcher.startWatching()
+    server.log.debug('start watching files')
+    server.platformatic.fileWatcher = fileWatcher
+    server.platformatic.configManager.startWatching()
+  }
+
+  async #stopFileWatching () {
+    const watcher = this.server.platformatic.fileWatcher
+
+    if (watcher) {
+      await watcher.stopWatching()
+      this.server.log.debug('stop watching files')
+      this.server.platformatic.fileWatcher = undefined
+      this.server.platformatic.configManager.stopWatching()
+    }
+  }
+
+  #logAndExit (err) {
+    this.config?.configManager?.stopWatching()
+    console.error(err)
+    process.exit(1)
+  }
+}
+
+module.exports = { PlatformaticApp }

package/lib/config.js

@@ -0,0 +1,209 @@
+'use strict'
+const { readFile, readdir } = require('node:fs/promises')
+const { join, resolve: pathResolve } = require('node:path')
+const Topo = require('@hapi/topo')
+const ConfigManager = require('@platformatic/config')
+const { schema } = require('./schema')
+
+async function _transformConfig (configManager) {
+  const config = configManager.current
+  const services = config.services ?? []
+
+  if (config.autoload) {
+    const { path, exclude = [], mappings = {} } = config.autoload
+    const entries = await readdir(path, { withFileTypes: true })
+
+    for (let i = 0; i < entries.length; ++i) {
+      const entry = entries[i]
+
+      if (exclude.includes(entry.name) || !entry.isDirectory()) {
+        continue
+      }
+
+      const mapping = mappings[entry.name] ?? {}
+      const id = mapping.id ?? entry.name
+      const entryPath = join(path, entry.name)
+      const configFilename = mapping.config ?? await ConfigManager.findConfigFile(entryPath)
+
+      if (typeof configFilename !== 'string') {
+        throw new Error(`no config file found for service '${id}'`)
+      }
+
+      const config = join(entryPath, configFilename)
+
+      services.push({ id, config, path: entryPath })
+    }
+  }
+
+  configManager.current.allowCycles = !!configManager.current.allowCycles
+  configManager.current.serviceMap = new Map()
+
+  let hasValidEntrypoint = false
+
+  for (let i = 0; i < services.length; ++i) {
+    const service = services[i]
+
+    service.config = pathResolve(service.path, service.config)
+    service.entrypoint = service.id === config.entrypoint
+    service.hotReload = !!config.hotReload
+    service.dependencies = []
+    service.dependents = []
+    service.localServiceEnvVars = new Map()
+    service.localUrl = `http://${service.id}.plt.local`
+
+    if (service.entrypoint) {
+      hasValidEntrypoint = true
+    }
+
+    configManager.current.serviceMap.set(service.id, service)
+  }
+
+  if (!hasValidEntrypoint) {
+    throw new Error(`invalid entrypoint: '${config.entrypoint}' does not exist`)
+  }
+
+  configManager.current.services = services
+  await parseClientsAndComposer(configManager)
+
+  if (!configManager.current.allowCycles) {
+    topologicalSort(configManager)
+  }
+}
+
+async function parseClientsAndComposer (configManager) {
+  for (let i = 0; i < configManager.current.services.length; ++i) {
+    const service = configManager.current.services[i]
+    const cm = new ConfigManager({ source: service.config })
+    const configString = await cm.load()
+    const parsed = cm._parser(configString)
+
+    if (Array.isArray(parsed.composer?.services)) {
+      for (let i = 0; i < parsed.composer.services.length; ++i) {
+        const dep = parsed.composer.services[i]
+        /* c8 ignore next 4 - why c8? */
+        const clientName = dep.id ?? ''
+        const dependency = configManager.current.serviceMap.get(clientName)
+
+        if (dependency === undefined) {
+          /* c8 ignore next 2 */
+          throw new Error(`service '${service.id}' has unknown dependency: '${clientName}'`)
+        }
+
+        dependency.dependents.push(service.id)
+
+        if (dep.origin) {
+          try {
+            await cm.replaceEnv(dep.origin)
+            /* c8 ignore next 4 */
+          } catch (err) {
+            if (err.name !== 'MissingValueError') {
+              throw err
+            }
+
+            if (dep.origin === `{${err.key}}`) {
+              service.localServiceEnvVars.set(err.key, `${clientName}.plt.local`)
+            }
+          }
+        }
+
+        service.dependencies.push({
+          id: clientName,
+          url: `http://${clientName}.plt.local`,
+          local: true
+        })
+      }
+    }
+
+    if (Array.isArray(parsed.clients)) {
+      const promises = parsed.clients.map((client) => {
+        // eslint-disable-next-line no-async-promise-executor
+        return new Promise(async (resolve, reject) => {
+          let clientUrl
+          let missingKey
+
+          try {
+            clientUrl = await cm.replaceEnv(client.url)
+            /* c8 ignore next 2 - unclear why c8 is unhappy here */
+          } catch (err) {
+            if (err.name !== 'MissingValueError') {
+              /* c8 ignore next 3 */
+              reject(err)
+              return
+            }
+
+            missingKey = err.key
+          }
+
+          const isLocal = missingKey && client.url === `{${missingKey}}`
+          const clientAbsolutePath = pathResolve(service.path, client.path)
+          const clientPackageJson = join(clientAbsolutePath, 'package.json')
+          const clientMetadata = JSON.parse(await readFile(clientPackageJson, 'utf8'))
+          /* c8 ignore next 20 - unclear why c8 is unhappy for nearly 20 lines here */
+          const clientName = clientMetadata.name ?? ''
+
+          if (clientUrl === undefined) {
+            // Combine the service name with the client name to avoid collisions
+            // if two or more services have a client with the same name pointing
+            // to different services.
+            clientUrl = isLocal ? `http://${clientName}.plt.local` : client.url
+          }
+
+          service.dependencies.push({
+            id: clientName,
+            url: clientUrl,
+            local: isLocal
+          })
+
+          const dependency = configManager.current.serviceMap.get(clientName)
+
+          if (dependency === undefined) {
+            /* c8 ignore next 3 */
+            reject(new Error(`service '${service.id}' has unknown dependency: '${clientName}'`))
+            return
+          }
+
+          dependency.dependents.push(service.id)
+
+          if (isLocal) {
+            service.localServiceEnvVars.set(missingKey, clientUrl)
+          }
+
+          resolve()
+        })
+      })
+
+      await Promise.all(promises)
+    }
+  }
+}
+
+function topologicalSort (configManager) {
+  const { services } = configManager.current
+  const topo = new Topo.Sorter()
+
+  for (let i = 0; i < services.length; ++i) {
+    const service = services[i]
+    const dependencyIds = service.dependencies.map(dep => dep.id)
+
+    topo.add(service, { group: service.id, after: dependencyIds, manual: true })
+  }
+
+  configManager.current.services = topo.sort()
+}
+
+async function platformaticRuntime () {
+  // No-op. Here for consistency with other app types.
+}
+
+platformaticRuntime[Symbol.for('skip-override')] = true
+platformaticRuntime.schema = schema
+platformaticRuntime.configType = 'runtime'
+platformaticRuntime.configManagerConfig = {
+  schema,
+  allowToWatch: ['.env'],
+  async transformConfig () {
+    await _transformConfig(this)
+  }
+}
+
+module.exports = { platformaticRuntime }

package/lib/loader.mjs

@@ -0,0 +1,101 @@
+import { createRequire, isBuiltin } from 'node:module'
+import { dirname, isAbsolute, resolve as pathResolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+const require = createRequire(import.meta.url)
+const thisFile = fileURLToPath(import.meta.url)
+const isWindows = process.platform === 'win32'
+let timestamp = process.hrtime.bigint()
+let port
+
+function bustEsmCache () {
+  timestamp = process.hrtime.bigint()
+}
+
+function clearCjsCache () {
+  // This evicts all of the modules from the require() cache.
+  // Note: This does not clean up children references to the deleted module.
+  // It's likely not a big deal for most cases, but it is a leak. The child
+  // references can be cleaned up, but it is expensive and involves walking
+  // the entire require() cache. See the DEP0144 documentation for how to do
+  // it.
+  Object.keys(require.cache).forEach((key) => {
+    delete require.cache[key]
+  })
+}
+
+function isRelativePath (p) {
+  // This function is extracted from Node core, so it should work.
+  return p.charAt(0) === '.' &&
+    /* c8 ignore next 9 */
+    (
+      p.length === 1 ||
+      p.charAt(1) === '/' ||
+      (isWindows && p.charAt(1) === '\\') ||
+      (p.charAt(1) === '.' && ((
+        p.length === 2 ||
+        p.charAt(2) === '/') ||
+        (isWindows && p.charAt(2) === '\\')))
+    )
+}
+
+function specifierToPath (specifier, referencingModuleId) {
+  // Convert the specifier into an absolute path if possible. If the specifier
+  // cannot be converted to a path (for example for a core module), then return
+  // null.
+  try {
+    const url = new URL(specifier)
+
+    if (url.protocol === 'file:') {
+      specifier = url.pathname
+    } else {
+      return null
+    }
+  } catch {
+    // Ignore error.
+  }
+
+  if (isBuiltin(specifier)) {
+    return null
+  }
+
+  if (isAbsolute(specifier)) {
+    return specifier
+  }
+
+  /* c8 ignore next 3 */
+  if (!referencingModuleId) {
+    throw new Error(`cannot map '${specifier}' to an absolute path`)
+  }
+
+  if (isRelativePath(specifier)) {
+    return pathResolve(dirname(fileURLToPath(referencingModuleId)), specifier)
+  } else {
+    // The specifier is something in node_modules/.
+    const req = createRequire(referencingModuleId)
+
+    return req.resolve(specifier)
+  }
+}
+
+export async function resolve (specifier, context, nextResolve) {
+  const path = specifierToPath(specifier, context.parentURL)
+
+  // If the specifier could not be mapped to a file, or the path is this file,
+  // then don't do anything.
+  if (typeof path !== 'string' || path === thisFile) {
+    return nextResolve(specifier, context)
+  }
+
+  return nextResolve(`${path}?ts=${timestamp}`, context)
+}
+
+export function globalPreload (context) {
+  port = context.port
+  port.on('message', () => {
+    bustEsmCache()
+    clearCjsCache()
+    port.postMessage('plt:cache-cleared')
+  })
+
+  return 'globalThis.LOADER_PORT = port;'
+}