velocious 1.0.430 → 1.0.432

package/src/http-server/server-client.js

@@ -0,0 +1,222 @@
+// @ts-check
+
+import EventEmitter from "../utils/event-emitter.js"
+import Logger from "../logger.js"
+
+/**
+ * Runs summarize socket chunk.
+ * @param {Buffer} chunk - Incoming socket data.
+ * @returns {object} - Chunk debug metadata.
+ */
+function summarizeSocketChunk(chunk) {
+  const preview = chunk.toString("latin1", 0, Math.min(chunk.length, 160)).replaceAll("\r", "\\r").replaceAll("\n", "\\n")
+
+  return {
+    length: chunk.length,
+    preview
+  }
+}
+
+export default class ServerClient {
+  events = new EventEmitter()
+
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {import("../configuration.js").default} args.configuration - Configuration instance.
+   * @param {import("net").Socket} args.socket - Socket instance.
+   * @param {number} args.clientCount - Client count.
+   */
+  constructor({configuration, socket, clientCount}) {
+    if (!configuration) throw new Error("No configuration given")
+
+    this.configuration = configuration
+    this.logger = new Logger(this)
+    this.socket = socket
+    this.clientCount = clientCount
+    this.remoteAddress = socket.remoteAddress
+    this.closeEmitted = false
+
+    socket.on("end", this.onSocketEnd)
+    socket.on("error", this.onSocketError)
+    socket.on("close", this.onSocketClose)
+    socket.on("timeout", this.onSocketTimeout)
+    socket.on("drain", this.onSocketDrain)
+    socket.on("finish", this.onSocketFinish)
+  }
+
+  /**
+   * Runs listen.
+   * @returns {void} - No return value.
+   */
+  listen() {
+    this.logger.debug(() => ["Socket listen", {
+      clientCount: this.clientCount,
+      remoteAddress: this.socket.remoteAddress,
+      remoteFamily: this.socket.remoteFamily,
+      remotePort: this.socket.remotePort
+    }])
+    this.socket.on("data", this.onSocketData)
+  }
+
+  /**
+   * Runs end.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  end() {
+    return new Promise((resolve) => {
+      if (this.socket.destroyed || this.socket.writableEnded || this.socket.writable === false) {
+        resolve(undefined)
+        return
+      }
+
+      this.socket.once("close", () => resolve(undefined))
+      this.socket.end()
+    })
+  }
+
+  /**
+   * On socket data.
+   * @param {Buffer} chunk - Chunk.
+   * @returns {void} - No return value.
+   */
+  onSocketData = (chunk) => {
+    this.logger.debugLowLevel(() => `Socket ${this.clientCount}: ${chunk}`)
+    this.logger.debug(() => ["Socket data received", {clientCount: this.clientCount, ...summarizeSocketChunk(chunk)}])
+
+    if (!this.worker) throw new Error("No worker")
+
+    this.worker.postMessage({
+      command: "clientWrite",
+      chunk,
+      clientCount: this.clientCount
+    })
+  }
+
+  /**
+   * On socket end.
+   * @returns {void} - No return value.
+   */
+  onSocketEnd = () => {
+    this.logger.debugLowLevel(() => `Socket ${this.clientCount} end`)
+    this.emitClose()
+  }
+
+  /**
+   * On socket close.
+   * @returns {void} - No return value.
+   */
+  onSocketClose = () => {
+    this.logger.debugLowLevel(() => `Socket ${this.clientCount} close`)
+    this.emitClose()
+  }
+
+  /**
+   * On socket timeout.
+   * @returns {void} - No return value.
+   */
+  onSocketTimeout = () => {
+    this.logger.debug(() => ["Socket timeout", {clientCount: this.clientCount}])
+  }
+
+  /**
+   * On socket drain.
+   * @returns {void} - No return value.
+   */
+  onSocketDrain = () => {
+    this.logger.debug(() => ["Socket drain", {clientCount: this.clientCount}])
+  }
+
+  /**
+   * On socket finish.
+   * @returns {void} - No return value.
+   */
+  onSocketFinish = () => {
+    this.logger.debug(() => ["Socket finish", {clientCount: this.clientCount}])
+  }
+
+
+  /**
+   * On socket error.
+   * @param {Error} error - Socket error.
+   * @returns {void} - No return value.
+   */
+  onSocketError = (error) => {
+    const errorCode = /**
+                       * Narrows the runtime value to the documented type.
+                        @type {{code?: string}} */ (error).code
+
+    this.logger.error(() => [`Socket ${this.clientCount} error`, errorCode || error.message])
+    this.emitClose()
+
+    if (!this.socket.destroyed) {
+      this.socket.destroy(error)
+    }
+  }
+
+  /**
+   * Runs emit close.
+   * @returns {void} - No return value.
+   */
+  emitClose() {
+    if (this.closeEmitted) return
+
+    this.closeEmitted = true
+    this.events.emit("close", this)
+  }
+
+  /**
+   * Runs send.
+   * @param {string | Uint8Array} data - Data payload.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async send(data) {
+    return new Promise((resolve) => {
+      this.logger.debugLowLevel(() => `Send ${data}`)
+      if (this.socket.destroyed || this.socket.writableEnded || this.socket.writable === false) {
+        this.logger.debugLowLevel(() => "Skipping send because socket is closed")
+        resolve()
+        return
+      }
+
+      let done = false
+
+      const finish = () => {
+        if (done) return
+
+        done = true
+        this.socket.off("error", onWriteError)
+        resolve()
+      }
+      const onWriteError = (/**
+                             * Narrows the runtime value to the documented type.
+                              @type {Error} */ error) => {
+        const errorCode = /**
+                           * Narrows the runtime value to the documented type.
+                            @type {{code?: string}} */ (error).code
+
+        this.logger.error(() => [`Socket ${this.clientCount} write error`, errorCode || error.message])
+        finish()
+      }
+
+      this.socket.once("error", onWriteError)
+      this.socket.write(data, (error) => {
+        if (error) {
+          onWriteError(error)
+          return
+        }
+
+        finish()
+      })
+    })
+  }
+
+  /**
+   * Runs set worker.
+   * @param {import("worker_threads").Worker} newWorker - New worker.
+   * @returns {void} - No return value.
+   */
+  setWorker(newWorker) {
+    this.worker = newWorker
+  }
+}

package/src/http-server/server-lock.js

@@ -0,0 +1,178 @@
+// @ts-check
+
+import fs from "node:fs/promises"
+import os from "node:os"
+import path from "node:path"
+
+/**
+ * Directory-based lock that allows only one HTTP server process per app directory.
+ */
+export default class VelociousHttpServerLock {
+  /**
+   * Build a lock for the configured application directory and server endpoint.
+   * @param {object} args - Options object.
+   * @param {import("../configuration.js").default} args.configuration - Configuration that owns the application directory.
+   * @param {string} args.host - Configured HTTP host.
+   * @param {number} args.port - Configured HTTP port.
+   */
+  constructor({configuration, host, port}) {
+    this.configuration = configuration
+    this.host = host
+    this.port = port
+    this.lockPath = path.join(configuration.getDirectory(), "tmp", "server.lock")
+    this.acquired = false
+  }
+
+  /**
+   * Acquires the app-directory HTTP server lock before startup side effects run.
+   * @returns {Promise<void>} - Resolves after the lock has been acquired.
+   */
+  async acquire() {
+    await fs.mkdir(path.dirname(this.lockPath), {recursive: true})
+
+    while (true) {
+      const acquired = await this.tryAcquire()
+
+      if (acquired) {
+        return
+      }
+
+      if (await this.isStale()) {
+        await fs.rm(this.lockPath, {recursive: true, force: true})
+        continue
+      }
+
+      throw new Error(await this.lockHeldMessage())
+    }
+  }
+
+  /**
+   * Tries to create the lock directory and write owner metadata.
+   * @returns {Promise<boolean>} - Whether the lock was acquired.
+   */
+  async tryAcquire() {
+    try {
+      await fs.mkdir(this.lockPath)
+    } catch (error) {
+      if (/**
+           * Narrows the runtime value to the documented type.
+            @type {{code?: string}} */ (error).code === "EEXIST") return false
+      throw error
+    }
+
+    try {
+      await this.writeOwnerMetadata()
+      this.acquired = true
+
+      return true
+    } catch (error) {
+      await fs.rm(this.lockPath, {recursive: true, force: true})
+      throw error
+    }
+  }
+
+  /**
+   * Releases the held HTTP server lock directory.
+   * @returns {Promise<void>} - Resolves after best-effort lock release.
+   */
+  async release() {
+    if (!this.acquired) return
+
+    this.acquired = false
+    await fs.rm(this.lockPath, {recursive: true, force: true})
+  }
+
+  /**
+   * Writes metadata used to explain or reclaim an existing server lock.
+   * @returns {Promise<void>} - Resolves after owner metadata has been written.
+   */
+  async writeOwnerMetadata() {
+    await fs.writeFile(path.join(this.lockPath, "owner.json"), JSON.stringify({
+      acquiredAt: new Date().toISOString(),
+      host: this.host,
+      hostname: os.hostname(),
+      pid: process.pid,
+      port: this.port
+    }))
+  }
+
+  /**
+   * Checks whether the current lock owner is a dead process on this host.
+   * @returns {Promise<boolean>} - Whether the existing lock belongs to a dead process.
+   */
+  async isStale() {
+    const owner = await this.readOwnerMetadata()
+
+    if (!this.isLocalProcessOwner(owner)) return false
+
+    return this.processIsDead(/**
+                               * Narrows the runtime value to the documented type.
+                                @type {{pid: number}} */ (owner).pid)
+  }
+
+  /**
+   * Runs is local process owner.
+   * @param {Record<string, ?> | null} owner - Existing lock owner metadata.
+   * @returns {boolean} - Whether owner metadata names a local process.
+   */
+  isLocalProcessOwner(owner) {
+    if (!owner) return false
+    if (typeof owner.pid !== "number") return false
+
+    return this.ownerHostnameMatches(owner)
+  }
+
+  /**
+   * Runs owner hostname matches.
+   * @param {Record<string, ?>} owner - Existing lock owner metadata.
+   * @returns {boolean} - Whether the owner hostname is local or absent.
+   */
+  ownerHostnameMatches(owner) {
+    if (!owner.hostname) return true
+    if (owner.hostname === os.hostname()) return true
+
+    return false
+  }
+
+  /**
+   * Runs process is dead.
+   * @param {number} pid - Process id.
+   * @returns {boolean} - Whether the process no longer exists.
+   */
+  processIsDead(pid) {
+    try {
+      process.kill(pid, 0)
+
+      return false
+    } catch (error) {
+      return /** Narrows the runtime value to the documented type. @type {{code?: string}} */ (error).code === "ESRCH"
+    }
+  }
+
+  /**
+   * Reads owner metadata from an existing server lock directory.
+   * @returns {Promise<Record<string, ?> | null>} - Parsed owner metadata, when readable.
+   */
+  async readOwnerMetadata() {
+    try {
+      const rawOwner = await fs.readFile(path.join(this.lockPath, "owner.json"), "utf8")
+
+      return /** Narrows the runtime value to the documented type. @type {Record<string, ?>} */ (JSON.parse(rawOwner))
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Builds a duplicate-server error message with owner details when available.
+   * @returns {Promise<string>} - Error message explaining which server owns the lock.
+   */
+  async lockHeldMessage() {
+    const owner = await this.readOwnerMetadata()
+    const details = owner
+      ? `PID ${String(owner.pid)} on ${String(owner.hostname)} (${String(owner.host)}:${String(owner.port)})`
+      : `lock directory ${this.lockPath}`
+
+    return `A Velocious HTTP server is already running for this application (${details}). Remove ${this.lockPath} if the server is no longer running.`
+  }
+}

package/src/http-server/websocket-channel-subscribers.js

@@ -0,0 +1,110 @@
+// @ts-check
+
+/**
+ * Per-process registry of channel subscribers used by worker code that
+ * needs to react to events broadcast via `websocketEventsHost.publish(...)`
+ * without holding an actual websocket session.
+ *
+ * Each Velocious worker thread (and the in-process handler used in tests)
+ * gets its own instance attached to the configuration via
+ * `setWebsocketChannelSubscribers(...)`.
+ */
+export default class VelociousWebsocketChannelSubscribers {
+  constructor() {
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {Map<string, Set<(payload: ?, meta: {channel: string, createdAt?: string, eventId?: string}) => void | Promise<void>>>} */
+    this._subscribers = new Map()
+  }
+
+  /**
+   * Runs subscribe.
+   * @param {string} channel - Channel name to subscribe to.
+   * @param {(payload: ?, meta: {channel: string, createdAt?: string, eventId?: string}) => void | Promise<void>} callback - Callback invoked for each event on the channel.
+   * @returns {() => void} - Unsubscribe function.
+   */
+  subscribe(channel, callback) {
+    if (!channel) throw new Error("channel is required")
+    if (typeof callback !== "function") throw new Error("callback must be a function")
+
+    let set = this._subscribers.get(channel)
+
+    if (!set) {
+      set = new Set()
+      this._subscribers.set(channel, set)
+    }
+
+    set.add(callback)
+
+    return () => this.unsubscribe(channel, callback)
+  }
+
+  /**
+   * Runs unsubscribe.
+   * @param {string} channel - Channel name.
+   * @param {(payload: ?, meta: {channel: string, createdAt?: string, eventId?: string}) => void | Promise<void>} callback - Previously registered callback.
+   * @returns {void}
+   */
+  unsubscribe(channel, callback) {
+    const set = this._subscribers.get(channel)
+
+    if (!set) return
+
+    set.delete(callback)
+
+    if (set.size === 0) {
+      this._subscribers.delete(channel)
+    }
+  }
+
+  /**
+   * Runs has subscribers.
+   * @param {string} channel - Channel name.
+   * @returns {boolean} - Whether any subscribers exist for the channel.
+   */
+  hasSubscribers(channel) {
+    const set = this._subscribers.get(channel)
+
+    return Boolean(set && set.size > 0)
+  }
+
+  /**
+   * Dispatch an event to all subscribers of the channel.
+   * @param {object} args - Event args.
+   * @param {string} args.channel - Channel name.
+   * @param {?} args.payload - Event payload.
+   * @param {string} [args.createdAt] - Event creation time.
+   * @param {string} [args.eventId] - Event identifier.
+   * @returns {Promise<void>} - Resolves when all subscribers have completed.
+   */
+  async dispatch({channel, payload, createdAt, eventId}) {
+    const set = this._subscribers.get(channel)
+
+    if (!set || set.size === 0) return
+
+    // Snapshot the subscribers so callbacks that unsubscribe (themselves or
+    // others) during dispatch do not skip later deliveries for this event.
+    const callbacks = Array.from(set)
+    const meta = {channel, createdAt, eventId}
+    const tasks = []
+
+    for (const callback of callbacks) {
+      try {
+        const result = callback(payload, meta)
+
+        if (result && typeof (/**
+                               * Narrows the runtime value to the documented type.
+                                @type {Promise<void>} */ (result)).then === "function") {
+          tasks.push(/**
+                      * Narrows the runtime value to the documented type.
+                       @type {Promise<void>} */ (result))
+        }
+      } catch (error) {
+        // Don't let one subscriber's failure abort the others; surface via the returned promises instead.
+        tasks.push(Promise.reject(error))
+      }
+    }
+
+    await Promise.all(tasks)
+  }
+}

package/src/http-server/websocket-channel.js

@@ -0,0 +1,137 @@
+// @ts-check
+
+/**
+ * WebsocketJsonValue type.
+ * @typedef {null | boolean | number | string | object} WebsocketJsonValue
+ */
+/**
+ * WebsocketParams type.
+ * @typedef {Record<string, WebsocketJsonValue>} WebsocketParams
+ */
+
+/**
+ * Base class for app-defined 1:N pub/sub channels.
+ *
+ * Subclasses override:
+ *  - `canSubscribe()` — subscribe-time auth (default `false`).
+ *  - `subscribed()` / `unsubscribed()` — optional lifecycle hooks.
+ *  - `matches(broadcastParams)` — broadcast routing filter.
+ */
+export default class VelociousWebsocketChannel {
+  /**
+   * Runs constructor.
+   * @param {object} args
+   * @param {string} args.subscriptionId - Client-assigned id, unique within the session.
+   * @param {WebsocketParams} args.params - Subscribe params.
+   * @param {import("./client/websocket-session.js").default} args.session - Owning session.
+   */
+  constructor({subscriptionId, params, session}) {
+    this.subscriptionId = subscriptionId
+    this.params = params || {}
+    this.session = session
+    this._closed = false
+  }
+
+  /**
+   * Subscribe-time auth. Default is `false` (deny). Channel authors
+   * MUST override to allow subscriptions. Returning a Promise defers
+   * the `channel-subscribed` confirmation until it resolves.
+   * @returns {boolean | Promise<boolean>}
+   */
+  canSubscribe() { return false }
+
+  /**
+   * Optional — called once after `canSubscribe` resolves truthy and
+   * before `channel-subscribed` is sent to the client. Use for
+   * initial snapshot delivery.
+   * @returns {void | Promise<void>}
+   */
+  subscribed() {}
+
+  /**
+   * Optional — called once when the subscription ends. Fires on
+   * client-initiated `channel-unsubscribe` or on session teardown.
+   * @returns {void | Promise<void>}
+   */
+  unsubscribed() {}
+
+  /**
+   * Called when the underlying socket drops and the session is
+   * moved into the paused/grace registry. Either `onResume` fires
+   * on successful client reconnect, or `unsubscribed()` fires when
+   * the grace window expires.
+   * @returns {void | Promise<void>}
+   */
+  onDisconnect() {}
+
+  /**
+   * Called after a client reconnect + `session-resume` rebinds this
+   * subscription to a new socket.
+   * @returns {void | Promise<void>}
+   */
+  onResume() {}
+
+  /**
+   * Called when the client sends updated metadata (e.g. after
+   * sign-in / locale change). Override to react to session-level
+   * metadata updates.
+   * @param {WebsocketParams} _metadata - Updated metadata.
+   * @returns {void | Promise<void>}
+   */
+  onMetadataChanged(_metadata) {}
+
+  /**
+   * Broadcast routing filter. Called by `broadcastToChannel` for
+   * each live subscription — returning true delivers the body via
+   * `sendMessage`. Default matches all broadcasts regardless of
+   * params; override for per-subscriber filtering.
+   * @param {...WebsocketJsonValue} _broadcastArgs - Params forwarded from `broadcastToChannel` (ignored by default).
+   * @returns {boolean} - True to deliver the broadcast to this subscriber.
+   */
+  matches(..._broadcastArgs) { return true }
+
+  /**
+   * Returns sanitized diagnostics for debug snapshots.
+   * Subclasses can override to expose non-sensitive routing details.
+   * @returns {Record<string, ?>} Debug-safe subscription details.
+   */
+  debugSnapshot() { return {} }
+
+  /**
+   * Delivers a matched broadcast to this subscriber. Subclasses can
+   * override when the outbound body must be tailored to subscription
+   * params before sending.
+   * @param {WebsocketJsonValue} body
+   * @param {{eventId?: string}} [meta] - Optional event metadata.
+   * @returns {void | Promise<void>}
+   */
+  deliverBroadcast(body, meta) {
+    this.sendMessage(body, meta)
+  }
+
+  /**
+   * Sends a `channel-message` frame to THIS subscriber only.
+   * When `meta.eventId` is provided, the client receives it so it
+   * can track its checkpoint for `lastEventId` replay on reconnect.
+   * @param {WebsocketJsonValue} body
+   * @param {{eventId?: string}} [meta] - Optional event metadata.
+   * @returns {void}
+   */
+  sendMessage(body, meta) {
+    if (this._closed) {
+      throw new Error(`Cannot sendMessage on closed subscription ${this.subscriptionId}`)
+    }
+
+    this.session.sendJson({
+      type: "channel-message",
+      subscriptionId: this.subscriptionId,
+      body,
+      ...(meta?.eventId ? {eventId: meta.eventId} : {})
+    })
+  }
+
+  /**
+   * Runs is closed.
+    @returns {boolean} */
+  isClosed() { return this._closed }
+}