velocious 1.0.720 → 1.0.722

package/src/routes/basic-route.js

@@ -6,10 +6,11 @@ export default class VelociousBasicRoute extends BaseRoute {
   /**
    * Runs get.
    * @param {string} name - Route name.
+   * @param {{on?: "member" | "collection"} | {skipControllerConnections?: boolean}} [options] - Route options; `skipControllerConnections: true` skips the request-scoped controller connection for this route.
    */
-  get(name) {
+  get(name, options = {}) {
     const GetRoute = VelociousBasicRoute.GetRouteType
-    const route = new GetRoute({name})
+    const route = new GetRoute({name, ...options})
 
     this.routes.push(route)
   }
@@ -51,35 +52,59 @@ export default class VelociousBasicRoute extends BaseRoute {
 
   /**
    * Runs namespace.
-   * @param {string} name - Name.
-   * @param {(arg: import("./namespace-route.js").default) => void} callback - Callback function.
+   * @param {string} name - Route name.
+   * @param {{skipControllerConnections?: boolean} | ((arg: import("./namespace-route.js").default) => void)} [options] - Namespace options (`skipControllerConnections: true` skips the request-scoped controller connection for every route declared inside this namespace; a per-route option still overrides it) or the draw callback (legacy form).
+   * @param {((arg: import("./namespace-route.js").default) => void) | undefined} [callback] - Callback function.
    * @returns {void} - No return value.
    */
-  namespace(name, callback) {
+  namespace(name, options = {}, callback) {
     const NamespaceRoute = VelociousBasicRoute.NameSpaceRouteType
 
     if (!NamespaceRoute) throw new Error("No NamespaceRoute registered")
 
+    // Backward compatible: the second argument may be the draw callback.
+    if (typeof options === "function") {
+      callback = options
+      options = {}
+    }
+
+    const namespaceOptions = /** @type {{skipControllerConnections?: boolean}} */ (options)
+    const skipControllerConnections = namespaceOptions.skipControllerConnections === true
+
     const route = new NamespaceRoute({name})
 
     this.routes.push(route)
 
     if (callback) {
+      const originalGet = route.get.bind(route)
+      const originalPost = route.post.bind(route)
+
+      route.get = (routeName, routeOptions = {}) => {
+        const subOptions = /** @type {{skipControllerConnections?: boolean}} */ (routeOptions)
+        return originalGet(routeName, {...routeOptions, skipControllerConnections: subOptions.skipControllerConnections ?? skipControllerConnections})
+      }
+
+      route.post = (routeName, routeOptions = {}) => {
+        const subOptions = /** @type {{skipControllerConnections?: boolean}} */ (routeOptions)
+        return originalPost(routeName, {...routeOptions, skipControllerConnections: subOptions.skipControllerConnections ?? skipControllerConnections})
+      }
+
       callback(route)
     }
   }
 
   /**
    * Runs post.
-   * @param {string} name - Name.
+   * @param {string} name - Route name.
+   * @param {{on?: "member" | "collection"} | {skipControllerConnections?: boolean}} [options] - Route options; `skipControllerConnections: true` skips the request-scoped controller connection for this route.
    * @returns {void} - No return value.
    */
-  post(name) {
+  post(name, options = {}) {
     const PostRoute = VelociousBasicRoute.PostRouteType
 
     if (!PostRoute) throw new Error("No PostRoute registered")
 
-    const route = new PostRoute({name})
+    const route = new PostRoute({name, ...options})
 
     this.routes.push(route)
   }

package/src/routes/get-route.js

@@ -28,16 +28,32 @@ function assignActionAndController(params, name) {
 }
 
 class VelociousRouteGetRoute extends BaseRoute {
+  /**
+   * When true the resolver skips the request-scoped controller connection for
+   * this route: the action runs without an ambient `ensureConnections` checkout,
+   * so a long-lived action (streaming response, long wait) does not pin a pool
+   * connection for its whole lifetime. Each explicit `ensureConnections` call
+   * inside the action still opens and returns its own short-lived connection.
+   * @type {boolean}
+   */
+  skipControllerConnections = false
+
   /**
    * Runs constructor.
    * @param {object} args - Options object.
    * @param {string} args.name - Name.
+   * @param {boolean} [args.skipControllerConnections] - Skip the request-scoped controller connection for this route.
    */
-  constructor({name, ...restArgs}) {
+  constructor({name, skipControllerConnections = false, ...restArgs}) {
     super()
     restArgsError(restArgs)
     this.name = name
     this.regExp = new RegExp(`^(${escapeStringRegexp(name)})(.*)$`)
+    if (skipControllerConnections !== true && skipControllerConnections !== false) {
+      throw new Error(`Expected get route 'skipControllerConnections' to be a boolean, got: ${String(skipControllerConnections)}`)
+    }
+
+    this.skipControllerConnections = skipControllerConnections
   }
 
   getHumanPaths() {

package/src/routes/post-route.js

@@ -27,16 +27,32 @@ function assignActionAndController(params, name) {
 }
 
 class VelociousRoutePostRoute extends BaseRoute {
+  /**
+   * When true the resolver skips the request-scoped controller connection for
+   * this route: the action runs without an ambient `ensureConnections` checkout,
+   * so a long-lived action (streaming response, long wait) does not pin a pool
+   * connection for its whole lifetime. Each explicit `ensureConnections` call
+   * inside the action still opens and returns its own short-lived connection.
+   * @type {boolean}
+   */
+  skipControllerConnections = false
+
   /**
    * Runs constructor.
    * @param {object} args - Options object.
    * @param {string} args.name - Name.
+   * @param {boolean} [args.skipControllerConnections] - Skip the request-scoped controller connection for this route.
    */
-  constructor({name, ...restArgs}) {
+  constructor({name, skipControllerConnections = false, ...restArgs}) {
     super()
     restArgsError(restArgs)
     this.name = name
     this.regExp = new RegExp(`^(${escapeStringRegexp(name)})(.*)$`)
+    if (skipControllerConnections !== true && skipControllerConnections !== false) {
+      throw new Error(`Expected post route 'skipControllerConnections' to be a boolean, got: ${String(skipControllerConnections)}`)
+    }
+
+    this.skipControllerConnections = skipControllerConnections
   }
 
   getHumanPaths() {

package/src/routes/resolver.js

@@ -92,10 +92,12 @@ export default class VelociousRoutesResolver {
     }
 
     const routeResolverHookMatch = await this.resolveRouteResolverHooks(currentPath, {hasMatchingCustomRoute})
-    let skipControllerConnections = this.configuration.database === false || routeResolverHookMatch?.skipControllerConnections === true
+    const matchResult = routeResolverHookMatch || !currentRoute ? undefined : this.matchPathWithRoutes(currentRoute, currentPath)
+    let skipControllerConnections = this.configuration.database === false
+      || routeResolverHookMatch?.skipControllerConnections === true
+      || matchResult?.skipControllerConnections === true
     let skipAbilityResolution = routeResolverHookMatch?.skipAbilityResolution === true
     let skipTenantResolution = routeResolverHookMatch?.skipTenantResolution === true
-    const matchResult = routeResolverHookMatch || !currentRoute ? undefined : this.matchPathWithRoutes(currentRoute, currentPath)
     const actionParam = this.params.action
     const controllerParam = this.params.controller
     const actionValue = typeof actionParam == "string" ? actionParam : (Array.isArray(actionParam) ? actionParam[0] : undefined)
@@ -272,7 +274,7 @@ export default class VelociousRoutesResolver {
    * Runs match path with routes.
    * @param {import("./base-route.js").default} route - Route.
    * @param {string} path - Path.
-   * @returns {{restPath: string} | undefined} - REST path metadata for this route.
+   * @returns {{restPath: string, skipControllerConnections?: boolean} | undefined} - REST path metadata for this route, including the matched leaf route's options.
    */
   matchPathWithRoutes(route, path) {
     const pathWithoutSlash = path.replace(/^\//, "").split("?")[0]

package/src/sync/sync-cursor.js

@@ -0,0 +1,56 @@
+// @ts-check
+
+/**
+ * @module sync-cursor
+ *
+ * Shared cursor helpers for the sync change feed: building a cursor from a
+ * serialized sync entry and ordering two cursors under the feed's stable order
+ * (server sequence when present, else updated-at then id). The server channel
+ * advances its per-subscription replay watermark with these across out-of-order
+ * live broadcasts, and the realtime bridge advances the persisted scope cursor
+ * monotonically on pushed changes.
+ */
+
+/** @typedef {import("./sync-api-client-types.js").SyncCursor} SyncCursor */
+
+/**
+ * Builds a cursor from a serialized sync entry, or null when the entry carries
+ * no cursor identity (no updated-at).
+ * @param {Record<string, ReturnType<typeof JSON.parse>>} entry - Serialized sync entry.
+ * @returns {SyncCursor} Cursor for the entry, or null.
+ */
+export function cursorFromSyncEntry(entry) {
+  const updatedAt = entry.updatedAt
+
+  if (typeof updatedAt !== "string" || updatedAt === "") return null
+
+  return {
+    id: entry.id === null || entry.id === undefined ? null : String(entry.id),
+    serverSequence: typeof entry.serverSequence === "number" ? entry.serverSequence : null,
+    updatedAt
+  }
+}
+
+/**
+ * Whether one cursor is strictly later than another under the change-feed order.
+ * A sequenced cursor is always later than an unsequenced one; both sequenced
+ * cursors order by server sequence; both unsequenced cursors order by updated-at
+ * then id.
+ * @param {SyncCursor} candidate - Candidate cursor.
+ * @param {SyncCursor} current - Current cursor.
+ * @returns {boolean} Whether the candidate is later.
+ */
+export function isCursorAfter(candidate, current) {
+  if (!candidate) return false
+  if (!current) return true
+
+  if (candidate.serverSequence !== null && current.serverSequence !== null) {
+    return candidate.serverSequence > current.serverSequence
+  }
+  if (candidate.serverSequence !== null) return true
+  if (current.serverSequence !== null) return false
+
+  if (candidate.updatedAt !== current.updatedAt) return candidate.updatedAt > current.updatedAt
+
+  return (candidate.id ?? "") > (current.id ?? "")
+}

package/src/sync/sync-realtime-bridge.js

@@ -5,10 +5,46 @@ import {mergeRemoteRequestContext} from "../remote-request-context.js"
 
 import SyncApiClient from "./sync-api-client.js"
 import {VELOCIOUS_SYNC_CHANNEL} from "./sync-channel-name.js"
+import {cursorFromSyncEntry, isCursorAfter} from "./sync-cursor.js"
 
 /** @typedef {import("../configuration-types.js").VelociousSyncRealtimeChannelDescriptor} VelociousSyncRealtimeChannelDescriptor */
 /** @typedef {import("../configuration-types.js").VelociousSyncRealtimeWebsocketClient} VelociousSyncRealtimeWebsocketClient */
 
+/**
+ * The persisted scope row the bridge carries so it can advance the scope's cursor
+ * on applied pushes. Mirrors the framework-owned scope store row shape.
+ * @typedef {object} SyncRealtimeScopeRow
+ * @property {Record<string, ReturnType<typeof JSON.parse>>} conditions - Scope attribute conditions.
+ * @property {string | null} cursorPayload - Persisted cursor JSON payload.
+ * @property {string} id - Scope row id.
+ * @property {string | null} resourceType - Scope resource type.
+ * @property {string} scopeDigest - Fixed-size scope digest.
+ * @property {string} state - Scope state.
+ * @property {string} storeIdentity - Physical store identity.
+ */
+
+/**
+ * One derived channel subscription carrying its owning scope row (null for legacy
+ * app channels) and the in-memory cursor watermark advanced by applied pushes.
+ * @typedef {object} DerivedSyncChannel
+ * @property {string} channel - Channel name.
+ * @property {import("./sync-api-client-types.js").SyncCursor} cursor - In-memory cursor watermark.
+ * @property {string | null} resourceType - Default resource type for pushed changes.
+ * @property {SyncRealtimeScopeRow | null} scopeRow - Owning scope row, or null for legacy channels.
+ * @property {import("../configuration-types.js").VelociousSyncRealtimeSubscription} subscription - Subscription handle.
+ */
+
+/**
+ * One derived channel to subscribe, carrying its owning scope row and cursor for
+ * framework sync channel subscriptions (null scope row for legacy app channels).
+ * @typedef {object} DerivedSyncChannelDescriptor
+ * @property {string} channel - Channel name.
+ * @property {import("./sync-api-client-types.js").SyncCursor} cursor - In-memory cursor watermark (null for legacy channels).
+ * @property {Record<string, ReturnType<typeof JSON.parse>>} params - Subscribe params (without the framework-injected auth token).
+ * @property {string | null} resourceType - Default resource type for pushed changes.
+ * @property {SyncRealtimeScopeRow | null} scopeRow - Owning scope row, or null for legacy channels.
+ */
+
 /**
  * Derived realtime push bridge for the sync client. Subscribes every declared
  * pull scope to the framework sync channel ({@link VELOCIOUS_SYNC_CHANNEL})
@@ -29,7 +65,7 @@ export default class SyncRealtimeBridge {
    */
   constructor({syncClient}) {
     this.syncClient = syncClient
-    /** @type {Array<{channel: string, resourceType: string | null, subscription: import("../configuration-types.js").VelociousSyncRealtimeSubscription}>} */
+    /** @type {Array<DerivedSyncChannel>} */
     this._channels = []
     /** @type {VelociousSyncRealtimeWebsocketClient | null} */
     this._client = null
@@ -40,8 +76,6 @@ export default class SyncRealtimeBridge {
     /** @type {number} Subscription generation - bumped by unsubscribe so in-flight subscribes detect they became stale. */
     this._generation = 0
     /** @type {Promise<void> | null} */
-    this._scheduledPull = null
-    /** @type {Promise<void> | null} */
     this._subscribePromise = null
     /** @type {"subscribed" | "subscribing" | "unsubscribed"} */
     this._state = "unsubscribed"
@@ -83,7 +117,7 @@ export default class SyncRealtimeBridge {
 
     this._state = "subscribing"
 
-    /** @type {Array<{channel: string, resourceType: string | null, subscription: import("../configuration-types.js").VelociousSyncRealtimeSubscription}>} */
+    /** @type {Array<DerivedSyncChannel>} */
     const channels = []
     /** @type {VelociousSyncRealtimeWebsocketClient | null} */
     let client = null
@@ -154,13 +188,19 @@ export default class SyncRealtimeBridge {
           label: "Sync client request context",
           params: {...channelDescriptor.params, authenticationToken}
         })
-        const subscription = client.subscribeChannel(channelDescriptor.channel, {
-          onMessage: (body) => this.enqueueApply({body, generation, resourceType}),
-          onResume: () => this.schedulePull(generation),
-          params
-        })
+        /** @type {DerivedSyncChannel} */
+        const channel = {
+          channel: channelDescriptor.channel,
+          cursor: channelDescriptor.cursor,
+          resourceType,
+          scopeRow: channelDescriptor.scopeRow,
+          subscription: client.subscribeChannel(channelDescriptor.channel, {
+            onMessage: (body) => this.enqueueApply({body, channel, generation}),
+            params
+          })
+        }
 
-        channels.push({channel: channelDescriptor.channel, resourceType, subscription})
+        channels.push(channel)
       }
 
       await Promise.all(channels.map(({subscription}) => subscription.waitForReady({signal})))
@@ -175,7 +215,6 @@ export default class SyncRealtimeBridge {
       this._client = client
       this._ownsClient = ownsClient
       this._state = "subscribed"
-      this.schedulePull(generation)
     } catch (error) {
       await teardown()
 
@@ -225,12 +264,11 @@ export default class SyncRealtimeBridge {
   }
 
   /**
-   * Awaits all enqueued message applies and any scheduled pull (tests, shutdown flows).
+   * Awaits all enqueued message applies (tests, shutdown flows).
    * @returns {Promise<void>}
    */
   async waitForApplied() {
     await this._applyPromise
-    if (this._scheduledPull) await this._scheduledPull
   }
 
   /**
@@ -266,33 +304,44 @@ export default class SyncRealtimeBridge {
    * model-level static realtime declarations and the config channels callback.
    * Fails loudly when nothing is subscribable.
    * @param {ReturnType<typeof JSON.parse>} context - App context passed to the deprecated channels callback.
-   * @returns {Promise<Array<VelociousSyncRealtimeChannelDescriptor>>} Channel descriptors.
+   * @returns {Promise<Array<DerivedSyncChannelDescriptor>>} Channel descriptors.
    */
   async channelDescriptors(context) {
     const realtime = this.realtimeConfiguration()
-    /** @type {Array<VelociousSyncRealtimeChannelDescriptor>} */
+    /** @type {Array<DerivedSyncChannelDescriptor>} */
     const channelDescriptors = []
 
     for (const scopeRow of await this.syncClient.scopeStore().activeScopes()) {
+      const cursorPayload = await this.syncClient.scopeStore().loadCursor(scopeRow)
+      const cursor = SyncApiClient.syncCursorFromPayload(cursorPayload)
+
       channelDescriptors.push({
         channel: VELOCIOUS_SYNC_CHANNEL,
+        cursor,
         params: {
           conditions: this.attributeNamedConditions(scopeRow),
           resourceType: scopeRow.resourceType,
           // Only the all-types scope carries the type list; a type-declared scope needs none.
-          ...(scopeRow.resourceType === null ? {resourceTypes: this.syncClient.userScopeResourceTypes()} : {})
-        }
+          ...(scopeRow.resourceType === null ? {resourceTypes: this.syncClient.userScopeResourceTypes()} : {}),
+          // Reuse the changes-endpoint cursor fields so the server replays the
+          // catch-up backlog from the scope's persisted cursor on subscribe.
+          ...SyncApiClient.cursorPayload("after", cursor)
+        },
+        resourceType: scopeRow.resourceType,
+        scopeRow
       })
     }
 
     for (const [resourceType, resourceConfig] of Object.entries(this.syncClient.config.resources)) {
       if (!resourceConfig.realtime) continue
 
-      channelDescriptors.push({channel: resourceConfig.realtime.channel, params: resourceConfig.realtime.params, resourceType})
+      channelDescriptors.push({channel: resourceConfig.realtime.channel, cursor: null, params: resourceConfig.realtime.params ?? {}, resourceType, scopeRow: null})
     }
 
     if (realtime?.channels) {
-      channelDescriptors.push(...await realtime.channels(context))
+      const legacyChannels = await realtime.channels(context)
+
+      channelDescriptors.push(...legacyChannels.map((descriptor) => ({channel: descriptor.channel, cursor: null, params: descriptor.params ?? {}, resourceType: descriptor.resourceType ?? null, scopeRow: null})))
     }
 
     if (channelDescriptors.length === 0) {
@@ -341,15 +390,15 @@ export default class SyncRealtimeBridge {
   /**
    * Chains one pushed message onto the serialized apply queue so changes apply
    * in arrival order; failures go to the sync client's error reporting.
-   * @param {{body: ReturnType<typeof JSON.parse>, generation?: number, resourceType: string | null}} args - Message args.
+   * @param {{body: ReturnType<typeof JSON.parse>, channel: DerivedSyncChannel, generation?: number}} args - Message args.
    * @returns {void}
    */
-  enqueueApply({body, generation = this._generation, resourceType}) {
+  enqueueApply({body, channel, generation = this._generation}) {
     this._applyPromise = this._applyPromise.then(async () => {
       if (generation !== this._generation) return
 
       try {
-        await this.applyMessage({body, resourceType})
+        await this.applyMessage({body, channel})
       } catch (error) {
         this.syncClient.reportError(/** @type {Error} */ (error))
       }
@@ -359,11 +408,12 @@ export default class SyncRealtimeBridge {
   /**
    * Applies one pushed message through the derived resource applier: drops
    * own-device messages by echo origin, defaults the channel's resourceType onto
-   * envelopes without one, and fails loudly on unknown resource types.
-   * @param {{body: ReturnType<typeof JSON.parse>, resourceType: string | null}} args - Message args.
+   * envelopes without one, fails loudly on unknown resource types, and advances
+   * the owning scope's cursor so a later replay resumes after the applied rows.
+   * @param {{body: ReturnType<typeof JSON.parse>, channel: DerivedSyncChannel}} args - Message args.
    * @returns {Promise<void>}
    */
-  async applyMessage({body, resourceType}) {
+  async applyMessage({body, channel}) {
     if (!body || typeof body !== "object" || Array.isArray(body)) {
       throw new Error(`Realtime sync messages must be envelope objects, got: ${JSON.stringify(body)}`)
     }
@@ -382,44 +432,40 @@ export default class SyncRealtimeBridge {
     // Coalesce record-change events across the pushed batch so it triggers one live-query re-run.
     await recordChanges.batch(async () => {
       for (const syncPayload of syncPayloads) {
-        const sync = SyncApiClient.syncEnvelopeFromPayload({resourceType, ...syncPayload})
+        const sync = SyncApiClient.syncEnvelopeFromPayload({resourceType: channel.resourceType, ...syncPayload})
 
         await applySync(sync)
       }
     })
+
+    await this.advanceScopeCursor(channel, syncPayloads)
   }
 
   /**
-   * Schedules a coalesced background pull closing offline gaps after
-   * (re)subscription readiness. Resumes arriving while a pull is already
-   * scheduled or in flight coalesce into that pull instead of stacking.
-   * @param {number} [generation] - Subscription generation owning the resume/readiness callback.
-   * @returns {void}
+   * Advances the owning scope's persisted cursor to the newest applied row,
+   * monotonically (never backwards) so an out-of-order or duplicate push cannot
+   * regress the cursor and re-deliver already-applied rows on a later replay.
+   * Legacy channels with no owning scope are skipped.
+   * @param {DerivedSyncChannel} channel - Channel owning the scope.
+   * @param {Array<ReturnType<typeof JSON.parse>>} syncPayloads - Applied sync entries.
+   * @returns {Promise<void>}
    */
-  schedulePull(generation = this._generation) {
-    if (generation !== this._generation) return
-    if (this.realtimeConfiguration()?.pullOnReconnect === false) return
+  async advanceScopeCursor(channel, syncPayloads) {
+    if (!channel.scopeRow) return
 
-    const coordinatorRun = this.syncClient.requestCoordinatorSync("realtime")
+    let latestCursor = channel.cursor
 
-    if (coordinatorRun) {
-      this._scheduledPull ||= coordinatorRun.finally(() => {
-        this._scheduledPull = null
-      })
-      return
+    for (const syncPayload of syncPayloads) {
+      const entry = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (syncPayload)
+      const cursor = cursorFromSyncEntry(entry)
+
+      if (cursor && isCursorAfter(cursor, latestCursor)) latestCursor = cursor
     }
 
-    this._scheduledPull ||= (async () => {
-      try {
-        await this.syncClient.pull()
-      } catch (error) {
-        if (!this.syncClient.isLifecycleAbort(error)) {
-          this.syncClient.reportError(/** @type {Error} */ (error))
-        }
-      } finally {
-        this._scheduledPull = null
-      }
-    })()
+    if (latestCursor && latestCursor !== channel.cursor) {
+      channel.cursor = latestCursor
+      await this.syncClient.scopeStore().saveCursor(channel.scopeRow, latestCursor)
+    }
   }
 }