velocious 1.0.431 → 1.0.433

package/build/http-server/worker-handler/index.js

@@ -0,0 +1,370 @@
+// @ts-check
+
+import Logger from "../../logger.js"
+import {Worker} from "worker_threads"
+import ensureError from "../../utils/ensure-error.js"
+import websocketEventsHost from "../websocket-events-host.js"
+
+/**
+ * Runs summarize worker message.
+ * @param {object} data - Worker message payload.
+ * @param {string} data.command - Command name.
+ * @param {number} [data.clientCount] - Client count.
+ * @param {string | Uint8Array} [data.output] - Output chunk.
+ * @returns {object} - Log-safe message details.
+ */
+function summarizeWorkerMessage(data) {
+  const {output, ...rest} = data
+
+  if (output === undefined) {
+    return rest
+  }
+
+  const outputType = typeof output
+  const outputLength = typeof output === "string"
+    ? output.length
+    : (output instanceof Uint8Array ? output.byteLength : undefined)
+
+  return {
+    ...rest,
+    output: {
+      length: outputLength,
+      type: outputType
+    }
+  }
+}
+
+export default class VelociousHttpServerWorker {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {import("../../configuration.js").default} args.configuration - Configuration instance.
+   * @param {number} args.workerCount - Worker count.
+   */
+  constructor({configuration, workerCount}) {
+    this.configuration = configuration
+
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {Record<number, import("../server-client.js").default>} */
+    this.clients = {}
+
+    this.logger = new Logger(this)
+    this.workerCount = workerCount
+    this.workerStarted = false
+    this._stopping = false
+    this._debugRequestId = 0
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {Map<number, {resolve: (snapshot: Record<string, ?>) => void}>} */
+    this._debugSnapshotRequests = new Map()
+  }
+
+  start() {
+    return new Promise((resolve) => {
+      this.onStartCallback = resolve
+      this._spawnWorker()
+    })
+  }
+
+  async _spawnWorker() {
+    const debug = this.configuration.debug
+    const directory = this.configuration.getDirectory()
+    const velociousPath = await this.configuration.getEnvironmentHandler().getVelociousPath()
+
+    this.worker = new Worker(`${velociousPath}/src/http-server/worker-handler/worker-script.js`, {
+      workerData: {
+        debug,
+        directory,
+        environment: this.configuration.getEnvironment(),
+        workerCount: this.workerCount
+      }
+    })
+    this.worker.on("error", this.onWorkerError)
+    this.worker.on("exit", this.onWorkerExit)
+    this.worker.on("message", this.onWorkerMessage)
+  }
+
+  /**
+   * Runs add socket connection.
+   * @param {import("../server-client.js").default} client - Client instance.
+   * @returns {void} - No return value.
+   */
+  addSocketConnection(client) {
+    const clientCount = client.clientCount
+
+    if (!this.worker) throw new Error("Worker not initialized")
+
+    client.setWorker(this.worker)
+    client.listen()
+
+    this.clients[clientCount] = client
+    this.worker.postMessage({command: "newClient", clientCount, remoteAddress: client.remoteAddress})
+  }
+
+  /**
+   * On worker error.
+   * @param {?} error - Error instance.
+   */
+  onWorkerError = (error) => {
+    this.logger.error(`Velocious worker ${this.workerCount} error`, error)
+    void this._closeAllClients()
+    throw ensureError(error) // Throws original error with backtrace and everything into the console
+  }
+
+  /**
+   * On worker exit.
+   * @param {number} code - Code.
+   * @returns {void} - No return value.
+   */
+  onWorkerExit = (code) => {
+    this._hasExited = true
+    this.workerStarted = false
+
+    if (code !== 0 && !this._stopping) {
+      this.logger.error(`Velocious worker ${this.workerCount} exited unexpectedly with code ${code}`)
+      void this._closeAllClients()
+      throw new Error(`Client worker stopped with exit code ${code}`)
+    } else {
+      this.logger.debug(() => `Client worker stopped with exit code ${code}`)
+    }
+
+    this.unregisterFromEventsHostIfNeeded()
+    if (this._stopResolve) {
+      this._stopResolve()
+    }
+    this._stopResolve = null
+  }
+
+  /**
+   * Runs close all clients.
+   * @returns {void} - No return value.
+   */
+  _closeAllClients() {
+    const clients = Object.values(this.clients)
+    this.clients = {}
+
+    for (const client of clients) {
+      try {
+        void client.end()
+      } catch (error) {
+        this.logger.warn("Failed to close client after worker exit", error)
+      }
+    }
+  }
+
+  /**
+   * On worker message.
+   * @param {object} data - Data payload.
+   * @param {string} data.command - Command.
+   * @param {number} [data.clientCount] - Client count.
+   * @param {string | Uint8Array} [data.output] - Output.
+   * @param {string} [data.channel] - Channel name.
+   * @param {number} [data.requestId] - Debug request id.
+   * @param {Record<string, ?>} [data.snapshot] - Worker debug snapshot.
+   * @param {?} [data.payload] - Payload data.
+   * @param {Record<string, ?>} [data.broadcastParams] - V2 broadcast filter params.
+   * @param {?} [data.body] - V2 broadcast body.
+   * @returns {void} - No return value.
+   */
+  onWorkerMessage = (data) => {
+    this.logger.debug("Worker message", summarizeWorkerMessage(data))
+
+    const {command} = data
+
+
+    if (command == "started") {
+      this.workerStarted = true
+      this.registerWithEventsHost()
+
+      if (this.onStartCallback) {
+        this.onStartCallback(null)
+      }
+
+      this.onStartCallback = null
+    } else if (command == "clientOutput") {
+      this.logger.debug("CLIENT OUTPUT", summarizeWorkerMessage(data))
+
+      const {clientCount, output} = data
+      const client = typeof clientCount === "number" ? this.clients[clientCount] : undefined
+
+      if (!client) {
+        this.logger.warn(() => [`Velocious worker ${this.workerCount} produced output for missing client ${clientCount}`, data])
+        return
+      }
+
+      if (output !== null && output !== undefined) {
+        const outputLength = typeof output === "string" ? output.length : output.byteLength
+
+        void client.send(output).then(() => {
+          this.logger.debug(() => ["Client output delivered", {
+            clientCount,
+            outputLength,
+            workerCount: this.workerCount
+          }])
+        }).catch((error) => {
+          this.logger.error(() => ["Failed to deliver client output", {
+            clientCount,
+            workerCount: this.workerCount
+          }, error])
+        })
+      }
+    } else if (command == "clientClose") {
+      const {clientCount} = data
+      const client = typeof clientCount === "number" ? this.clients[clientCount] : undefined
+
+      if (!client) {
+        this.logger.error(() => [`Velocious worker ${this.workerCount} requested close for missing client ${clientCount}`, data])
+        return
+      }
+
+      void client.end()
+
+      if (typeof clientCount === "number") {
+        delete this.clients[clientCount]
+      }
+    } else if (command == "debugSnapshot") {
+      const {requestId, snapshot} = data
+      if (typeof requestId !== "number") throw new Error("debugSnapshot requestId must be a number")
+      const request = this._debugSnapshotRequests.get(requestId)
+
+      if (request) {
+        this._debugSnapshotRequests.delete(requestId)
+        request.resolve(snapshot || {})
+      }
+    } else if (command == "shutdownComplete") {
+      this._stopResolve?.()
+      this._stopResolve = null
+    } else if (command == "websocketPublish") {
+      const {channel, payload} = data
+
+      if (typeof channel !== "string") {
+        throw new Error("Worker websocket publish channel must be a string")
+      }
+
+      websocketEventsHost.publish({channel, payload})
+    } else if (command == "websocketV2Broadcast") {
+      const {body, broadcastParams, channel} = data
+
+      if (typeof channel !== "string") {
+        throw new Error("Worker websocket v2-broadcast channel must be a string")
+      }
+
+      websocketEventsHost.broadcastV2({body, broadcastParams: broadcastParams || {}, channel})
+    } else {
+      throw new Error(`Unknown command: ${command}`)
+    }
+  }
+
+  /**
+   * Runs get debug snapshot.
+   * @returns {Promise<Record<string, ?>>} - Worker-local debug snapshot.
+   */
+  getDebugSnapshot() {
+    if (!this.workerStarted || !this.worker) {
+      return Promise.resolve({active: false, workerCount: this.workerCount})
+    }
+
+    const requestId = ++this._debugRequestId
+
+    return new Promise((resolve) => {
+      const timeout = setTimeout(() => {
+        this._debugSnapshotRequests.delete(requestId)
+        resolve({active: true, error: "Timed out waiting for worker debug snapshot", workerCount: this.workerCount})
+      }, 2000)
+
+      if (typeof timeout.unref === "function") timeout.unref()
+
+      const worker = this.worker
+
+      if (!worker) {
+        clearTimeout(timeout)
+        resolve({active: false, workerCount: this.workerCount})
+        return
+      }
+
+      this._debugSnapshotRequests.set(requestId, {
+        resolve: (snapshot) => {
+          clearTimeout(timeout)
+          resolve({active: true, snapshot, workerCount: this.workerCount})
+        }
+      })
+      worker.postMessage({command: "debugSnapshot", requestId})
+    })
+  }
+
+  /**
+   * Runs stop.
+   * @returns {Promise<void>} - Resolves when stopped.
+   */
+  stop() {
+    if (!this.worker) return Promise.resolve()
+    if (this._hasExited) return Promise.resolve()
+
+    this._stopping = true
+    this.workerStarted = false
+    this.unregisterFromEventsHostIfNeeded()
+    const worker = this.worker
+
+    if (!worker) return Promise.resolve()
+
+    return new Promise((resolve) => {
+      this._stopResolve = resolve
+      worker.postMessage({command: "shutdown"})
+    })
+  }
+
+  /**
+   * Runs dispatch websocket event.
+   * @param {object} args - Options object.
+   * @param {string} args.channel - Channel name.
+   * @param {string} [args.createdAt] - Event creation time.
+   * @param {string} [args.eventId] - Event identifier.
+   * @param {?} args.payload - Payload data.
+   * @returns {void} - No return value.
+   */
+  dispatchWebsocketEvent({channel, createdAt, eventId, payload}) {
+    // Test and shutdown paths can leave a registered handler without a live worker-thread transport.
+    if (!this.workerStarted) return
+    if (!this.worker || typeof this.worker.postMessage !== "function") return
+
+    this.worker.postMessage({channel, command: "websocketEvent", createdAt, eventId, payload})
+  }
+
+  /**
+   * Forwards a V2 channel broadcast to this worker's thread so it can
+   * dispatch to any locally-registered V2 subscriptions.
+   * @param {object} args - Options object.
+   * @param {string} args.channel - Channel name.
+   * @param {Record<string, ?>} args.broadcastParams - Routing filter params.
+   * @param {?} args.body - Message body.
+   * @param {string} [args.eventId] - Persisted event id for replay.
+   * @param {string} [args.createdAt] - Event creation timestamp.
+   * @returns {void}
+   */
+  dispatchWebsocketV2Broadcast({body, broadcastParams, channel, eventId, createdAt}) {
+    if (!this.workerStarted) return
+    if (!this.worker || typeof this.worker.postMessage !== "function") return
+
+    this.worker.postMessage({body, broadcastParams, channel, command: "websocketV2Broadcast", eventId, createdAt})
+  }
+
+  /**
+   * Runs register with events host.
+    @returns {void} */
+  registerWithEventsHost() {
+    if (this.unregisterFromEventsHost) return
+
+    this.unregisterFromEventsHost = websocketEventsHost.register(this)
+  }
+
+  /**
+   * Runs unregister from events host if needed.
+    @returns {void} */
+  unregisterFromEventsHostIfNeeded() {
+    if (!this.unregisterFromEventsHost) return
+
+    this.unregisterFromEventsHost()
+    this.unregisterFromEventsHost = null
+  }
+}

package/build/http-server/worker-handler/worker-script.js

@@ -0,0 +1,6 @@
+// @ts-check
+
+import {workerData, parentPort} from "worker_threads"
+import WorkerThread from "./worker-thread.js"
+
+new WorkerThread({parentPort, workerData})

package/build/http-server/worker-handler/worker-thread.js

@@ -0,0 +1,286 @@
+// @ts-check
+
+import Application from "../../application.js"
+import Client from "../client/index.js"
+import dispatchChannelSubscribers from "./channel-subscriber-dispatch.js"
+import {digg} from "diggerize"
+import errorLogger from "../../error-logger.js"
+import Logger from "../../logger.js"
+import toImportSpecifier from "../../utils/to-import-specifier.js"
+import WebsocketEvents from "../websocket-events.js"
+
+/**
+ * Runs summarize client write chunk.
+ * @param {Buffer | Uint8Array | string} chunk - Client input payload.
+ * @returns {{length: number, preview: string}} - Chunk summary for logging.
+ */
+function summarizeClientWriteChunk(chunk) {
+  const normalizedChunk = typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk)
+  const preview = normalizedChunk.toString("latin1", 0, Math.min(normalizedChunk.length, 160)).replaceAll("\r", "\\r").replaceAll("\n", "\\n")
+
+  return {length: normalizedChunk.length, preview}
+}
+
+export default class VelociousHttpServerWorkerHandlerWorkerThread {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {import("worker_threads").parentPort} args.parentPort - Parent port.
+   * @param {{debug: boolean, directory: string, environment: string, workerCount: number}} args.workerData - Worker configuration details.
+   */
+  constructor({parentPort, workerData}) {
+    if (!parentPort) throw new Error("parentPort is required")
+
+    const {workerCount} = workerData
+
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {Record<number, Client>} */
+    this.clients = {}
+
+    this.logger = new Logger(this)
+    this.parentPort = parentPort
+    this.workerData = workerData
+    this.workerCount = workerCount
+
+    parentPort.on("message", errorLogger(this.onCommand))
+
+    this.initialize().then(() => {
+      if (!this.application) throw new Error("Application not initialized")
+
+      this.application.initialize().then(() => {
+        this.logger.debugLowLevel(() => `Worker ${workerCount} started`)
+        parentPort.postMessage({command: "started"})
+      })
+    })
+  }
+
+  /**
+   * Runs initialize.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async initialize() {
+    const {debug, directory, environment} = this.workerData
+    const configurationPath = `${directory}/src/config/configuration.js`
+    const configurationImport = await import(toImportSpecifier(configurationPath))
+
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {import("../../configuration.js").default} */
+    this.configuration = configurationImport.default
+
+    if (!this.configuration) throw new Error(`Configuration couldn't be loaded from: ${configurationPath}`)
+
+    const configuration = this.configuration
+
+    configuration.debug = debug === true
+    configuration.setEnvironment(environment)
+    configuration.setCurrent()
+    await this.logger.debug(() => ["Worker thread configuration loaded", {debug: configuration.debug, workerCount: this.workerCount}])
+    this.websocketEvents = new WebsocketEvents({parentPort: this.parentPort, workerCount: this.workerCount})
+    configuration.setWebsocketEvents(this.websocketEvents)
+
+    this.application = new Application({configuration, type: "worker-handler"})
+
+    if (!configuration.isInitialized()) {
+      await configuration.initialize({type: "worker-handler"})
+    }
+  }
+
+  /**
+   * On command.
+   * @param {object} data - Data payload.
+   * @param {string} data.command - Command.
+   * @param {Buffer | Uint8Array | string} [data.chunk] - Chunk.
+   * @param {string} [data.remoteAddress] - Remote address.
+   * @param {number} [data.clientCount] - Client count.
+   * @param {string} [data.channel] - Channel name.
+   * @param {string} [data.createdAt] - Event creation time.
+   * @param {string} [data.eventId] - Event identifier.
+   * @param {number} [data.requestId] - Debug request id.
+   * @param {?} [data.payload] - Payload data.
+   * @param {Record<string, ?>} [data.broadcastParams] - V2 broadcast filter params.
+   * @param {?} [data.body] - V2 broadcast body.
+   */
+  onCommand = async (data) => {
+    await this.logger.debugLowLevel(() => [`Worker ${this.workerCount} received command`, data])
+
+    const command = data.command
+
+    if (command == "newClient") {
+      this.handleNewClient(data)
+    } else if (command == "clientWrite") {
+      await this.handleClientWrite(data)
+    } else if (command == "websocketEvent") {
+      await this.handleWebsocketEvent(data)
+    } else if (command == "websocketV2Broadcast") {
+      this.handleWebsocketV2Broadcast(data)
+    } else if (command == "debugSnapshot") {
+      this.handleDebugSnapshot(data)
+    } else if (command == "shutdown") {
+      await this.handleShutdown()
+    } else {
+      throw new Error(`Unknown command: ${command}`)
+    }
+  }
+
+  /**
+   * Runs handle new client.
+   * @param {object} data - Data payload.
+   * @param {number} [data.clientCount] - Client count.
+   * @param {string} [data.remoteAddress] - Remote address.
+   * @returns {void}
+   */
+  handleNewClient(data) {
+    if (!this.configuration) throw new Error("Configuration not initialized")
+
+    const {clientCount, remoteAddress} = data
+
+    if (typeof clientCount !== "number") throw new Error("clientCount must be a number")
+
+    const client = new Client({
+      clientCount,
+      configuration: this.configuration,
+      remoteAddress
+    })
+
+    client.events.on("output", (output) => {
+      this.parentPort.postMessage({command: "clientOutput", clientCount, output})
+    })
+
+    client.events.on("close", (output) => {
+      this.logger.debugLowLevel(() => "Close received from client in worker - forwarding to worker parent")
+      this.parentPort.postMessage({command: "clientClose", clientCount, output})
+    })
+
+    this.clients[clientCount] = client
+  }
+
+  /**
+   * Runs handle client write.
+   * @param {object} data - Data payload.
+   * @param {Buffer | Uint8Array | string} [data.chunk] - Chunk.
+   * @param {number} [data.clientCount] - Client count.
+   * @returns {Promise<void>} Resolves when the client write is dispatched.
+   */
+  async handleClientWrite(data) {
+    await this.logger.debugLowLevel("Looking up client")
+
+    const {chunk, clientCount} = data
+    if (!chunk) throw new Error("No chunk given")
+    const client = /**
+                    * Narrows the runtime value to the documented type.
+                     @type {Client | undefined} */ (digg(this.clients, clientCount))
+
+    if (!client) throw new Error(`Client not found for clientWrite: ${clientCount}`)
+
+    const clientChunk = typeof chunk === "string" ? Buffer.from(chunk) : Buffer.from(chunk)
+
+    await this.logger.debug(() => ["Sending clientWrite to parser", {clientCount, ...summarizeClientWriteChunk(clientChunk)}])
+
+    client.onWrite(clientChunk)
+  }
+
+  /**
+   * Runs handle websocket event.
+   * @param {object} data - Data payload.
+   * @param {string} [data.channel] - Channel name.
+   * @param {string} [data.createdAt] - Event creation time.
+   * @param {string} [data.eventId] - Event identifier.
+   * @param {?} [data.payload] - Payload data.
+   * @returns {Promise<void>} Resolves when the websocket event is dispatched.
+   */
+  async handleWebsocketEvent(data) {
+    const {channel, createdAt, eventId, payload} = data
+
+    if (typeof channel !== "string") throw new Error("No channel given")
+
+    await this.broadcastWebsocketEvent({channel, createdAt, eventId, payload})
+  }
+
+  /**
+   * Runs handle websocket v2 broadcast.
+   * @param {object} data - Data payload.
+   * @param {Record<string, ?>} [data.broadcastParams] - V2 broadcast filter params.
+   * @param {?} [data.body] - V2 broadcast body.
+   * @param {string} [data.channel] - Channel name.
+   * @param {string} [data.eventId] - Event identifier.
+   * @returns {void}
+   */
+  handleWebsocketV2Broadcast(data) {
+    const {body, broadcastParams, channel, eventId} = data
+
+    if (typeof channel !== "string") throw new Error("No channel given")
+    if (!this.configuration) throw new Error("Configuration not initialized")
+
+    this.configuration._broadcastToChannelLocal(channel, broadcastParams || {}, body, {eventId})
+  }
+
+  /**
+   * Runs handle debug snapshot.
+   * @param {object} data - Data payload.
+   * @param {number} [data.requestId] - Debug request id.
+   * @returns {void}
+   */
+  handleDebugSnapshot(data) {
+    const {requestId} = data
+
+    if (typeof requestId !== "number") throw new Error("debugSnapshot requestId must be a number")
+    if (!this.configuration) throw new Error("Configuration not initialized")
+
+    this.parentPort.postMessage({
+      command: "debugSnapshot",
+      requestId,
+      snapshot: this.configuration.getLocalDebugSnapshot()
+    })
+  }
+
+  /**
+   * Runs handle shutdown.
+   * @returns {Promise<void>} Resolves after worker shutdown has been requested.
+   */
+  async handleShutdown() {
+    if (this.configuration?.closeDatabaseConnections) {
+      await this.configuration.closeDatabaseConnections()
+    }
+
+    this.parentPort.postMessage({command: "shutdownComplete"})
+    process.exit(0)
+  }
+
+  /**
+   * Runs broadcast websocket event.
+   * @param {object} args - Options object.
+   * @param {string} args.channel - Channel name.
+   * @param {string | undefined} args.createdAt - Event creation time.
+   * @param {string | undefined} args.eventId - Event identifier.
+   * @param {?} args.payload - Payload data.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async broadcastWebsocketEvent({channel, createdAt, eventId, payload}) {
+    const sendTasks = []
+
+    for (const clientKey of Object.keys(this.clients)) {
+      const client = this.clients[Number(clientKey)]
+      if (!client) continue
+      const session = client.websocketSession
+
+      if (!session) continue
+
+      sendTasks.push(session.sendEvent(channel, payload, {
+        createdAt,
+        eventId
+      }))
+    }
+
+    if (this.configuration) {
+      // Isolate channel subscriber failures so a buggy in-process callback
+      // cannot reject this command and crash the worker thread, but still
+      // surface the error to the framework error events so bug reporters
+      // can pick it up.
+      sendTasks.push(dispatchChannelSubscribers({channel, configuration: this.configuration, createdAt, eventId, logger: this.logger, payload}))
+    }
+
+    await Promise.all(sendTasks)
+  }
+}

package/build/initializer.js

@@ -0,0 +1,39 @@
+// @ts-check
+
+import restArgsError from "./utils/rest-args-error.js"
+
+export default class VelociousInitializer {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {import("./configuration.js").default} args.configuration - Configuration instance.
+   * @param {string} args.type - Type identifier.
+   */
+  constructor({configuration, type, ...restArgs}) {
+    restArgsError(restArgs)
+
+    this._configuration = configuration
+    this._type = type
+  }
+
+  /**
+   * Runs get configuration.
+   * @returns {import("./configuration.js").default} - The configuration.
+   */
+  getConfiguration() { return this._configuration }
+
+  /**
+   * Runs get type.
+   * @returns {string} - The type.
+   */
+  getType() { return this._type }
+
+  /**
+   * Runs run.
+   * @abstract
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  run() {
+    throw new Error(`'run' hasn't been implemented on ${this.constructor.name})`)
+  }
+}