velocious 1.0.620 → 1.0.622

package/src/remote-request-context.js

@@ -0,0 +1,97 @@
+// @ts-check
+
+import VelociousError from "./velocious-error.js"
+import isPlainObject from "./utils/plain-object.js"
+
+/** @typedef {Readonly<Record<string, string | number | boolean>>} RemoteRequestContext */
+
+const UNSAFE_CONTEXT_KEYS = new Set(["__proto__", "constructor", "prototype"])
+
+/**
+ * Captures and validates immutable scalar context for one remote operation.
+ * @param {ReturnType<typeof JSON.parse> | undefined} value - Configured context value.
+ * @param {object} [args] - Validation options.
+ * @param {string} [args.label] - Context label used in errors.
+ * @param {Iterable<string>} [args.reservedKeys] - Framework-owned keys unavailable to context.
+ * @returns {RemoteRequestContext} Frozen context snapshot.
+ */
+export function captureRemoteRequestContext(value, {label = "Remote request context", reservedKeys = []} = {}) {
+  if (value === undefined || value === null) return Object.freeze({})
+
+  if (!isPlainObject(value)) {
+    throw remoteRequestContextError(`${label} must be a plain object of scalar values`)
+  }
+
+  const reservedKeySet = new Set(reservedKeys)
+  /** @type {Record<string, string | number | boolean>} */
+  const context = {}
+
+  for (const key of Object.keys(value).sort()) {
+    if (!key.trim()) throw remoteRequestContextError(`${label} keys must be non-blank strings`)
+    if (UNSAFE_CONTEXT_KEYS.has(key) || reservedKeySet.has(key)) {
+      throw remoteRequestContextError(`${label} key ${JSON.stringify(key)} is reserved by the framework`)
+    }
+
+    const contextValue = value[key]
+
+    if (!remoteRequestContextScalar(contextValue)) {
+      throw remoteRequestContextError(`${label} key ${JSON.stringify(key)} must contain a string, finite number, or boolean scalar`)
+    }
+
+    context[key] = contextValue
+  }
+
+  return Object.freeze(context)
+}
+
+/**
+ * Merges captured context into framework request params without ambiguity.
+ * @template {Record<string, ReturnType<typeof JSON.parse>>} TParams
+ * @param {object} args - Merge arguments.
+ * @param {RemoteRequestContext} args.context - Captured context.
+ * @param {string} [args.label] - Context label used in errors.
+ * @param {TParams} args.params - Framework-owned request params.
+ * @returns {TParams & RemoteRequestContext} Merged params, or the original params when unscoped.
+ */
+export function mergeRemoteRequestContext({context, label = "Remote request context", params}) {
+  const contextKeys = Object.keys(context)
+
+  if (contextKeys.length === 0) return params
+
+  for (const key of contextKeys) {
+    if (Object.hasOwn(params, key)) {
+      throw remoteRequestContextError(`${label} key ${JSON.stringify(key)} is reserved by the request payload`)
+    }
+  }
+
+  return {...params, ...context}
+}
+
+/**
+ * Returns a stable identity for an immutable captured context.
+ * @param {RemoteRequestContext} context - Captured context.
+ * @returns {string} Stable serialized key.
+ */
+export function remoteRequestContextKey(context) {
+  return JSON.stringify(context)
+}
+
+/**
+ * Checks whether a value is a supported request-context scalar.
+ * @param {ReturnType<typeof JSON.parse>} value - Candidate scalar.
+ * @returns {value is string | number | boolean} Whether the value is supported.
+ */
+function remoteRequestContextScalar(value) {
+  if (["string", "boolean"].includes(typeof value)) return true
+
+  return typeof value === "number" && Number.isFinite(value)
+}
+
+/**
+ * Builds a client-safe request-context validation error.
+ * @param {string} message - Safe validation message.
+ * @returns {VelociousError} Validation error.
+ */
+function remoteRequestContextError(message) {
+  return VelociousError.safe(message, {code: "remote-request-context-invalid", errorType: "validation_error"})
+}

package/src/sync/sync-client-types.js

@@ -90,6 +90,7 @@
  * @typedef {object} SyncClientOptions
  * @property {import("../configuration.js").default} [configuration] - Configuration owning the registered models, the `sync.client` block, and the scope-store database. Defaults to the current configuration.
  * @property {(args: {scope: SerializedSyncScope}) => string | null | Promise<string | null>} [legacyCursor] - Seeds a newly declared scope's cursor (e.g. from a pre-scope cursor store) so devices don't re-pull everything.
+ * @property {import("../remote-request-context.js").RemoteRequestContext} [requestContext] - Immutable scalar context captured for this client and sent with every pull, replay, and realtime subscription.
  * @property {import("./sync-scope-store.js").default} [scopeStore] - Scope store override (tests).
  * @property {ReturnType<typeof JSON.parse>} [syncModel] - Pending-sync model override. Defaults to the registered "Sync" model.
  * @property {string} [databaseIdentifier] - Tenant database identifier; required with tenantHandle.
@@ -109,6 +110,7 @@
  * @property {(payload: import("./sync-api-client-types.js").SyncChangesRequest & {scope: SerializedSyncScope}) => Promise<import("./sync-api-client-types.js").SyncChangesResponse>} postChanges - Posts one changes request.
  * @property {(payload: {authenticationToken: string, syncs: Array<Record<string, ReturnType<typeof JSON.parse>>>}) => Promise<import("./sync-api-client-types.js").SyncReplayResponse>} postReplay - Posts one replay request.
  * @property {import("../configuration-types.js").VelociousSyncClientRealtimeConfiguration} [realtime] - Realtime push configuration consumed by `subscribeRealtime(...)`.
+ * @property {import("../remote-request-context.js").RemoteRequestContext} requestContext - Immutable scalar context captured for this client.
  * @property {Record<string, SyncClientResourceConfig>} resources - Derived resource policies keyed by resource/model name.
  * @property {ReturnType<typeof JSON.parse>} syncModel - Local pending-sync model class.
  * @property {string} [databaseIdentifier] - Tenant-scoped database identifier.

package/src/sync/sync-client.js

@@ -3,6 +3,7 @@
 import Configuration from "../configuration.js"
 import {isBooleanColumnType} from "../database/column-types.js"
 import Logger from "../logger.js"
+import {captureRemoteRequestContext, mergeRemoteRequestContext} from "../remote-request-context.js"
 import restArgsError from "../utils/rest-args-error.js"
 import VelociousWebsocketClient from "../http-client/websocket-client.js"
 
@@ -28,6 +29,20 @@ const DEFAULT_TRACKED_OPERATIONS = ["create", "update"]
 /** Attribute names treated as client-local sync bookkeeping when deriving localOnlyAttributes. */
 const LOCAL_BOOKKEEPING_ATTRIBUTE_NAMES = ["createdAt", "updatedAt", "lastSyncChangeAt"]
 
+const SYNC_REQUEST_RESERVED_KEYS = [
+  "afterId",
+  "afterServerSequence",
+  "afterUpdatedAt",
+  "authenticationToken",
+  "limit",
+  "scope",
+  "syncs",
+  "upstreamRefresh",
+  "upToId",
+  "upToServerSequence",
+  "upToUpdatedAt"
+]
+
 /** @type {WeakMap<Configuration, SyncClient>} */
 const syncClientsByConfiguration = new WeakMap()
 
@@ -56,11 +71,15 @@ export default class SyncClient {
    * @param {import("./sync-client-types.js").SyncClientOptions} [options] - Optional overrides.
    */
   constructor(options = {}) {
-    const {configuration = Configuration.current(), databaseIdentifier, legacyCursor, scopeStore, syncModel, tenantHandle, ...restOptions} = options
+    const {configuration = Configuration.current(), databaseIdentifier, legacyCursor, requestContext, scopeStore, syncModel, tenantHandle, ...restOptions} = options
 
     restArgsError(restOptions)
 
     const clientConfiguration = configuration.getSyncConfiguration().client
+    const capturedRequestContext = captureRemoteRequestContext(requestContext, {
+      label: "Sync client request context",
+      reservedKeys: SYNC_REQUEST_RESERVED_KEYS
+    })
 
     if (!clientConfiguration) {
       throw new Error("SyncClient requires a sync.client configuration block: new Configuration({sync: {client: {authenticationToken, transport}}})")
@@ -121,9 +140,10 @@ export default class SyncClient {
       isOnline: clientConfiguration.isOnline,
       legacyCursor,
       onError: clientConfiguration.onError,
-      postChanges: transportPoster({path: `${clientConfiguration.mountPath}/changes`, transport: clientConfiguration.transport}),
-      postReplay: transportPoster({path: `${clientConfiguration.mountPath}/replay`, transport: clientConfiguration.transport}),
+      postChanges: transportPoster({path: `${clientConfiguration.mountPath}/changes`, requestContext: capturedRequestContext, transport: clientConfiguration.transport}),
+      postReplay: transportPoster({path: `${clientConfiguration.mountPath}/replay`, requestContext: capturedRequestContext, transport: clientConfiguration.transport}),
       realtime: clientConfiguration.realtime,
+      requestContext: capturedRequestContext,
       resources,
       syncModel: resolvedSyncModel,
       tenantHandle,
@@ -1267,12 +1287,17 @@ function normalizedTrack(track) {
 
 /**
  * Builds a framework-owned sync endpoint POSTer over the configured transport.
- * @param {{path: string, transport: import("../configuration-types.js").VelociousSyncClientTransport}} args - Poster args.
+ * @param {{path: string, requestContext: import("../remote-request-context.js").RemoteRequestContext, transport: import("../configuration-types.js").VelociousSyncClientTransport}} args - Poster args.
  * @returns {(payload: Record<string, ReturnType<typeof JSON.parse>>) => Promise<ReturnType<typeof JSON.parse>>} Sync endpoint POSTer.
  */
-function transportPoster({path, transport}) {
+function transportPoster({path, requestContext, transport}) {
   return async (payload) => {
-    const response = await transport.post(path, payload)
+    const requestPayload = mergeRemoteRequestContext({
+      context: requestContext,
+      label: "Sync client request context",
+      params: payload
+    })
+    const response = await transport.post(path, requestPayload)
 
     if (!response || typeof response.json !== "function") {
       throw new Error(`sync.client transport.post must resolve to a response with a json() method for ${path} (like the frontend-model websocket client)`)

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

@@ -1,6 +1,7 @@
 // @ts-check
 
 import recordChanges from "../database/record-changes.js"
+import {mergeRemoteRequestContext} from "../remote-request-context.js"
 
 import SyncApiClient from "./sync-api-client.js"
 import {VELOCIOUS_SYNC_CHANNEL} from "./sync-channel-name.js"
@@ -141,10 +142,15 @@ export default class SyncRealtimeBridge {
         }
 
         const resourceType = channelDescriptor.resourceType ?? null
+        const params = mergeRemoteRequestContext({
+          context: this.syncClient.config.requestContext,
+          label: "Sync client request context",
+          params: {...channelDescriptor.params, authenticationToken}
+        })
         const subscription = client.subscribeChannel(channelDescriptor.channel, {
           onMessage: (body) => this.enqueueApply({body, resourceType}),
           onResume: () => this.schedulePull(),
-          params: {...channelDescriptor.params, authenticationToken}
+          params
         })
 
         channels.push({channel: channelDescriptor.channel, resourceType, subscription})

package/src/testing/shared-transaction-connection-coordinator.js

@@ -1,6 +1,7 @@
 // @ts-check
 
-/** @typedef {{coordinator: (callback: () => Promise<unknown>) => Promise<unknown>, ownedQueue: Promise<void>, owner: symbol, reentrantOwners: Set<symbol>, rootOwners: Set<symbol>}} CoordinatorRegistration */
+/** @typedef {{ownedQueue: Promise<void>}} CoordinatorOwnerScope */
+/** @typedef {{connectionScope: CoordinatorOwnerScope, coordinator: (callback: () => Promise<unknown>) => Promise<unknown>, owner: symbol, ownerScopes: Map<symbol, CoordinatorOwnerScope>}} CoordinatorRegistration */
 
 /** @type {WeakMap<object, CoordinatorRegistration>} */
 const coordinators = new WeakMap()
@@ -21,43 +22,47 @@ async function inactiveCoordinator(callback) {
  * @template T
  * @param {import("../database/drivers/base.js").default} connection - Parent physical connection.
  * @param {CoordinatorRegistration} registration - Physical connection registration.
+ * @param {CoordinatorOwnerScope} ownerScope - Queue inherited from the current owner.
  * @param {() => Promise<T>} callback - Owned operation.
+ * @param {string} [ownerDescription] - Async owner description.
  * @returns {Promise<T>} - Operation result.
  */
-async function coordinateOwnedSharedTransactionConnection(connection, registration, callback) {
-  const previous = registration.ownedQueue
+async function coordinateOwnedSharedTransactionConnection(connection, registration, ownerScope, callback, ownerDescription = "shared-transaction-owned-operation") {
+  const previous = ownerScope.ownedQueue
   /**
    * Releases the next owned sibling operation.
    * @type {() => void}
    */
   let release = () => {}
 
-  registration.ownedQueue = new Promise((resolve) => { release = resolve })
+  ownerScope.ownedQueue = new Promise((resolve) => { release = resolve })
   await previous
-  const operationOwner = Symbol("shared-transaction-owned-operation")
+  const operationOwner = Symbol(ownerDescription)
   const environmentHandler = connection.configuration.getEnvironmentHandler()
+  const operationScope = {ownedQueue: Promise.resolve()}
 
-  registration.reentrantOwners.add(operationOwner)
+  registration.ownerScopes.set(operationOwner, operationScope)
   try {
     return await environmentHandler.runWithSharedTransactionCoordinatorOwner(connection, operationOwner, callback)
   } finally {
-    registration.reentrantOwners.delete(operationOwner)
+    await drainOwnedSharedTransactionConnections(operationScope)
+    registration.ownerScopes.delete(operationOwner)
     release()
   }
 }
 
 /**
  * Drains all inherited operations admitted before the root owner is revoked.
- * @param {CoordinatorRegistration} registration - Physical connection registration.
+ * @param {CoordinatorOwnerScope} ownerScope - Owner scope to drain.
  * @returns {Promise<void>} - Resolves when the owned queue stops advancing.
  */
-async function drainOwnedSharedTransactionConnections(registration) {
+async function drainOwnedSharedTransactionConnections(ownerScope) {
   let tail
 
   do {
-    tail = registration.ownedQueue
+    tail = ownerScope.ownedQueue
     await tail
-  } while (tail !== registration.ownedQueue)
+  } while (tail !== ownerScope.ownedQueue)
 }
 
 /**
@@ -69,17 +74,13 @@ async function drainOwnedSharedTransactionConnections(registration) {
  * @returns {Promise<T>} - Operation result.
  */
 async function coordinateRootSharedTransactionConnection(connection, registration, callback) {
-  await drainOwnedSharedTransactionConnections(registration)
-  const rootOwner = Symbol("shared-transaction-root-operation")
-  const environmentHandler = connection.configuration.getEnvironmentHandler()
-
-  registration.rootOwners.add(rootOwner)
-  try {
-    return await environmentHandler.runWithSharedTransactionCoordinatorOwner(connection, rootOwner, callback)
-  } finally {
-    await drainOwnedSharedTransactionConnections(registration)
-    registration.rootOwners.delete(rootOwner)
-  }
+  return await coordinateOwnedSharedTransactionConnection(
+    connection,
+    registration,
+    registration.connectionScope,
+    callback,
+    "shared-transaction-root-operation"
+  )
 }
 
 /**
@@ -96,7 +97,12 @@ export function setSharedTransactionCoordinator(connection, coordinator) {
     registration.coordinator = coordinator
     registration.owner = owner
   } else {
-    registration = {coordinator, ownedQueue: Promise.resolve(), owner, reentrantOwners: new Set(), rootOwners: new Set()}
+    registration = {
+      connectionScope: {ownedQueue: Promise.resolve()},
+      coordinator,
+      owner,
+      ownerScopes: new Map()
+    }
     connectionRegistrations.set(connection, registration)
   }
 
@@ -135,12 +141,14 @@ export async function coordinateSharedTransactionConnection(connection, callback
 
   const environmentHandler = connection.configuration.getEnvironmentHandler()
   const currentOwner = environmentHandler.getSharedTransactionCoordinatorOwner(connection)
+  const currentOwnerScope = currentOwner ? registration.ownerScopes.get(currentOwner) : undefined
 
-  if (currentOwner && registration.reentrantOwners.has(currentOwner)) return await callback()
-  if (currentOwner && registration.rootOwners.has(currentOwner)) {
-    return await coordinateOwnedSharedTransactionConnection(connection, registration, callback)
+  if (currentOwnerScope) {
+    return await coordinateOwnedSharedTransactionConnection(connection, registration, currentOwnerScope, callback)
+  }
+  if (!activeRegistration) {
+    return await coordinateOwnedSharedTransactionConnection(connection, registration, registration.connectionScope, callback)
   }
-  if (!activeRegistration) return await coordinateOwnedSharedTransactionConnection(connection, registration, callback)
   if (operationOwner === registration.owner) {
     return await coordinateRootSharedTransactionConnection(connection, registration, callback)
   }
@@ -149,3 +157,19 @@ export async function coordinateSharedTransactionConnection(connection, callback
     return await coordinateRootSharedTransactionConnection(connection, registration, callback)
   }))
 }
+
+/**
+ * Runs physical query work without inheriting this connection's coordinator owner.
+ * Unregistered connections have no coordinator ownership to clear.
+ * @template T
+ * @param {import("../database/drivers/base.js").default} connection - Physical connection.
+ * @param {() => Promise<T>} callback - Physical query work.
+ * @returns {Promise<T>} - Callback result.
+ */
+export async function runWithoutSharedTransactionCoordinatorOwner(connection, callback) {
+  if (!connectionRegistrations.has(connection)) return await callback()
+
+  const environmentHandler = connection.configuration.getEnvironmentHandler()
+
+  return await environmentHandler.runWithoutSharedTransactionCoordinatorOwner(connection, callback)
+}

package/src/testing/test-runner.js

@@ -1436,7 +1436,7 @@ export default class TestRunner {
                 testSharedConnectionsActive = true
 
                 try {
-                  if (testArgs.databaseCleaning?.transaction === true) {
+                  if (testArgs.databaseCleaning?.transaction === true || testArgs.type == "request") {
                     sharedTransactionBrokerPreparation = await this.prepareSharedTransactionBroker()
                   }