velocious 1.0.667 → 1.0.668

package/src/environment-handlers/node/cli/commands/test.js

@@ -1,19 +1,22 @@
 // @ts-check
 
 import BaseCommand from "../../../../cli/base-command.js"
-import fs from "fs/promises"
 import path from "node:path"
 import picocolors from "picocolors"
 import TestFilesFinder from "../../../../testing/test-files-finder.js"
 import TestProfiler from "../../../../testing/test-profiler.js"
-import { formatTestProfileSummary, writeTestProfileOutputs } from "../../../../testing/test-profile-output.js"
+import {
+  formatTestProfileSummary,
+  loadTimingManifest,
+  resolveTestProfileOptions,
+  writeTestProfileOutputs
+} from "../../../../testing/test-profile-output.js"
 import TestRunner from "../../../../testing/test-runner.js"
 import TestSuiteSplitter from "../../../../testing/test-suite-splitter.js"
 import { normalizeExamplePatterns, parseFilters } from "../../../../testing/test-filter-parser.js"
 import {
   canonicalTimingManifestPath,
-  timingManifestFileSetHash,
-  validateTimingManifest
+  timingManifestFileSetHash
 } from "../../../../testing/timing-manifest.js"
 import { prepareSourcePeerPackage } from "../../source-peer-package.js"
 
@@ -44,8 +47,11 @@ export default class VelociousCliCommandsTest extends BaseCommand {
       groupNumber,
       profile,
       profileJsonPath,
+      retries,
+      setupFiles,
       timingManifestPath,
-      timingManifestOutputPath
+      timingManifestOutputPath,
+      timeoutMs
     } = parseFilters(this.processArgs || [])
     const profileOptions = resolveTestProfileOptions({
       cwd: process.cwd(),
@@ -70,7 +76,7 @@ export default class VelociousCliCommandsTest extends BaseCommand {
 
     /**
      * Finalizes requested outputs once for every command outcome.
-     * @param {string} status - Run status.
+     * @param {import("@velocious/testing/node").TestProfileStatus} status - Run status.
      * @returns {Promise<void>} - Resolves after requested outputs are written.
      */
     const finalizeProfile = async (status) => {
@@ -157,7 +163,10 @@ export default class VelociousCliCommandsTest extends BaseCommand {
         testFiles,
         lineFilters: testFilesFinder.getLineFiltersByFile(),
         examplePatterns: normalizeExamplePatterns(examplePatterns),
-        profiler
+        profiler,
+        retries,
+        setupFiles: setupFiles.map((setupFile) => path.resolve(process.cwd(), setupFile)),
+        timeoutMs
       })
       const activeTestRunner = testRunner
       let signalHandled = false
@@ -272,68 +281,7 @@ export default class VelociousCliCommandsTest extends BaseCommand {
   }
 }
 
-/**
- * Resolves and validates profiling paths before test discovery starts.
- * @param {object} args - Raw profiling options.
- * @param {string} args.cwd - Command working directory.
- * @param {boolean} args.profile - Whether console profiling was requested.
- * @param {string} [args.profileJsonPath] - Rich profile output path.
- * @param {string} [args.timingManifestPath] - Timing manifest input path.
- * @param {string} [args.timingManifestOutputPath] - Timing manifest output path.
- * @returns {{profile: boolean, profileJsonPath: string | undefined, timingManifestPath: string | undefined, timingManifestOutputPath: string | undefined}} - Resolved profiling options.
- */
-export function resolveTestProfileOptions({cwd, profile, profileJsonPath, timingManifestPath, timingManifestOutputPath}) {
-  const resolvedProfileJsonPath = profileJsonPath ? path.resolve(cwd, profileJsonPath) : undefined
-  const resolvedTimingManifestPath = timingManifestPath ? path.resolve(cwd, timingManifestPath) : undefined
-  const resolvedTimingManifestOutputPath = timingManifestOutputPath
-    ? path.resolve(cwd, timingManifestOutputPath)
-    : undefined
-
-  if (resolvedProfileJsonPath && resolvedTimingManifestOutputPath && resolvedProfileJsonPath === resolvedTimingManifestOutputPath) {
-    throw new Error("Test profiling output paths must be different")
-  }
-
-  if (resolvedTimingManifestPath && (
-    resolvedProfileJsonPath === resolvedTimingManifestPath ||
-    resolvedTimingManifestOutputPath === resolvedTimingManifestPath
-  )) {
-    throw new Error("Test profiling outputs must not overwrite --timing-manifest input")
-  }
-
-  return {
-    profile: profile || Boolean(resolvedProfileJsonPath || resolvedTimingManifestOutputPath),
-    profileJsonPath: resolvedProfileJsonPath,
-    timingManifestPath: resolvedTimingManifestPath,
-    timingManifestOutputPath: resolvedTimingManifestOutputPath
-  }
-}
-
-/**
- * Loads and validates an explicitly supplied plain JSON timing manifest.
- * @param {string | undefined} timingManifestPath - Timing manifest path.
- * @returns {Promise<Record<string, number> | undefined>} - Canonical manifest, or undefined when not requested.
- */
-export async function loadTimingManifest(timingManifestPath) {
-  if (!timingManifestPath) return undefined
-
-  let content
-
-  try {
-    content = await fs.readFile(timingManifestPath, "utf8")
-  } catch (error) {
-    throw new Error(`Failed to read timing manifest: ${timingManifestPath}`, {cause: error})
-  }
-
-  let parsed
-
-  try {
-    parsed = JSON.parse(content)
-  } catch (error) {
-    throw new Error(`Failed to parse timing manifest: ${timingManifestPath}`, {cause: error})
-  }
-
-  return validateTimingManifest(parsed, {source: `Timing manifest ${timingManifestPath}`})
-}
+export { loadTimingManifest, resolveTestProfileOptions }
 
 /**
  * Resolves how many slowest tests to report from the `VELOCIOUS_SLOW_TEST_COUNT`

package/src/frontend-models/websocket-channel.js

@@ -389,6 +389,24 @@ export default class FrontendModelWebsocketChannel extends VelociousWebsocketCha
     return broadcastParams?.model === this._modelName()
   }
 
+  /**
+   * Drops the server-only destroy-authorization snapshot before replay
+   * persistence. The snapshot is what makes replayed destroy events
+   * require a client resync, and the pre-delete row it captures must
+   * never be stored.
+   * @param {Record<string, import("./query.js").FrontendModelTransportValue> | null | undefined} broadcastParams - Params from `broadcastToChannel`.
+   * @returns {Record<string, import("./query.js").FrontendModelTransportValue> | null} - Persistable routing params.
+   */
+  static replayableBroadcastParams(broadcastParams) {
+    if (!broadcastParams) return null
+
+    const replayableParams = {...broadcastParams}
+
+    delete replayableParams.destroyAuthorizationRecord
+
+    return replayableParams
+  }
+
   /**
    * Runs debug snapshot.
    * @returns {Record<string, ReturnType<typeof JSON.parse>>} Debug-safe subscription details.

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

@@ -1843,8 +1843,13 @@ export default class VelociousHttpServerClientWebsocketSession {
 
   /**
    * Replays missed events from the persistent event-log store for a
-   * channel subscription that provided `lastEventId`. Sends each
-   * missed event as a `channel-message` with `replayed: true`.
+   * channel subscription that provided `lastEventId`. Delivery is
+   * stream-scoped: each persisted event's broadcast params are
+   * re-applied through the subscription's `matches()` — the same routing
+   * decision live delivery uses — so the subscription only replays events
+   * from its own stream of the channel. A checkpoint that belongs to a
+   * different stream (or is no longer retained) yields
+   * `channel-replay-gap` instead of cross-stream replay.
    * @param {object} args - Options.
    * @param {string} args.channelType - Channel type name (event-log key).
    * @param {string} args.lastEventId - Client's last-seen event id.
@@ -1858,7 +1863,7 @@ export default class VelociousHttpServerClientWebsocketSession {
 
     const checkpoint = await store.getEventById({channel: channelType, id: lastEventId})
 
-    if (!checkpoint) {
+    if (!checkpoint || !this._replayEventMatchesSubscription({channelType, event: checkpoint, subscription})) {
       this.sendJson({
         type: "channel-replay-gap",
         subscriptionId: subscription.subscriptionId,
@@ -1880,6 +1885,8 @@ export default class VelociousHttpServerClientWebsocketSession {
     for (const event of events) {
       if (subscription.isClosed()) break
 
+      if (!this._replayEventMatchesSubscription({channelType, event, subscription})) continue
+
       if (await subscription._requiresReplayGap(event.payload)) {
         this.sendJson({
           type: "channel-replay-gap",
@@ -1891,11 +1898,41 @@ export default class VelociousHttpServerClientWebsocketSession {
 
       await subscription.deliverBroadcast(
         /** @type {import("../websocket-channel.js").WebsocketJsonValue} */ (event.payload),
-        {eventId: event.id}
+        {
+          ...(event.params !== null ? {broadcastParams: event.params} : {}),
+          eventId: event.id
+        }
       )
     }
   }
 
+  /**
+   * Whether a persisted replay event belongs to this subscription's
+   * stream. A `matches()` failure means the stream membership cannot be
+   * proven, so the event is treated as not matching — the same isolation
+   * live delivery applies to a broken `matches()`.
+   * @param {object} args - Options.
+   * @param {string} args.channelType - Channel type name.
+   * @param {{params: Record<string, ReturnType<typeof JSON.parse>> | null}} args.event - Persisted replay event.
+   * @param {import("../websocket-channel.js").default} args.subscription - Live subscription.
+   * @returns {boolean} - Whether the event belongs to the subscription's stream.
+   */
+  _replayEventMatchesSubscription({channelType, event, subscription}) {
+    try {
+      return Boolean(subscription.matches(event.params || {}))
+    } catch (caughtError) {
+      const error = this._reportUnexpectedDispatchError(caughtError, {
+        channelType,
+        stage: "websocket-channel-replay",
+        subscriptionId: subscription.subscriptionId
+      })
+
+      this.logger.error(() => [`Websocket replay subscription ${subscription.subscriptionId} matches() threw`, error])
+
+      return false
+    }
+  }
+
   /**
    * Handles `{type: "channel-unsubscribe"}` from the client — calls
    * `unsubscribed()` and sends `channel-unsubscribed`.

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

@@ -94,6 +94,20 @@ export default class VelociousWebsocketChannel {
    */
   matches(..._broadcastArgs) { return true }
 
+  /**
+   * Returns the broadcast params that may be persisted for replay.
+   * Persisted params are re-applied through `matches(broadcastParams)`
+   * when replaying missed events, so they must be JSON-serializable and
+   * safe to store. Override when `broadcastParams` carries server-only
+   * values that must never reach the event log (e.g. authorization
+   * snapshots).
+   * @param {WebsocketParams | null | undefined} broadcastParams - Params passed to `broadcastToChannel`.
+   * @returns {WebsocketParams | null} - Params to persist, or null to store none.
+   */
+  static replayableBroadcastParams(broadcastParams) {
+    return broadcastParams ?? null
+  }
+
   /**
    * Whether replaying a persisted broadcast would require a client resync.
    * Subclasses override this when replay storage deliberately omits metadata

package/src/http-server/websocket-event-log-store.js

@@ -11,6 +11,7 @@ import Logger from "../logger.js"
  * @property {Date | string} created_at - Creation time.
  * @property {string} id - Event id.
  * @property {string} payload_json - Serialized payload.
+ * @property {string | null} params_json - Serialized broadcast params, or null when the publish carried none.
  * @property {number | string} sequence - Sequence number.
  */
 /**
@@ -18,6 +19,16 @@ import Logger from "../logger.js"
  * @typedef {object} WebsocketReplayChannelRow
  * @property {string} channel - Channel name.
  */
+/**
+ * Normalized persisted websocket event.
+ * @typedef {object} WebsocketPersistedEvent
+ * @property {string} channel - Channel name.
+ * @property {string} createdAt - ISO creation time.
+ * @property {string} id - Event id.
+ * @property {Record<string, ReturnType<typeof JSON.parse>> | null} params - Persisted broadcast params, or null when the publish carried none.
+ * @property {ReturnType<typeof JSON.parse>} payload - Event payload.
+ * @property {number} sequence - Sequence number.
+ */
 const EVENTS_TABLE = "websocket_channel_events"
 const REPLAY_CHANNELS_TABLE = "websocket_replay_channels"
 const DEFAULT_RETENTION_MS = 10 * 60 * 1000
@@ -100,22 +111,40 @@ export default class VelociousHttpServerWebsocketEventLogStore {
 
   /**
    * Runs schema present.
-   * @returns {Promise<boolean>} - Whether both event-log tables physically exist.
+   * @returns {Promise<boolean>} - Whether both event-log tables exist and the events table carries every required column.
    */
   async _schemaPresent() {
     return await this._withDb(async (db) =>
-      await db.tableExists(EVENTS_TABLE) && await db.tableExists(REPLAY_CHANNELS_TABLE)
+      (await db.tableExists(EVENTS_TABLE) && await db.tableExists(REPLAY_CHANNELS_TABLE))
+      && (await this._columnPresent(db, EVENTS_TABLE, "params_json"))
     )
   }
 
+  /**
+   * Runs column present.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @param {string} tableName - Table name.
+   * @param {string} columnName - Column name.
+   * @returns {Promise<boolean>} - Whether the column exists on the table.
+   */
+  async _columnPresent(db, tableName, columnName) {
+    const tables = await db.getTables()
+    const table = tables.find((candidate) => candidate.getName() == tableName)
+
+    if (!table) return false
+
+    return (await table.getColumnByName(columnName)) !== undefined
+  }
+
   /**
    * Runs append event.
    * @param {object} args - Options.
    * @param {string} args.channel - Channel name.
    * @param {ReturnType<typeof JSON.parse>} args.payload - Event payload.
-   * @returns {Promise<{channel: string, createdAt: string, id: string, payload: ReturnType<typeof JSON.parse>}>} - Persisted event row.
+   * @param {Record<string, ReturnType<typeof JSON.parse>> | null} [args.params] - Broadcast params to persist for stream-scoped replay, or null when the publish carried none.
+   * @returns {Promise<WebsocketPersistedEvent>} - Persisted event row.
    */
-  async appendEvent({channel, payload}) {
+  async appendEvent({channel, params = null, payload}) {
     await this.ensureReady()
 
     const id = randomUUID()
@@ -128,10 +157,11 @@ export default class VelociousHttpServerWebsocketEventLogStore {
           channel,
           created_at: createdAt,
           id,
+          params_json: params === null ? null : JSON.stringify(params),
           payload_json: JSON.stringify(payload)
         }
       })
-      return {channel, createdAt: createdAt.toISOString(), id, payload}
+      return {channel, createdAt: createdAt.toISOString(), id, params, payload}
     })
   }
 
@@ -139,8 +169,13 @@ export default class VelociousHttpServerWebsocketEventLogStore {
    * Runs mark channel interested.
    * @param {string} channel - Channel name.
    * @returns {Promise<void>} - Resolves when the channel interest was persisted.
+   * @throws {Error} When the channel is registered live-only, which forbids replay persistence.
    */
   async markChannelInterested(channel) {
+    if (this.configuration.isWebsocketChannelLiveOnly(channel)) {
+      throw new Error(`Websocket channel "${channel}" is registered live-only and cannot be marked interested in replay persistence`)
+    }
+
     await this.ensureReady()
 
     const interestedUntil = new Date(Date.now() + this.retentionMs)
@@ -158,6 +193,12 @@ export default class VelociousHttpServerWebsocketEventLogStore {
    * @returns {Promise<boolean>} - Whether the channel should be persisted for replay.
    */
   async shouldPersistChannel(channel) {
+    // A channel re-registered live-only can still hold cached or durable
+    // interest state from before the re-registration; the live-only
+    // contract must hold at the persistence decision, not only at
+    // interest marking.
+    if (this.configuration.isWebsocketChannelLiveOnly(channel)) return false
+
     if (this._channelInterestCached(channel)) return true
     if (this._interestedChannels.size === 0) return false
 
@@ -197,7 +238,7 @@ export default class VelociousHttpServerWebsocketEventLogStore {
    * @param {object} args - Options.
    * @param {string} args.channel - Channel name.
    * @param {string} args.id - Event id.
-   * @returns {Promise<{channel: string, createdAt: string, id: string, payload: ReturnType<typeof JSON.parse>, sequence: number} | null>} - Event row or null.
+   * @returns {Promise<WebsocketPersistedEvent | null>} - Event row or null.
    */
   async getEventById({channel, id}) {
     await this.ensureReady()
@@ -237,7 +278,7 @@ export default class VelociousHttpServerWebsocketEventLogStore {
    * @param {string} args.channel - Channel name.
    * @param {number} args.sequence - Lower bound sequence.
    * @param {number | null | undefined} [args.upToSequence] - Inclusive ceiling sequence.
-   * @returns {Promise<Array<{channel: string, createdAt: string, id: string, payload: ReturnType<typeof JSON.parse>, sequence: number}>>} - Ordered events.
+   * @returns {Promise<WebsocketPersistedEvent[]>} - Ordered events.
    */
   async getEventsAfter({channel, sequence, upToSequence}) {
     await this.ensureReady()
@@ -312,24 +353,55 @@ export default class VelociousHttpServerWebsocketEventLogStore {
    * @returns {Promise<void>} - Resolves when complete.
    */
   async _ensureEventsTable(db) {
-    this.logger.info("Applying websocket event-log schema")
-
     if (await db.tableExists(EVENTS_TABLE)) {
-      this.logger.info("Websocket event-log table already exists - skipping create")
+      await this._ensureEventsTableColumns(db)
       return
     }
 
+    this.logger.info("Applying websocket event-log schema")
+
     const eventTable = new TableData(EVENTS_TABLE, {ifNotExists: true})
 
     eventTable.integer("sequence", {autoIncrement: true, null: false, primaryKey: true})
     eventTable.string("id", {index: true, null: false})
     eventTable.string("channel", {index: true, null: false})
+    eventTable.text("params_json", {null: true})
     eventTable.text("payload_json", {null: false})
     eventTable.datetime("created_at", {index: true, null: false})
 
     await db.createTable(eventTable)
   }
 
+  /**
+   * Adds columns the current schema requires to an events table created by an
+   * older framework version, so upgrades keep working without a manual ALTER.
+   * @param {import("../database/drivers/base.js").default} db - Database connection.
+   * @returns {Promise<void>} - Resolves when the events table schema is current.
+   */
+  async _ensureEventsTableColumns(db) {
+    if (await this._columnPresent(db, EVENTS_TABLE, "params_json")) return
+
+    this.logger.info("Adding params_json column to websocket event-log table")
+
+    const tableData = new TableData(EVENTS_TABLE)
+
+    tableData.addColumn("params_json", {isNewColumn: true, null: true, type: "text"})
+
+    try {
+      for (const sql of await db.alterTableSQLs(tableData)) {
+        await db.query(sql)
+      }
+    } catch (error) {
+      // A concurrent process can add the column between the presence check
+      // and the ALTER (multi-worker or rolling upgrade); the
+      // duplicate-column failure is then the expected outcome, not a real
+      // error. Anything else re-checks as absent and rethrows.
+      if (await this._columnPresent(db, EVENTS_TABLE, "params_json")) return
+
+      throw error
+    }
+  }
+
   /**
    * Runs ensure replay channels table.
    * @param {import("../database/drivers/base.js").default} db - Database connection.
@@ -352,7 +424,7 @@ export default class VelociousHttpServerWebsocketEventLogStore {
    * @param {string} args.channel - Channel name.
    * @param {import("../database/drivers/base.js").default} args.db - Database connection.
    * @param {string} args.id - Event id.
-   * @returns {Promise<{channel: string, createdAt: string, id: string, payload: ReturnType<typeof JSON.parse>, sequence: number} | null>} - Event row or null.
+   * @returns {Promise<WebsocketPersistedEvent | null>} - Event row or null.
    */
   async _getEventById({channel, db, id}) {
     const rows = /** @type {WebsocketEventRow[]} */ (await db
@@ -370,7 +442,7 @@ export default class VelociousHttpServerWebsocketEventLogStore {
   /**
    * Runs normalize event row.
    * @param {WebsocketEventRow} row - Raw row.
-   * @returns {{channel: string, createdAt: string, id: string, payload: ReturnType<typeof JSON.parse>, sequence: number}} - Normalized row.
+   * @returns {WebsocketPersistedEvent} - Normalized row.
    */
   _normalizeEventRow(row) {
     const createdAtValue = row.created_at
@@ -379,6 +451,7 @@ export default class VelociousHttpServerWebsocketEventLogStore {
       channel: row.channel,
       createdAt: createdAtValue instanceof Date ? createdAtValue.toISOString() : new Date(createdAtValue).toISOString(),
       id: row.id,
+      params: row.params_json === null || row.params_json === undefined ? null : JSON.parse(row.params_json),
       payload: JSON.parse(row.payload_json),
       sequence: Number(row.sequence)
     }

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

@@ -116,7 +116,7 @@ export class VelociousHttpServerWebsocketEventsHost {
     // Other channels chain onto their own tails and are not delayed.
     this._queuePublish({
       callback: async () => {
-        const persistedEvent = await this._persistV2EventIfNeeded({body, channel, configuration})
+        const persistedEvent = await this._persistV2EventIfNeeded({body, broadcastParams, channel, configuration})
         const dispatchedTargets = new Set()
 
         for (const handler of this.broadcastHandlersByConfiguration.get(configuration) || []) {
@@ -193,12 +193,13 @@ export class VelociousHttpServerWebsocketEventsHost {
    * Runs persist v2 event if needed.
    * @param {object} args - Options.
    * @param {ReturnType<typeof JSON.parse>} args.body - Event body.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.broadcastParams - Routing filter params.
    * @param {string} args.channel - Channel name.
    * @param {import("../configuration.js").default} args.configuration - Originating configuration.
    * @returns {Promise<{createdAt: string, id: string} | null>} - Persisted event metadata when storage is enabled.
    */
-  async _persistV2EventIfNeeded({body, channel, configuration}) {
-    return await this._persistChannelEventIfNeeded({channel, payload: body, configuration})
+  async _persistV2EventIfNeeded({body, broadcastParams, channel, configuration}) {
+    return await this._persistChannelEventIfNeeded({broadcastParams, channel, configuration, payload: body})
   }
 
   /**
@@ -213,14 +214,18 @@ export class VelociousHttpServerWebsocketEventsHost {
   }
 
   /**
-   * Runs persist channel event if needed.
+   * Runs persist channel event if needed. Persists the broadcast's routing
+   * params (sanitized through the channel class's
+   * `replayableBroadcastParams`) so replay can re-apply `matches()` per
+   * stream instead of delivering the whole channel's log.
    * @param {object} args - Options object.
+   * @param {Record<string, ReturnType<typeof JSON.parse>> | null} [args.broadcastParams] - Broadcast params to persist for stream-scoped replay.
    * @param {string} args.channel - Channel name.
    * @param {ReturnType<typeof JSON.parse>} args.payload - Payload data.
    * @param {import("../configuration.js").default} [args.configuration] - Configuration owning the event store.
    * @returns {Promise<{createdAt: string, id: string} | null>} - Persisted event metadata.
    */
-  async _persistChannelEventIfNeeded({channel, payload, configuration}) {
+  async _persistChannelEventIfNeeded({broadcastParams = null, channel, configuration, payload}) {
     const handler = this.handlers.values().next().value
     const eventConfiguration = configuration || handler?.configuration
 
@@ -231,7 +236,10 @@ export class VelociousHttpServerWebsocketEventsHost {
 
     if (!shouldPersist) return null
 
-    const persistedEvent = await websocketEventLogStore.appendEvent({channel, payload})
+    const ChannelClass = eventConfiguration.getWebsocketChannelClass(channel)
+    const params = ChannelClass ? ChannelClass.replayableBroadcastParams(broadcastParams) : broadcastParams
+
+    const persistedEvent = await websocketEventLogStore.appendEvent({channel, params, payload})
 
     return {
       createdAt: persistedEvent.createdAt,