velocious 1.0.621 → 1.0.623

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-envelope-replay-service.js

@@ -798,18 +798,24 @@ export default class SyncEnvelopeReplayService {
     if (!existingRecord || mutation.syncType === "create") return null
     if (mutation.baseVersion === undefined || mutation.baseVersion === null) return null
 
+    const ModelClass = resource.modelClass()
+    const primaryKey = ModelClass.primaryKey()
+    const primaryKeyAttribute = ModelClass.resolveAttributeName(primaryKey)
     const versionAttribute = this.conflictStrategy.versionAttribute
-    const serverVersion = normalizeConflictValue(existingRecord.readAttribute(versionAttribute))
+    const versionAttributeName = ModelClass.resolveAttributeName(versionAttribute)
+
+    if (!primaryKeyAttribute) throw new Error(`Couldn't resolve primary key attribute: ${primaryKey}`)
+    if (!versionAttributeName) throw new Error(`Couldn't resolve version attribute: ${versionAttribute}`)
+
+    const serverVersion = normalizeConflictValue(existingRecord.readAttribute(versionAttributeName))
 
     if (stableJsonStringify(serverVersion) === stableJsonStringify(mutation.baseVersion)) return null
 
-    const ModelClass = resource.modelClass()
-    const primaryKey = ModelClass.primaryKey()
     const serializedAffectedAttributes = await this.serializedRoutedConflictAttributes({attributes, existingRecord, resource})
     const serverAttributes = {
       ...serializedAffectedAttributes,
-      [primaryKey]: existingRecord.readAttribute(primaryKey),
-      [versionAttribute]: serverVersion
+      [primaryKeyAttribute]: existingRecord.readAttribute(primaryKeyAttribute),
+      [versionAttributeName]: serverVersion
     }
 
     const serverRecord = {
@@ -842,8 +848,9 @@ export default class SyncEnvelopeReplayService {
    * attribute contract. Writable-but-hidden fields are omitted, while custom
    * `<attribute>Attribute(model)` serializers and model accessors remain the
    * source of frontend-visible values (Date values are kept raw so the normal
-   * frontend-model transport serializer can emit its date marker). The full
-   * model attribute hash is never exposed.
+   * frontend-model transport serializer can emit its date marker). Projected
+   * keys use canonical model attribute names even when the mutation used a
+   * database-column alias. The full model attribute hash is never exposed.
    * @param {object} args - Projection args.
    * @param {Record<string, ReturnType<typeof JSON.parse>>} args.attributes - Permitted affected mutation attributes.
    * @param {import("../database/record/index.js").default} args.existingRecord - Authorized server record.
@@ -886,7 +893,7 @@ export default class SyncEnvelopeReplayService {
       const resourceAttribute = resource.resourceMethod(`${attributeName}Attribute`)
 
       if (resourceAttribute) {
-        serializedAttributes[affectedField] = await resourceAttribute.method.call(resourceAttribute.resource, existingRecord)
+        serializedAttributes[attributeName] = await resourceAttribute.method.call(resourceAttribute.resource, existingRecord)
         continue
       }
 
@@ -894,9 +901,9 @@ export default class SyncEnvelopeReplayService {
       const attributeMethod = recordMethods[attributeName]
 
       if (typeof attributeMethod === "function") {
-        serializedAttributes[affectedField] = await attributeMethod.call(existingRecord)
+        serializedAttributes[attributeName] = await attributeMethod.call(existingRecord)
       } else {
-        serializedAttributes[affectedField] = existingRecord.readAttribute(attributeName)
+        serializedAttributes[attributeName] = existingRecord.readAttribute(attributeName)
       }
     }
 

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

@@ -157,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()
                   }