velocious 1.0.514 → 1.0.516

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

@@ -4,7 +4,7 @@
  * Client-declared sync scope serialized from a model query.
  * @typedef {object} SerializedSyncScope
  * @property {Record<string, ?>} conditions - Plain attribute conditions from the query.
- * @property {string} resourceType - Resource/model name the scope was declared for.
+ * @property {string | null} resourceType - Resource/model name the scope was declared for, or null for the all-types (user) scope covering every type the server authorizes for the caller.
  * @property {string} [owner] - Local partition key: the authenticated identity that declared the scope. Used only to partition the local scope/cursor store (never sent to the server as scope conditions), so a user scope's empty-conditions cursor does not leak across accounts on a shared device.
  */
 

package/src/sync/sync-client.js

@@ -428,7 +428,12 @@ export default class SyncClient {
           }) : undefined,
           postChanges: async (payload) => await this.config.postChanges({
             ...payload,
-            scope: {conditions: scopeRow.conditions, resourceType: scopeRow.resourceType}
+            // Only the all-types scope carries the type list; a type-declared scope needs none.
+            scope: {
+              conditions: scopeRow.conditions,
+              resourceType: scopeRow.resourceType,
+              ...(scopeRow.resourceType === null ? {resourceTypes: this.userScopeResourceTypes()} : {})
+            }
           }),
           saveCursor: async (cursor) => await scopeStore.saveCursor(scopeRow, cursor)
         })
@@ -543,12 +548,7 @@ export default class SyncClient {
   async _subscribeUserScope() {
     this._userScopeState = "subscribing"
 
-    const scopeStore = this.scopeStore()
-    const owner = await this.userScopeOwner()
-
-    for (const resourceType of this.userScopeResourceTypes()) {
-      await scopeStore.findOrCreateScope({conditions: {}, owner, resourceType})
-    }
+    await this.scopeStore().findOrCreateScope(await this.userScope())
 
     await this.subscribeRealtime()
     await this.pull()
@@ -564,12 +564,7 @@ export default class SyncClient {
    * @returns {Promise<void>}
    */
   async unsubscribeUserScope() {
-    const scopeStore = this.scopeStore()
-    const owner = await this.userScopeOwner()
-
-    for (const resourceType of this.userScopeResourceTypes()) {
-      await scopeStore.deactivate({conditions: {}, owner, resourceType})
-    }
+    await this.scopeStore().deactivate(await this.userScope())
 
     await this.unsubscribeRealtime()
 
@@ -578,8 +573,26 @@ export default class SyncClient {
   }
 
   /**
-   * The resource types a user scope covers: every declared resource that
-   * receives pulled changes (has pull `attributes`).
+   * The user scope: a single all-types scope (null resourceType) with empty
+   * conditions, partitioned locally by owner. One scope - not one per resource
+   * type - so the server authorizes the caller once per sync and per subscribe,
+   * however many resource types it serves. The server decides which types the
+   * caller may see; the client applies each pulled row by the resource type on
+   * its own envelope.
+   * @returns {Promise<import("./sync-client-types.js").SerializedSyncScope>} The user scope.
+   */
+  async userScope() {
+    return {conditions: {}, owner: await this.userScopeOwner(), resourceType: null}
+  }
+
+  /**
+   * The resource types the user scope covers: every declared resource that
+   * receives pulled changes (has pull `attributes`), so the client can apply
+   * them. Sent with the scope as a delivery/type filter - it narrows, never
+   * widens, what the server's authorization already allows, and it keeps a
+   * broadcast of a type this client cannot apply from reaching the server's
+   * per-delivery access re-check (a database query per matched broadcast, per
+   * subscribed device).
    * @returns {string[]} Pullable resource type names.
    */
   userScopeResourceTypes() {

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

@@ -262,7 +262,12 @@ export default class SyncRealtimeBridge {
     for (const scopeRow of await this.syncClient.scopeStore().activeScopes()) {
       channelDescriptors.push({
         channel: VELOCIOUS_SYNC_CHANNEL,
-        params: {conditions: this.attributeNamedConditions(scopeRow), resourceType: scopeRow.resourceType}
+        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()} : {})
+        }
       })
     }
 
@@ -292,10 +297,16 @@ export default class SyncRealtimeBridge {
    * without a column mapping are already attribute names and pass through;
    * scopes on models without a declared sync resource fail loudly because no
    * attribute mapping exists for them.
-   * @param {{conditions: Record<string, ?>, resourceType: string}} scopeRow - Active scope row.
+   *
+   * The all-types (user) scope has no resource type and no conditions - it
+   * covers everything the server authorizes for the caller - so there is
+   * nothing to map.
+   * @param {{conditions: Record<string, ?>, resourceType: string | null}} scopeRow - Active scope row.
    * @returns {Record<string, ?>} Attribute-named scope conditions.
    */
   attributeNamedConditions(scopeRow) {
+    if (scopeRow.resourceType === null) return {}
+
     const resourceConfig = this.syncClient.config.resources[scopeRow.resourceType]
 
     if (!resourceConfig) {

package/src/sync/sync-resource-base.js

@@ -13,7 +13,8 @@ const QUICK_SEARCH_COLUMN = "quickSearch"
  * Optional client-declared sync scope carried on a changes request.
  * @typedef {object} SerializedChangesScope
  * @property {Record<string, ?>} conditions - Plain attribute conditions from the client query.
- * @property {string} resourceType - Client resource/model name the scope was declared for.
+ * @property {string | null} resourceType - Client resource/model name the scope was declared for, or null for the all-types (user) scope: one scope covering every resource type this resource authorizes for the caller, so a sync authorizes once however many types it serves.
+ * @property {string[] | null} resourceTypes - For the all-types scope, the resource types the client can apply. A cheap delivery/type filter only - it narrows, never widens, what the app's authorization already allows. Null for a type-declared scope.
  */
 
 /**
@@ -135,14 +136,30 @@ export default class SyncResourceBase extends FrontendModelBaseResource {
     }
 
     const scopeParams = /** @type {Record<string, ?>} */ (scope)
-    const resourceType = forcedNonBlankString(scopeParams.resourceType, "resourceType")
+    const resourceType = scopeParams.resourceType === null || scopeParams.resourceType === undefined
+      ? null
+      : forcedNonBlankString(scopeParams.resourceType, "resourceType")
+    const resourceTypes = this.changesScopeResourceTypes(scopeParams.resourceTypes)
     const conditions = scopeParams.conditions
 
     if (!conditions || typeof conditions !== "object" || Array.isArray(conditions)) {
       throw new Error(`Sync changes scope.conditions must be an object, got: ${String(conditions)}`)
     }
 
-    return {conditions: /** @type {Record<string, ?>} */ (conditions), resourceType}
+    return {conditions: /** @type {Record<string, ?>} */ (conditions), resourceType, resourceTypes}
+  }
+
+  /**
+   * Parses the optional resource-type list an all-types scope declares.
+   * @param {?} value - Raw `scope.resourceTypes` param.
+   * @returns {string[] | null} Declared resource types, or null when the client sent none.
+   */
+  changesScopeResourceTypes(value) {
+    if (value === undefined || value === null) return null
+
+    if (!Array.isArray(value)) throw new Error(`Sync changes scope.resourceTypes must be an array, got: ${String(value)}`)
+
+    return value.map((resourceType) => forcedNonBlankString(resourceType, "resourceTypes"))
   }
 
   /**

package/src/sync/sync-scope-store.js

@@ -24,7 +24,7 @@ function scopeDigestForScope(scope) {
  * @property {Record<string, ?>} conditions - Scope attribute conditions.
  * @property {string | null} cursorPayload - Persisted cursor JSON payload.
  * @property {string} id - Scope row id.
- * @property {string} resourceType - Scope resource/model name.
+ * @property {string | null} resourceType - Scope resource/model name, or null for the all-types (user) scope.
  * @property {string} scopeDigest - Fixed-size deterministic digest of the canonical scope key.
  * @property {string} state - Scope state ("active" or "removed").
  */
@@ -102,7 +102,7 @@ export default class SyncScopeStore {
         conditions: scope.conditions,
         cursorPayload: null,
         id: new UUID(4).format(),
-        resourceType: scope.resourceType,
+        resourceType: scope.resourceType ?? null,
         scopeDigest: digest,
         state: "active"
       }
@@ -131,7 +131,9 @@ export default class SyncScopeStore {
           created_at: new Date(),
           cursor_json: null,
           id: new UUID(4).format(),
-          resource_type: scope.resourceType,
+          // The all-types (user) scope has no resource type; the column is non-null, so it
+          // stores as an empty string and normalizes back to null on read.
+          resource_type: scope.resourceType ?? "",
           scope_digest: digest,
           state: "active",
           updated_at: new Date()
@@ -319,7 +321,7 @@ export default class SyncScopeStore {
       conditions: /** @type {Record<string, ?>} */ (JSON.parse(String(row.conditions_json))),
       cursorPayload: row.cursor_json === null || row.cursor_json === undefined ? null : String(row.cursor_json),
       id: String(row.id),
-      resourceType: String(row.resource_type),
+      resourceType: String(row.resource_type) === "" ? null : String(row.resource_type),
       scopeDigest: String(row.scope_digest),
       state: String(row.state)
     }

package/src/sync/sync-websocket-channel.js

@@ -49,7 +49,7 @@ export default class SyncWebsocketChannel extends VelociousWebsocketChannel {
    */
   async canSubscribe() {
     const resource = await this.buildSyncResource()
-    const scope = resource.changesScope({scope: {conditions: this.params.conditions, resourceType: this.params.resourceType}})
+    const scope = resource.changesScope({scope: {conditions: this.params.conditions, resourceType: this.params.resourceType, resourceTypes: this.params.resourceTypes}})
 
     await resource.authorizeChanges({params: this.params, scope})
 
@@ -107,6 +107,16 @@ export default class SyncWebsocketChannel extends VelociousWebsocketChannel {
    * conditions match by membership). Broadcasts without a resource type and
    * conditions the publisher's scoping params do not carry never match, so a
    * subscription cannot receive changes outside its authorized scope.
+   *
+   * The all-types (user) scope declares no single resource type - it subscribes
+   * once for every type it can apply, listed in `scope.resourceTypes` - so it
+   * matches a broadcast of any of those types. Types outside that list are
+   * dropped here, by this cheap check, and never reach the per-delivery access
+   * re-check in {@link SyncWebsocketChannel#_userScopeDeliverableBody}: that
+   * re-check checks out a database connection and runs a query per matched
+   * broadcast, so matching every type would put DB work on every broadcast for
+   * every subscribed device. A broadcast carrying no resource type at all still
+   * never matches.
    * @param {import("../http-server/websocket-channel.js").WebsocketJsonValue} broadcastParams - Publisher scoping params (the published resourceType plus the change's scope-partition values).
    * @returns {boolean} Whether the broadcast belongs to this subscription's scope.
    */
@@ -119,7 +129,13 @@ export default class SyncWebsocketChannel extends VelociousWebsocketChannel {
       ? /** @type {Record<string, ?>} */ (broadcastParams)
       : {}
 
-    if (!Object.hasOwn(scopingParams, "resourceType") || String(scopingParams.resourceType) !== String(scope.resourceType)) return false
+    if (!Object.hasOwn(scopingParams, "resourceType")) return false
+
+    if (scope.resourceType === null) {
+      if (scope.resourceTypes && !scope.resourceTypes.some((resourceType) => resourceType === String(scopingParams.resourceType))) return false
+    } else if (String(scopingParams.resourceType) !== String(scope.resourceType)) {
+      return false
+    }
 
     for (const [conditionName, conditionValue] of Object.entries(scope.conditions)) {
       if (!Object.hasOwn(scopingParams, conditionName)) return false

package/src/tenants/tenant-iterator.js

@@ -7,12 +7,12 @@
  * against the wrong connection. When iterating in parallel the per-tenant failures are
  * collected and rethrown together as an `AggregateError` so one bad tenant does not hide the
  * others. This is the iteration engine shared by the `db:tenants:*` CLI commands and the
- * runtime {@link Tenant} façade; the caller is responsible for producing the tenant list.
+ * runtime tenant façade; the caller is responsible for producing the tenant list.
  */
 export default class TenantIterator {
   /**
    * Creates an iterator bound to a configuration and tenant database identifier.
-   * @param {{configuration: import("../configuration.js").default, identifier: string, parallelCount?: number}} args
+   * @param {{configuration: import("../configuration.js").default, identifier: string, parallelCount?: number}} args - Tenant configuration, database identifier, and concurrency limit.
    */
   constructor({configuration, identifier, parallelCount = 1}) {
     this.configuration = configuration
@@ -22,9 +22,9 @@ export default class TenantIterator {
 
   /**
    * Runs `callback` within each tenant's context and returns how many tenants were processed.
-   * @param {Array<?>} tenants
-   * @param {function({databaseConfiguration: import("../configuration-types.js").DatabaseConfigurationType, tenant: ?}) : Promise<void>} callback
-   * @returns {Promise<number>}
+   * @param {Array<?>} tenants - Tenant descriptors to enter and process.
+   * @param {function({databaseConfiguration: import("../configuration-types.js").DatabaseConfigurationType, tenant: ?}) : Promise<void>} callback - Per-tenant operation receiving the active database configuration.
+   * @returns {Promise<number>} - Number of processed tenants.
    */
   async run(tenants, callback) {
     if (this.parallelCount <= 1) {
@@ -76,7 +76,7 @@ export default class TenantIterator {
 
   /**
    * Enters one tenant's context and runs the callback, asserting the database is active first.
-   * @param {{callback: function({databaseConfiguration: import("../configuration-types.js").DatabaseConfigurationType, tenant: ?}) : Promise<void>, tenant: ?}} args
+   * @param {{callback: function({databaseConfiguration: import("../configuration-types.js").DatabaseConfigurationType, tenant: ?}) : Promise<void>, tenant: ?}} args - Tenant descriptor and operation to run in its context.
    * @returns {Promise<void>}
    */
   async runTenantCallback({callback, tenant}) {
@@ -94,8 +94,8 @@ export default class TenantIterator {
 
   /**
    * Builds a human-readable label for a tenant for use in error messages.
-   * @param {?} tenant
-   * @returns {string}
+   * @param {?} tenant - Tenant descriptor to identify in an error.
+   * @returns {string} - Human-readable tenant label.
    */
   static tenantLabel(tenant) {
     if (tenant && typeof tenant === "object") {

package/src/tenants/tenant.js

@@ -26,8 +26,8 @@ export default class Tenant {
    * connections keyed by identifier, the same as `ensureConnections`.
    * @template T
    * @param {object} tenant Descriptor understood by the app's tenantDatabaseResolver.
-   * @param {(connections: Record<string, import("../database/drivers/base.js").default>) => Promise<T>} callback
-   * @returns {Promise<T>}
+   * @param {(connections: Record<string, import("../database/drivers/base.js").default>) => Promise<T>} callback - Operation to run with the tenant's active connections.
+   * @returns {Promise<T>} - Callback result from within the tenant context.
    */
   static async with(tenant, callback) {
     const configuration = Current.configuration()
@@ -37,7 +37,7 @@ export default class Tenant {
 
   /**
    * The current tenant descriptor, or undefined when running outside any tenant context.
-   * @returns {Record<string, unknown> | undefined}
+   * @returns {Record<string, unknown> | undefined} - Current async-context tenant descriptor, if any.
    */
   static current() {
     return Current.tenant()
@@ -49,8 +49,8 @@ export default class Tenant {
    * {@link Tenant.with}, the callback runs inside `ensureConnections` so each tenant's
    * database is queryable without the caller wiring up connections. Returns how many tenants
    * the callback ran for (after filtering).
-   * @param {{identifier: string, callback: function({databaseConfiguration: import("../configuration-types.js").DatabaseConfigurationType, tenant: ?}) : Promise<void>, parallel?: number, filter?: (tenant: ?) => boolean, configuration?: import("../configuration.js").default}} args
-   * @returns {Promise<number>}
+   * @param {{identifier: string, callback: function({databaseConfiguration: import("../configuration-types.js").DatabaseConfigurationType, tenant: ?}) : Promise<void>, parallel?: number, filter?: (tenant: ?) => boolean, configuration?: import("../configuration.js").default}} args - Tenant database identifier, per-tenant operation, filtering, and concurrency settings.
+   * @returns {Promise<number>} - Number of processed tenants.
    */
   static async each({identifier, callback, parallel = 1, filter, configuration = Current.configuration()}) {
     const provider = configuration.getTenantDatabaseProvider(identifier)
@@ -76,7 +76,7 @@ export default class Tenant {
 
   /**
    * Drops one tenant's database/schema through the provider's `dropDatabase` hook.
-   * @param {{identifier: string, tenant: object, configuration?: import("../configuration.js").default}} args
+   * @param {{identifier: string, tenant: object, configuration?: import("../configuration.js").default}} args - Tenant descriptor and database identifier to drop.
    * @returns {Promise<void>}
    */
   static async drop({identifier, tenant, configuration = Current.configuration()}) {

package/src/testing/test-runner.js

@@ -520,7 +520,12 @@ export default class TestRunner {
     if (!this._application) {
       this._application = new Application({
         configuration: this.getConfiguration(),
-        httpServer: {port: 31006},
+        // Run request handlers in the main thread (not worker threads) so they
+        // resolve DB work to the per-test shared connection set by
+        // {@link activateTestSharedConnections}. This lets request-type specs use
+        // transaction-based cleaning (their writes land inside the test's
+        // transaction and roll back) instead of truncating every table.
+        httpServer: {inProcess: true, port: 31006},
         type: "test-runner"
       })
 
@@ -531,6 +536,46 @@ export default class TestRunner {
     return this._application
   }
 
+  /**
+   * Pins each per-test connection as its pool's in-process test shared connection so
+   * HTTP request handlers dispatched during the test (which run in the main thread but
+   * in a fresh async context without the connection pin) resolve to the SAME connection
+   * — and therefore the same open transaction — as the test body. Pools that predate the
+   * shared-connection hook are skipped. Pair with {@link clearTestSharedConnections} in a
+   * finally.
+   * @returns {void}
+   */
+  activateTestSharedConnections() {
+    const configuration = this.getConfiguration()
+    const currentConnections = configuration.getCurrentConnections()
+
+    for (const identifier of Object.keys(currentConnections)) {
+      const pool = configuration.getDatabasePool(identifier)
+
+      // Tenant-scoped pools resolve a different connection per request tenant
+      // (via runWithTenant), so forcing a single shared connection would break
+      // per-request tenant resolution. Only share non-tenant pools; the tenant
+      // pool keeps resolving its own connection per request.
+      if (pool.getConfiguration().tenantOnly) {
+        continue
+      }
+      pool.setTestSharedConnection(currentConnections[identifier])
+    }
+  }
+
+  /**
+   * Clears the in-process test shared connection on every configured pool. Idempotent and
+   * safe to call when none was set.
+   * @returns {void}
+   */
+  clearTestSharedConnections() {
+    const configuration = this.getConfiguration()
+
+    for (const identifier of configuration.getDatabaseIdentifiers()) {
+      configuration.getDatabasePool(identifier).clearTestSharedConnection()
+    }
+  }
+
   /**
    * Runs request client.
    * @returns {Promise<RequestClient>} - Resolves with the request client.
@@ -941,28 +986,40 @@ export default class TestRunner {
               // stale async-context pin and force every later test onto a fresh checkout,
               // breaking isolation).
               await this.getConfiguration().ensureConnections({name: `Test: ${testDescription}`}, async () => {
-                try {
-                  clearDeliveries()
-                  for (const beforeEachData of newBeforeEaches) {
-                    await beforeEachData.callback({configuration: this.getConfiguration(), testArgs, testData})
-                  }
+                // Only request-type tests dispatch through the in-process HTTP handler,
+                // so only they need the pinned connection shared with it. Sharing it for
+                // every test would let unrelated specs observe a test shared connection on
+                // pools they inspect directly. Cleared after afterEach either way.
+                if (testArgs.type == "request") {
+                  this.activateTestSharedConnections()
+                }
 
-                  // Record which test is running so an async crash (an unhandled
-                  // rejection detached from any await) that fires during or shortly
-                  // after this test can be attributed to it in run()'s handler.
-                  this._lastTestContext = {
-                    fullDescription: this.buildFullDescription(descriptions, testDescription),
-                    filePath: testData.filePath ?? "<unknown>",
-                    line: testData.line ?? 0
-                  }
-                  await testData.function(testArgs)
-                  if (!timeoutState.timedOut) {
-                    this._successfulTests++
+                try {
+                  try {
+                    clearDeliveries()
+                    for (const beforeEachData of newBeforeEaches) {
+                      await beforeEachData.callback({configuration: this.getConfiguration(), testArgs, testData})
+                    }
+
+                    // Record which test is running so an async crash (an unhandled
+                    // rejection detached from any await) that fires during or shortly
+                    // after this test can be attributed to it in run()'s handler.
+                    this._lastTestContext = {
+                      fullDescription: this.buildFullDescription(descriptions, testDescription),
+                      filePath: testData.filePath ?? "<unknown>",
+                      line: testData.line ?? 0
+                    }
+                    await testData.function(testArgs)
+                    if (!timeoutState.timedOut) {
+                      this._successfulTests++
+                    }
+                  } finally {
+                    for (const afterEachData of newAfterEaches) {
+                      await afterEachData.callback({configuration: this.getConfiguration(), testArgs, testData})
+                    }
                   }
                 } finally {
-                  for (const afterEachData of newAfterEaches) {
-                    await afterEachData.callback({configuration: this.getConfiguration(), testArgs, testData})
-                  }
+                  this.clearTestSharedConnections()
                 }
               })
             })
@@ -996,6 +1053,15 @@ export default class TestRunner {
             if (timedOut && testLifecycle) {
               timeoutState.timedOut = true
               await awaitSettledOrGrace(testLifecycle, timeoutMs ?? 60000)
+
+              // If the abandoned lifecycle never settled within the grace, its
+              // `finally` (which clears the shared connections) has not run, so
+              // this test's shared connection — sitting on a still-open, timed-out
+              // transaction — would otherwise be reused by the next test's outer
+              // ensureConnections before activateTestSharedConnections() replaces
+              // it. Clear it here so the next test checks out a fresh connection.
+              // Idempotent when the lifecycle did settle and already cleared.
+              this.clearTestSharedConnections()
             }
 
             willRetry = retriesUsed < retryCount