velocious 1.0.430 → 1.0.432

package/src/http-server/websocket-events-host.js

@@ -0,0 +1,170 @@
+// @ts-check
+
+import {websocketEventLogStoreForConfiguration} from "./websocket-event-log-store.js"
+
+export class VelociousHttpServerWebsocketEventsHost {
+  constructor() {
+    /**
+     * Narrows the runtime value to the documented type.
+      @type {Set<import("./worker-handler/index.js").default>} */
+    this.handlers = new Set()
+    this.publishQueue = Promise.resolve()
+  }
+
+  /**
+   * Returns a promise that resolves when all pending publish/broadcast
+   * operations have completed (including event-log persistence). Useful
+   * when a request handler needs to guarantee its broadcast is persisted
+   * before responding — without this, the HTTP response can return before
+   * the async event-log write finishes.
+   * @returns {Promise<void>}
+   */
+  async awaitPendingBroadcasts() {
+    await this.publishQueue
+  }
+
+  /**
+   * Runs register.
+   * @param {import("./worker-handler/index.js").default} handler - Handler instance.
+   * @returns {() => void} - The register.
+   */
+  register(handler) {
+    this.handlers.add(handler)
+
+    return () => this.handlers.delete(handler)
+  }
+
+  /**
+   * Runs publish.
+   * @param {object | string} channelOrArgs - Channel name or options object.
+   * @param {?} [payloadArg] - Payload data when channel is passed separately.
+   * @returns {void} - No return value.
+   */
+  publish(channelOrArgs, payloadArg) {
+    const publishArgs = typeof channelOrArgs === "string"
+      ? {channel: channelOrArgs, payload: payloadArg}
+      : /**
+         * Narrows the runtime value to the documented type.
+          @type {{channel: string, payload: ?}} */ (channelOrArgs)
+    const channel = publishArgs.channel
+    const payload = publishArgs.payload
+
+    this._queuePublish(async () => {
+      const persistedEvent = await this._persistEventIfNeeded({channel, payload})
+
+      for (const handler of this.handlers) {
+        handler.dispatchWebsocketEvent({
+          channel,
+          createdAt: persistedEvent?.createdAt,
+          eventId: persistedEvent?.id,
+          payload
+        })
+      }
+    }, "Failed to publish websocket event")
+  }
+
+  /**
+   * Fan a V2 channel broadcast out to every registered worker handler.
+   * Persists the event to the event-log store (if the channel is marked
+   * interested) so clients can resume from a `lastEventId` checkpoint.
+   * @param {object} args - Options object.
+   * @param {string} args.channel - Channel name.
+   * @param {Record<string, ?>} args.broadcastParams - Routing filter params.
+   * @param {?} args.body - Message body.
+   * @returns {void}
+   */
+  broadcastV2({body, broadcastParams, channel}) {
+    // Chain onto publishQueue so persistence completes before
+    // the next broadcast — without this, a subscriber that connects
+    // immediately after a broadcast could miss the just-persisted
+    // event when replaying from lastEventId on a slow DB.
+    this._queuePublish(async () => {
+      const persistedEvent = await this._persistV2EventIfNeeded({body, channel})
+
+      for (const handler of this.handlers) {
+        handler.dispatchWebsocketV2Broadcast({
+          body,
+          broadcastParams,
+          channel,
+          eventId: persistedEvent?.id,
+          createdAt: persistedEvent?.createdAt
+        })
+      }
+    }, "Failed to persist/broadcast V2 event")
+  }
+
+  /**
+   * Runs queue publish.
+   * @param {() => Promise<void>} callback - Publish work to run in order.
+   * @param {string} errorMessage - Message logged when publish work fails.
+   * @returns {void}
+   */
+  _queuePublish(callback, errorMessage) {
+    const handler = this.handlers.values().next().value
+    const configuration = handler?.configuration
+
+    this.publishQueue = this.publishQueue
+      .then(async () => {
+        if (configuration) {
+          return await configuration.withoutCurrentConnectionContexts(callback)
+        }
+
+        return await callback()
+      })
+      .catch((error) => {
+        console.error(errorMessage, error)
+        throw error
+      })
+  }
+
+  /**
+   * Runs persist v2 event if needed.
+   * @param {object} args - Options.
+   * @param {?} args.body - Event body.
+   * @param {string} args.channel - Channel name.
+   * @returns {Promise<{createdAt: string, id: string} | null>}
+   */
+  async _persistV2EventIfNeeded({body, channel}) {
+    return await this._persistChannelEventIfNeeded({channel, payload: body})
+  }
+
+  /**
+   * Runs persist event if needed.
+   * @param {object} args - Options object.
+   * @param {string} args.channel - Channel name.
+   * @param {?} args.payload - Payload data.
+   * @returns {Promise<{createdAt: string, id: string} | null>} - Persisted event metadata.
+   */
+  async _persistEventIfNeeded({channel, payload}) {
+    return await this._persistChannelEventIfNeeded({channel, payload})
+  }
+
+  /**
+   * Runs persist channel event if needed.
+   * @param {object} args - Options object.
+   * @param {string} args.channel - Channel name.
+   * @param {?} args.payload - Payload data.
+   * @returns {Promise<{createdAt: string, id: string} | null>} - Persisted event metadata.
+   */
+  async _persistChannelEventIfNeeded({channel, payload}) {
+    const handler = this.handlers.values().next().value
+
+    if (!handler?.configuration) return null
+
+    const websocketEventLogStore = websocketEventLogStoreForConfiguration(handler.configuration)
+    const shouldPersist = await websocketEventLogStore.shouldPersistChannel(channel)
+
+    if (!shouldPersist) return null
+
+    const persistedEvent = await websocketEventLogStore.appendEvent({channel, payload})
+
+    return {
+      createdAt: persistedEvent.createdAt,
+      id: persistedEvent.id
+    }
+  }
+}
+
+const websocketEventsHost = new VelociousHttpServerWebsocketEventsHost()
+
+export default websocketEventsHost

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

@@ -0,0 +1,50 @@
+// @ts-check
+
+export default class VelociousHttpServerWebsocketEvents {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {import("worker_threads").parentPort} args.parentPort - Parent port.
+   * @param {number} args.workerCount - Worker count.
+   */
+  constructor({parentPort, workerCount}) {
+    this.parentPort = parentPort
+    this.workerCount = workerCount
+  }
+
+  /**
+   * Runs publish.
+   * @param {string} channel - Channel name.
+   * @param {?} payload - Payload data.
+   * @returns {void} - No return value.
+   */
+  publish(channel, payload) {
+    if (!channel) throw new Error("channel is required")
+    if (!this.parentPort) throw new Error("parentPort is required")
+
+    this.parentPort.postMessage({channel, command: "websocketPublish", payload, workerCount: this.workerCount})
+  }
+
+  /**
+   * Fan-out entry point for `configuration.broadcastToChannel` on V2
+   * channels. The worker posts to the main process, which fans out to
+   * every worker so subscribers on any worker receive the broadcast.
+   * @param {object} args - Options object.
+   * @param {string} args.channel - Channel name.
+   * @param {Record<string, ?>} args.broadcastParams - Filter params forwarded to `matches()`.
+   * @param {?} args.body - Message body delivered via `sendMessage()`.
+   * @returns {void}
+   */
+  publishV2Broadcast({channel, broadcastParams, body}) {
+    if (!channel) throw new Error("channel is required")
+    if (!this.parentPort) throw new Error("parentPort is required")
+
+    this.parentPort.postMessage({
+      body,
+      broadcastParams,
+      channel,
+      command: "websocketV2Broadcast",
+      workerCount: this.workerCount
+    })
+  }
+}

package/src/http-server/worker-handler/channel-subscriber-dispatch.js

@@ -0,0 +1,28 @@
+// @ts-check
+
+/**
+ * Runs dispatch channel subscribers.
+ * @param {object} args - Dispatch arguments.
+ * @param {string} args.channel - Channel name.
+ * @param {string | undefined} args.createdAt - Event creation timestamp.
+ * @param {string | undefined} args.eventId - Event identifier.
+ * @param {import("../../configuration.js").default} args.configuration - Configuration instance.
+ * @param {import("../../logger.js").default} args.logger - Logger for isolated subscriber failures.
+ * @param {?} args.payload - Broadcast payload.
+ * @returns {Promise<void>} Resolves after subscribers have been attempted.
+ */
+export default async function dispatchChannelSubscribers({channel, configuration, createdAt, eventId, logger, payload}) {
+  try {
+    await configuration.getWebsocketChannelSubscribers().dispatch({channel, createdAt, eventId, payload})
+  } catch (error) {
+    logger.error(() => [`Channel subscriber dispatch failed for ${channel}`, error])
+
+    const errorPayload = {
+      context: {channel, createdAt, eventId, source: "websocket-channel-subscribers"},
+      error
+    }
+
+    configuration.getErrorEvents().emit("framework-error", errorPayload)
+    configuration.getErrorEvents().emit("all-error", {...errorPayload, errorType: "framework-error"})
+  }
+}

package/src/http-server/worker-handler/in-process.js

@@ -0,0 +1,155 @@
+// @ts-check
+
+import Client from "../client/index.js"
+import dispatchChannelSubscribers from "./channel-subscriber-dispatch.js"
+import Logger from "../../logger.js"
+import websocketEventsHost from "../websocket-events-host.js"
+
+/**
+ * In-process worker handler that processes HTTP requests in the main thread
+ * instead of spawning a Worker thread. This allows the test runner's database
+ * connection context to be shared with HTTP request handlers, so model-created
+ * records in tests are visible to HTTP endpoints.
+ */
+export default class VelociousHttpServerInProcessHandler {
+  /**
+   * 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, {httpClient: Client, serverClient: import("../server-client.js").default}>} */
+    this.clients = {}
+
+    this.logger = new Logger(this)
+    this.workerCount = workerCount
+    this.unregisterFromEventsHost = websocketEventsHost.register(/**
+                                                                  * Narrows the runtime value to the documented type.
+                                                                   @type {?} */ (this))
+    this._stopping = false
+  }
+
+  /**
+   * Runs start.
+    @returns {Promise<void>} */
+  async start() {
+    await this.logger.debug(() => `In-process handler ${this.workerCount} started`)
+  }
+
+  /**
+   * Runs add socket connection.
+   * @param {import("../server-client.js").default} serverClient - Server client instance.
+   * @returns {void}
+   */
+  addSocketConnection(serverClient) {
+    const clientCount = serverClient.clientCount
+
+    const httpClient = new Client({
+      clientCount,
+      configuration: this.configuration,
+      remoteAddress: serverClient.remoteAddress
+    })
+
+    httpClient.events.on("output", (output) => {
+      if (output !== null && output !== undefined) {
+        void serverClient.send(output).catch((error) => {
+          this.logger.error(() => ["Failed to deliver client output", {clientCount}, error])
+        })
+      }
+    })
+
+    httpClient.events.on("close", () => {
+      void serverClient.end()
+      delete this.clients[clientCount]
+    })
+
+    this.clients[clientCount] = {httpClient, serverClient}
+
+    // Create a message-port shim so ServerClient.onSocketData can route data
+    // to the in-process HTTP Client without needing a real worker thread.
+    const messagePortShim = /**
+                             * Narrows the runtime value to the documented type.
+                              @type {import("worker_threads").Worker} */ (/**
+                                                                           * Narrows the runtime value to the documented type.
+                                                                            @type {?} */ ({
+      postMessage: (/**
+                     * Narrows the runtime value to the documented type.
+                      @type {{command: string, chunk?: Buffer | Uint8Array | string, clientCount?: number}} */ data) => {
+        if (data.command === "clientWrite" && data.chunk) {
+          const chunk = typeof data.chunk === "string" ? Buffer.from(data.chunk) : Buffer.from(data.chunk)
+
+          httpClient.onWrite(chunk)
+        }
+      }
+    }))
+
+    serverClient.setWorker(messagePortShim)
+    serverClient.listen()
+  }
+
+  /**
+   * Runs stop.
+    @returns {Promise<void>} */
+  async stop() {
+    this._stopping = true
+
+    for (const {serverClient} of Object.values(this.clients)) {
+      try {
+        void serverClient.end()
+      } catch (error) {
+        this.logger.warn("Failed to close client during shutdown", error)
+      }
+    }
+
+    this.clients = {}
+    this.unregisterFromEventsHost?.()
+  }
+
+  /**
+   * In-process handler path for V2 channel broadcasts. No worker
+   * boundary to cross — dispatch directly to any matching live
+   * subscriptions on the shared configuration.
+   * @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.
+   * @returns {void}
+   */
+  dispatchWebsocketV2Broadcast({body, broadcastParams, channel, eventId}) {
+    if (!this.configuration) return
+
+    return this.configuration._broadcastToChannelLocal(channel, broadcastParams, body, {eventId})
+  }
+
+  /**
+   * 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}
+   */
+  dispatchWebsocketEvent({channel, createdAt, eventId, payload}) {
+    for (const {httpClient} of Object.values(this.clients)) {
+      const session = httpClient.websocketSession
+
+      if (!session) continue
+
+      void session.sendEvent(channel, payload, {createdAt, eventId})
+    }
+
+    if (this.configuration) {
+      // Isolate subscriber failures from breaking the in-process handler,
+      // but still surface them to the framework error events so bug
+      // reporters can pick them up.
+      void dispatchChannelSubscribers({channel, configuration: this.configuration, createdAt, eventId, logger: this.logger, payload})
+    }
+  }
+}