@tetherto/mdk-gateway 0.0.0 → 0.12.1

package/workers/http.node.wrk.js

@@ -0,0 +1,175 @@
+'use strict'
+
+const crypto = require('crypto')
+const fs = require('fs')
+const path = require('path')
+const async = require('async')
+const TetherWrkBase = require('@tetherto/tether-wrk-base/workers/base.wrk.tether')
+const createLogger = require('debug')
+const debug = createLogger('store:aggr')
+const { createRuntimeClient, getOrCreateSeed, resolvePluginDir } = require('@tetherto/mdk-app-runtime')
+const { loadPlugin } = require('@tetherto/mdk-app-runtime/lib/plugin-loader')
+const { buildFastifyRoutes, errorResponse, resolveAppTimeout } = require('./lib/plugin-adapter')
+const { fastifyLoggerOptions, gatewayLogger } = require('./lib/logger')
+const { resolveSecurityOptions, buildHostAllowlist, createHostCheck } = require('./lib/security')
+const { resolveStoreDir } = require('./lib/utils')
+
+// Publishes the key app runtimes allow-list. The directory is private to this
+// user and the file is not group/other-writable (runtimes refuse one that is),
+// and it is replaced atomically so a runtime never reads half a key.
+function writeGatewayKeyFile (file, key) {
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 })
+  const tmp = `${file}.${crypto.randomBytes(8).toString('hex')}.tmp`
+  try {
+    fs.writeFileSync(tmp, key, { mode: 0o644, flag: 'wx' })
+    fs.chmodSync(tmp, 0o644) // the umask may have narrowed it; never widened past 0o644
+    fs.renameSync(tmp, file)
+  } catch (err) {
+    try { fs.unlinkSync(tmp) } catch {}
+    throw err
+  }
+}
+
+class WrkServerHttp extends TetherWrkBase {
+  constructor (conf, ctx) {
+    super(conf, ctx)
+
+    if (!ctx.port) {
+      throw new Error('ERR_HTTP_PORT_INVALID')
+    }
+
+    this.storeDir = 'http'
+    this.prefix = `${this.wtype}-${ctx.port}`
+    this.queuedRequests = new Map()
+
+    this.init()
+    this.start()
+  }
+
+  init () {
+    super.init()
+
+    const storeFac = (this.conf.init?.facilities || []).find(([, mod, name]) => mod === '@tetherto/hp-svc-facs-store' && name === 's0')
+    if (storeFac) storeFac[4] = { ...storeFac[4], storeDir: resolveStoreDir(storeFac[4].storeDir, this.ctx) }
+
+    // Validated up front so a bad option fails the boot, not the first request.
+    this._security = resolveSecurityOptions(this.conf, this.ctx)
+    resolveAppTimeout(this.conf)
+
+    this.setInitFacs([
+      ['fac', '@bitfinex/bfx-facs-lru', '10s', '10s', { max: 10000, maxAge: 10000 }],
+      ['fac', '@bitfinex/bfx-facs-lru', '15s', '15s', { max: 10000, maxAge: 15000 }],
+      ['fac', '@bitfinex/bfx-facs-lru', '30s', '30s', { max: 10000, maxAge: 30000 }],
+      ['fac', '@bitfinex/bfx-facs-lru', '1m', '1m', { max: 10000, maxAge: 60000 }],
+      ['fac', '@bitfinex/bfx-facs-lru', '15m', '15m', { max: 10000, maxAge: 60000 * 15 }],
+      ['fac', '@tetherto/svc-facs-httpd', 'h0', 'h0', {
+        // Static serving is opt-in: only when common.json sets staticRootPath.
+        staticRootPath: this.conf.staticRootPath,
+        staticOn404File: 'index.html',
+        port: this.ctx.port,
+        logger: fastifyLoggerOptions(this.conf),
+        // No GET /echo: the gateway serves only what its plugins and caller declare.
+        addDefaultRoutes: false,
+        trustProxy: this._security.trustProxy,
+        bodyLimit: this._security.bodyLimit
+      }, 0]
+    ])
+
+    // ctx.apps (`{ name, appDir, keyFile, mount? }`) is the complete inventory
+    // of a gateway's app routes. Each app runs in its own runtime process: only
+    // its route table is read here, and every request is forwarded over HRPC.
+    this._apps = (this.ctx.apps || []).map(app => ({
+      ...app,
+      routes: loadPlugin(resolvePluginDir(app.appDir), undefined, { handlers: false }).routes
+    }))
+    this._runtimeClient = null
+  }
+
+  debugGeneric (msg) {
+    debug(`[HTTP/${this.ctx.shard}]`, ...arguments)
+  }
+
+  _start (cb) {
+    async.series([
+      next => { super._start(next) },
+      async () => {
+        await this.net_r0.startRpcServer()
+
+        const httpd = this.httpd_h0
+        const security = this._security
+        const log = gatewayLogger(this.conf)
+
+        // Registered before any route so their onRoute/onRequest hooks cover
+        // every plugin and additional route.
+        if (security.helmet) httpd.addPlugin([require('@fastify/helmet'), security.helmet])
+        else log.warn('security headers (helmet) are disabled')
+        if (security.rateLimit) httpd.addPlugin([require('@fastify/rate-limit'), security.rateLimit])
+        else log.warn('rate limiting is disabled')
+
+        const hostAllowlist = buildHostAllowlist(security.allowedHosts, {
+          port: String(this.ctx.port),
+          host: httpd.opts.host || httpd.conf?.host
+        })
+        if (hostAllowlist) httpd.addHook('onRequest', createHostCheck(hostAllowlist))
+        else log.warn('allowedHosts contains "*": the Host check is off, so DNS rebinding is not blocked')
+
+        this.ctx.additionalRoutes?.forEach(r => {
+          httpd.addRoute(r)
+        })
+
+        if (this._apps.length || this.ctx.gatewayKeyFile) {
+          // One stable key, across restarts, for every app runtime to allow-list.
+          const seed = getOrCreateSeed(path.join(this.ctx.root, 'identity', 'seedRuntimeClient'))
+          this._runtimeClient = createRuntimeClient({ seed, bootstrap: this.ctx.kernelBootstrap })
+          await this._runtimeClient.connect()
+        }
+
+        for (const app of this._apps) {
+          buildFastifyRoutes(app, this._runtimeClient, this, { authVerifier: security.authVerifier }).forEach(r => {
+            httpd.addRoute(r)
+          })
+        }
+
+        if (!security.authVerifier) {
+          const closed = this._apps.flatMap(a => a.routes.filter(r => r.auth === true).map(r => r.id))
+          if (closed.length) log.warn(`no authVerifier configured: ${closed.length} auth: true route(s) answer 401 (${closed.join(', ')})`)
+        }
+
+        httpd.addErrorHandler((err, request, reply) => {
+          const body = errorResponse(err, request.log)
+          reply.status(body.statusCode).send(body)
+        })
+
+        await httpd.startServer()
+
+        // The net facility's DHT client key; startGateway publishes it to the
+        // trusted-keys dir as gateway.pub. App routes use appClientKey below.
+        this.status.rpcClientKey = this.net_r0.dht.defaultKeyPair.publicKey.toString('hex')
+
+        // The key app runtimes allow-list (their allowedKeyFiles), published
+        // once the listener is up.
+        if (this._runtimeClient) {
+          this.status.appClientKey = this._runtimeClient.publicKey.toString('hex')
+          if (this.ctx.gatewayKeyFile) {
+            writeGatewayKeyFile(this.ctx.gatewayKeyFile, this.status.appClientKey)
+          }
+        }
+        this.saveStatus()
+      }
+    ], cb)
+  }
+
+  _stop (cb) {
+    async.series([
+      next => { super._stop(next) },
+      async () => {
+        const client = this._runtimeClient
+        this._runtimeClient = null
+        if (client) await client.close()
+      }
+    ], cb)
+  }
+}
+
+module.exports = WrkServerHttp
+module.exports.writeGatewayKeyFile = writeGatewayKeyFile

package/workers/lib/constants.js

@@ -0,0 +1,7 @@
+'use strict'
+
+const RPC_TIMEOUT = 15000
+
+module.exports = {
+  RPC_TIMEOUT
+}

package/workers/lib/logger.js

@@ -0,0 +1,70 @@
+'use strict'
+
+const pino = require('pino')
+
+// Everything the gateway prints — Fastify's request lines and every plugin's
+// logger — goes through one destination, so a plugin failure is formatted and
+// ordered like the rest of the log instead of arriving as a bare console line.
+
+let destination = null
+
+function _destination () {
+  if (destination) return destination
+
+  // Human-readable in a terminal; NDJSON when stdout is piped, which is what
+  // Docker, systemd and log shippers expect to parse.
+  destination = process.stdout.isTTY
+    ? require('pino-pretty')({
+      colorize: true,
+      translateTime: 'HH:MM:ss',
+      ignore: 'pid,hostname',
+      singleLine: true
+    })
+    : pino.destination(1)
+
+  return destination
+}
+
+// `debug: 0` in the gateway's common.json is the default, so debug lines are
+// opt-in the same way they are for the other facilities.
+function _level (conf) {
+  return conf?.debug ? 'debug' : 'info'
+}
+
+// Fastify announces every address it binds, and logs an "incoming request" line
+// paired with each "request completed". The CLI already prints the gateway URL,
+// and one line per request is what an operator can actually read.
+const hooks = {
+  logMethod (args, method) {
+    const msg = typeof args[0] === 'string' ? args[0] : typeof args[1] === 'string' ? args[1] : ''
+    if (msg.startsWith('Server listening at') || msg === 'incoming request') return
+    return method.apply(this, args)
+  }
+}
+
+function fastifyLoggerOptions (conf) {
+  return { level: _level(conf), stream: _destination(), hooks }
+}
+
+let root = null
+
+/**
+ * The logger a plugin sees as `logger` on its ambient context: pino's
+ * error/warn/info/debug/trace/fatal plus child(), tagged with the plugin name so
+ * a line names who wrote it.
+ */
+function pluginLogger (name, conf) {
+  if (!root) root = pino({ level: _level(conf) }, _destination())
+  return root.child({ name })
+}
+
+/**
+ * The same logger for the few things the gateway itself has to tell an operator
+ * — a plugin's `onReady` callback throwing, say. Tagged like a plugin's so the
+ * line names its source, and on the one stream, so it is ordered with the rest.
+ */
+function gatewayLogger (conf) {
+  return pluginLogger('gateway', conf)
+}
+
+module.exports = { fastifyLoggerOptions, pluginLogger, gatewayLogger }

package/workers/lib/plugin-adapter.js

@@ -0,0 +1,189 @@
+'use strict'
+
+const crypto = require('crypto')
+const fs = require('fs')
+const { STATUS_CODES } = require('http')
+const { pipeToResponse } = require('@tetherto/mdk-app-runtime')
+const { cachedRoute } = require('./server/lib/cachedRoute')
+const { send200 } = require('./server/lib/send200')
+const { createAuthHook, canOverwriteCache } = require('./security')
+
+// Only ERR_* codes and Fastify's own 4xx errors (validation, content type,
+// body size) describe the request; any other message can carry internals, so
+// the client gets the status text and the log gets the error.
+function errorResponse (err, log) {
+  const statusCode = Number.isInteger(err.statusCode) && err.statusCode >= 400 ? err.statusCode : 400
+  const error = STATUS_CODES[statusCode] || 'Bad Request'
+  const isSafe = /^ERR_/.test(err.message) || (/^FST_/.test(err.code) && statusCode < 500)
+  if (!isSafe && !err.remote) log?.error(err)
+  return { statusCode, error, message: isSafe ? err.message : error }
+}
+
+function _extractCacheKeyParts (fields, req) {
+  return fields.map(field => {
+    const parts = field.split('.')
+    return parts.reduce((obj, key) => (obj != null ? obj[key] : undefined), req)
+  })
+}
+
+// JSON with object keys sorted, so the same identity always hashes the same
+// whatever order the verifier built it in.
+function _stableStringify (value) {
+  if (Array.isArray(value)) return `[${value.map(v => _stableStringify(v ?? null)).join(',')}]`
+  if (value && typeof value === 'object' && typeof value.toJSON !== 'function') {
+    return `{${Object.keys(value).sort().filter(k => value[k] !== undefined).map(k => `${JSON.stringify(k)}:${_stableStringify(value[k])}`).join(',')}}`
+  }
+  return JSON.stringify(value) ?? 'null'
+}
+
+// A cache key component for the verified caller of an `auth: true` route, so
+// two identities never share a cached response or an in-flight call.
+function _identityCacheKey (req) {
+  return 'id:' + crypto.createHash('sha256').update(_stableStringify(req._info || {})).digest('hex')
+}
+
+// Bounds a unary call, and the wait for a stream route's response head, so a
+// hung controller cannot hold the HTTP request open forever (common.json `appTimeoutMs`).
+const APP_TIMEOUT_MS = 60000
+
+// A malformed value must fail the boot: one that is not a positive number would
+// silently drop the bound. Digit strings are accepted, as for bodyLimit.
+function resolveAppTimeout (conf = {}) {
+  let ms = conf.appTimeoutMs
+  if (ms === undefined || ms === null) return APP_TIMEOUT_MS
+  if (typeof ms === 'string' && /^\d+$/.test(ms)) ms = Number(ms)
+  if (!Number.isInteger(ms) || ms <= 0) {
+    throw new Error('ERR_GATEWAY_APP_TIMEOUT_INVALID: appTimeoutMs must be a positive integer (milliseconds)')
+  }
+  return ms
+}
+
+// Re-read on every request, so a runtime may start, or restart under a new
+// key, after the Gateway. Until it has published a key its routes answer 503.
+async function _runtimeKey (app) {
+  const key = await fs.promises.readFile(app.keyFile, 'utf8').then(s => s.trim(), () => '')
+  if (/^[0-9a-f]{64}$/i.test(key)) return key
+  const err = new Error(`ERR_APP_RUNTIME_UNAVAILABLE: ${app.name}`)
+  err.statusCode = 503
+  throw err
+}
+
+// The caller's credentials stay at the Gateway: the authVerifier already turned
+// them into the identity, and app code must not be able to replay them.
+const CREDENTIAL_HEADERS = ['authorization', 'proxy-authorization', 'cookie']
+
+function _appRequest (req) {
+  const headers = { ...req.headers }
+  for (const name of CREDENTIAL_HEADERS) delete headers[name]
+  return { params: req.params, query: req.query, body: req.body, headers }
+}
+
+// Aborts when the client goes away before its response finished, so a request
+// nobody waits for is not forwarded.
+function _disconnectSignal (rep) {
+  const ac = new AbortController()
+  rep.raw.once('close', () => { if (!rep.raw.writableFinished) ac.abort() })
+  return ac.signal
+}
+
+// One call to the app's runtime: `method` is 'invoke' (unary) or 'stream'. The
+// runtime takes `{ params, query, body, headers }` from `req`; the identity the
+// authVerifier set (none on an open route) travels beside it.
+async function _forward (client, app, route, method, req, timeoutMs, signal) {
+  const key = await _runtimeKey(app)
+  return client[method](key, route.id, _appRequest(req), { identity: req._info || {}, timeoutMs, signal })
+}
+
+// Mounts an app's route table (`app.routes`) under `app.mount` (default
+// `/apps/<name>`) and forwards every request to the app's runtime over HRPC.
+//
+// opts.authVerifier: async (request, route) => identity | false. Every
+// `auth: true` route gets a route-level preParsing hook that runs it: after the
+// Host check and rate limit (onRequest, so failed attempts are throttled too),
+// before body parsing, validation, the cache and the forward. With no
+// verifier those routes answer 401. Routes without `auth: true` stay open.
+// The verified identity reaches the app runtime as the call's `identity`.
+function buildFastifyRoutes (app, client, ctx, opts = {}) {
+  const mount = app.mount || `/apps/${app.name}`
+  const timeoutMs = resolveAppTimeout(ctx.conf)
+  const prefix = mount === '/' ? '' : mount
+
+  return app.routes.map(route => {
+    const fastifyRoute = {
+      method: route.method,
+      // A route at "/" answers at the mount itself (/apps/<name>), not only with a trailing slash.
+      url: prefix && route.path === '/' ? prefix : prefix + route.path
+    }
+
+    if (route.schema) {
+      fastifyRoute.schema = route.schema
+    }
+
+    if (route.auth === true) {
+      fastifyRoute.preParsing = createAuthHook(opts.authVerifier || null, Object.freeze({
+        id: route.id,
+        method: route.method,
+        path: route.path,
+        app: app.name,
+        permissions: Array.isArray(route.permissions) ? Object.freeze([...route.permissions]) : undefined
+      }))
+    }
+
+    // A stream route owns the raw ServerResponse. The reply is hijacked so
+    // Fastify never serializes; the boundary catch is load-bearing — a
+    // rejection after hijack() is otherwise swallowed (reply.sent is true)
+    // and the socket stays open forever.
+    if (route.stream === true) {
+      fastifyRoute.handler = async (req, rep) => {
+        const signal = _disconnectSignal(rep)
+        rep.hijack()
+        const raw = rep.raw
+        try {
+          await pipeToResponse(await _forward(client, app, route, 'stream', req, timeoutMs, signal), raw)
+        } catch (err) {
+          if (!raw.headersSent) {
+            const body = errorResponse(err, req.log)
+            raw.writeHead(body.statusCode, { 'content-type': 'application/json' })
+            raw.end(JSON.stringify(body))
+          } else if (!raw.writableEnded) {
+            raw.end()
+          }
+        }
+      }
+      return fastifyRoute
+    }
+
+    const cacheFields = route.cache
+
+    fastifyRoute.handler = async (req, rep) => {
+      // A cached call is shared by every request waiting on its key, so one
+      // client leaving must not abort it.
+      const signal = Array.isArray(cacheFields) ? undefined : _disconnectSignal(rep)
+      const forward = () => _forward(client, app, route, 'invoke', req, timeoutMs, signal)
+
+      let result
+      if (cacheFields && Array.isArray(cacheFields)) {
+        const keyParts = [app.name, route.id, ..._extractCacheKeyParts(cacheFields, req)]
+        // Per-caller on an `auth: true` route: the response may depend on who asked.
+        if (route.auth === true) keyParts.push(_identityCacheKey(req))
+        result = await cachedRoute(
+          ctx,
+          keyParts,
+          route.path,
+          forward,
+          // A forced refresh is honoured only for a caller the authVerifier
+          // vouched for and granted OVERWRITE_CACHE_PERM; a bare header is not proof.
+          String(req.query?.overwriteCache) === 'true' && canOverwriteCache(req)
+        )
+      } else {
+        result = await forward()
+      }
+
+      return send200(rep, result)
+    }
+
+    return fastifyRoute
+  })
+}
+
+module.exports = { buildFastifyRoutes, errorResponse, resolveAppTimeout, runtimeKey: _runtimeKey }

package/workers/lib/plugin-gateway.js

@@ -0,0 +1,67 @@
+'use strict'
+
+const path = require('path')
+const { pluginLogger } = require('./logger')
+
+// Builds what a plugin sees as require('@tetherto/mdk-gateway/plugin') — the
+// contract between a plugin and the gateway. There are no phases and no worker
+// internals to learn; the one moment in the gateway's life a plugin can name is
+// onReady, and only because a plugin cannot observe it any other way.
+//
+// The full surface:
+//   gw.config           gateway conf ⊕ the plugin's own config block
+//                       (spec.gateway.plugins[].config wins key-by-key)
+//   gw.logger           the gateway's logger, tagged with this plugin's name:
+//                       error/warn/info/debug/trace/fatal + child()
+//   gw.onReady(fn)      fn runs once this gateway is serving
+//
+// Everything else a plugin needs it owns: kernel and worker data — live or
+// historical — go through the plugin's own mdk client, built from
+// config.kernelKey/kernelKeyPair/kernelBootstrap (see the telemetry plugin's
+// lib/client.js). kernelKeyPair is the persistent keypair status.rpcClientKey
+// is read from, so plugin clients dial the Kernel with the allowlisted key.
+
+// What a plugin's log lines are tagged with. The manifest name is the plugin's
+// own identity; the scope is dropped because the tag prefixes every line.
+function _pluginName (pluginDir) {
+  try {
+    const { name } = require(path.join(pluginDir, 'mdk-plugin.json'))
+    if (typeof name === 'string' && name) return name.replace(/^@[^/]+\//, '')
+  } catch {}
+  return path.basename(pluginDir)
+}
+
+function buildPluginContext (wrk, pluginDir, pluginConf) {
+  const kernelKey = Buffer.isBuffer(wrk.ctx.kernelKey) ? wrk.ctx.kernelKey.toString('hex') : wrk.ctx.kernelKey
+
+  const context = Object.freeze({
+    // The plugin's own config block (spec.gateway.plugins[].config) wins over
+    // gateway-wide conf, so a plugin's settings live with the plugin.
+    config: Object.freeze({
+      kernelKey: kernelKey || null,
+      // resolved lazily: net_r0.dht does not exist yet when plugins load; a
+      // host without one (the MCP server's shim) dials with an ephemeral key
+      kernelKeyPair: () => wrk.net_r0?.dht?.defaultKeyPair,
+      kernelBootstrap: wrk.ctx.kernelBootstrap || null,
+      ...wrk.conf,
+      ...pluginConf
+    }),
+
+    // A plugin that prints with console has no level, no timestamp and no name;
+    // going through the gateway's logger puts its lines in the same stream and
+    // format as the requests it serves.
+    logger: pluginLogger(_pluginName(pluginDir), wrk.conf),
+
+    // Plugin modules are loaded from the worker's init(), which is strictly
+    // before _start() opens the listener, so a plugin doing anything at load
+    // time does it to a gateway that answers nothing yet — and a plugin whose
+    // work is a call to this same gateway fails for no reason but the order.
+    // onReady is that missing moment: fn runs once everything this gateway
+    // serves is up, and runs straight away for anything registered after that.
+    onReady: (fn) => wrk.onGatewayReady(fn)
+  })
+
+  return { context }
+}
+
+module.exports = { buildPluginContext }

package/workers/lib/plugin-loader.js

@@ -0,0 +1,6 @@
+'use strict'
+
+// The loader lives in @tetherto/mdk-app-runtime, which loads and runs app
+// handlers; the Gateway only reads route tables with it. This path stays as a
+// re-export for existing callers.
+module.exports = require('@tetherto/mdk-app-runtime/lib/plugin-loader')