velocious 1.0.502 → 1.0.504

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

@@ -0,0 +1,146 @@
+// @ts-check
+
+import VelociousWebsocketChannel from "../http-server/websocket-channel.js"
+import {VELOCIOUS_SYNC_CHANNEL} from "./sync-channel-name.js"
+
+/** Configurations whose framework sync channel has already been registered. */
+const registeredConfigurations = new WeakSet()
+
+/**
+ * Framework-owned websocket channel for synced resources
+ * ({@link VELOCIOUS_SYNC_CHANNEL}).
+ *
+ * Subscribe params mirror a declared pull scope — `{resourceType, conditions}`
+ * plus the client-injected `authenticationToken` — and subscribe-time
+ * authorization delegates to the app sync resource's existing
+ * `authorizeChanges({params, scope})` (the `sync.api.resourceClass`), so apps
+ * hook in through the authorization they already declared instead of writing
+ * their own channel classes. Broadcast routing matches the publisher's
+ * scoping params against the subscription's scope conditions.
+ */
+export default class SyncWebsocketChannel extends VelociousWebsocketChannel {
+  /**
+   * Scope the subscription was authorized for, set by {@link SyncWebsocketChannel#canSubscribe}.
+   * @type {import("./sync-resource-base.js").SerializedChangesScope | null}
+   */
+  _scope = null
+
+  /**
+   * Registers the framework sync channel on a configuration declaring a
+   * `sync.api` block (guarded so repeated server boots with the same
+   * configuration register it only once). No-op without `sync.api` — the
+   * channel authorizes through the app's sync resource class.
+   * @param {import("../configuration.js").default} configuration - Configuration instance.
+   * @returns {void}
+   */
+  static registerFromConfiguration(configuration) {
+    if (!configuration.getSyncConfiguration().api || registeredConfigurations.has(configuration)) return
+
+    registeredConfigurations.add(configuration)
+    configuration.registerWebsocketChannel(VELOCIOUS_SYNC_CHANNEL, this)
+  }
+
+  /**
+   * Authorizes the subscription through the app sync resource: the subscribe
+   * params are parsed into the same serialized scope the changes endpoint
+   * consumes and passed to the resource's `authorizeChanges({params, scope})`.
+   * Denials and malformed scopes throw, rejecting the subscription.
+   * @returns {Promise<boolean>} Whether the subscription is allowed.
+   */
+  async canSubscribe() {
+    const resource = await this.buildSyncResource()
+    const scope = resource.changesScope({scope: {conditions: this.params.conditions, resourceType: this.params.resourceType}})
+
+    await resource.authorizeChanges({params: this.params, scope})
+
+    this._scope = scope
+
+    return true
+  }
+
+  /**
+   * Builds the app sync resource authorizing this subscription, mirroring the
+   * sync transport controller's resource construction with the ability
+   * resolved from the subscribe params (which carry the client-injected
+   * authenticationToken).
+   * @returns {Promise<import("./sync-resource-base.js").default>} App sync resource instance.
+   */
+  async buildSyncResource() {
+    const configuration = this.session.configuration
+    const api = configuration.getSyncConfiguration().api
+
+    if (!api) {
+      throw new Error(`The ${VELOCIOUS_SYNC_CHANNEL} channel requires a sync.api configuration block with the app's sync resource class`)
+    }
+
+    // Narrows the configured resource class to the sync resource contract
+    // (changesScope/authorizeChanges) the sync.api validation requires.
+    const ResourceClass = /** @type {typeof import("./sync-resource-base.js").default} */ (api.resourceClass)
+    // Narrows the websocket subscribe params to the resource params contract.
+    const params = /** @type {import("../configuration-types.js").VelociousParams} */ (/** @type {unknown} */ (this.params))
+    const request = this.session.upgradeRequest
+    const ability = await configuration.resolveAbility({params, request})
+
+    return new ResourceClass({
+      ability,
+      context: {
+        ...(ability?.getContext() || {}),
+        params,
+        request
+      },
+      locals: ability?.getLocals() || {},
+      modelClass: ResourceClass.ModelClass,
+      modelName: ResourceClass.ModelClass?.name,
+      params,
+      resourceConfiguration: /** @type {import("../configuration-types.js").FrontendModelResourceConfiguration} */ ({
+        attributes: ResourceClass.attributes || {},
+        sync: {enabled: true}
+      })
+    })
+  }
+
+  /**
+   * Routes a publisher broadcast to this subscription when the published
+   * resource type equals the type the subscription was authorized for and the
+   * scoping params satisfy every scope condition: each condition key must be
+   * present in the broadcast params and match by string comparison (array
+   * 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.
+   * @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.
+   */
+  matches(broadcastParams) {
+    const scope = this._scope
+
+    if (!scope) return false
+
+    const scopingParams = broadcastParams && typeof broadcastParams === "object" && !Array.isArray(broadcastParams)
+      ? /** @type {Record<string, ?>} */ (broadcastParams)
+      : {}
+
+    if (!Object.hasOwn(scopingParams, "resourceType") || String(scopingParams.resourceType) !== String(scope.resourceType)) return false
+
+    for (const [conditionName, conditionValue] of Object.entries(scope.conditions)) {
+      if (!Object.hasOwn(scopingParams, conditionName)) return false
+
+      const scopingValue = scopingParams[conditionName]
+
+      if (Array.isArray(conditionValue)) {
+        if (!conditionValue.some((value) => String(value) === String(scopingValue))) return false
+      } else if (String(conditionValue) !== String(scopingValue)) {
+        return false
+      }
+    }
+
+    return true
+  }
+
+  /**
+   * Returns the authorized scope for debug snapshots.
+   * @returns {Record<string, ?>} Debug-safe subscription details.
+   */
+  debugSnapshot() {
+    return {scope: this._scope}
+  }
+}

package/src/testing/test-runner.js

@@ -13,8 +13,20 @@ import {testConfig, testEvents, tests} from "./test.js"
 import {pathToFileURL} from "url"
 import {clearDeliveries} from "../mailer.js"
 
+/**
+ * Marks the error thrown by {@link runWithTimeout} so the caller can tell a
+ * lifecycle timeout (the promise is still running detached) apart from an
+ * ordinary test failure (the promise already settled).
+ * @typedef {Error & {velociousTestTimeout?: true}} TestTimeoutError
+ */
+
 /**
  * Runs run with timeout.
+ *
+ * On timeout the wrapped `promise` is NOT cancelled — it keeps running detached.
+ * The rejected error is tagged with `velociousTestTimeout` so the runner knows
+ * the lifecycle (and its afterEach database cleanup) is still in flight and can
+ * wait for it to settle before the next test reuses the shared connection.
  * @param {Promise<?> | ?} promise - Promise or value.
  * @param {number} timeoutMs - Timeout in milliseconds.
  * @param {string} testDescription - Test description.
@@ -22,7 +34,9 @@ import {clearDeliveries} from "../mailer.js"
  */
 function runWithTimeout(promise, timeoutMs, testDescription) {
   const timeoutSeconds = (timeoutMs / 1000).toFixed(3).replace(/\.?0+$/, "")
+  /** @type {TestTimeoutError} */
   const timeoutError = new Error(`Timed out after ${timeoutSeconds}s: ${testDescription}`)
+  timeoutError.velociousTestTimeout = true
 
   return new Promise((resolve, reject) => {
     const timeout = setTimeout(() => reject(timeoutError), timeoutMs)
@@ -37,6 +51,38 @@ function runWithTimeout(promise, timeoutMs, testDescription) {
   })
 }
 
+/**
+ * Waits for an abandoned (timed-out) test lifecycle to settle, bounded by a
+ * grace period, so its afterEach database cleanup runs on the shared connection
+ * before the next test reuses it. Resolves early the moment the lifecycle
+ * settles; otherwise resolves once the grace elapses (never rejects, and never
+ * keeps the process alive on its own).
+ * @param {Promise<?>} lifecycle - The abandoned per-test lifecycle promise.
+ * @param {number} graceMs - Maximum time to wait for the lifecycle to settle.
+ * @returns {Promise<boolean>} - Whether the lifecycle settled within the grace period.
+ */
+function awaitSettledOrGrace(lifecycle, graceMs) {
+  return new Promise((resolve) => {
+    let settled = false
+    const graceTimer = setTimeout(() => {
+      if (settled) return
+
+      settled = true
+      resolve(false)
+    }, graceMs)
+
+    if (typeof graceTimer.unref === "function") graceTimer.unref()
+
+    Promise.resolve(lifecycle).then(() => {}, () => {}).then(() => {
+      if (settled) return
+
+      settled = true
+      clearTimeout(graceTimer)
+      resolve(true)
+    })
+  })
+}
+
 /**
  * ConsoleMethodName type.
  * @typedef {"log" | "info" | "warn" | "error" | "debug"} ConsoleMethodName */
@@ -862,6 +908,11 @@ export default class TestRunner {
            * @type {?} */
           let lastError
           let willRetry = false
+          /**
+           * The per-test lifecycle promise, hoisted so the timeout branch can
+           * still wait for it to settle after runWithTimeout has abandoned it.
+           * @type {Promise<?> | undefined} */
+          let testLifecycle
           const stopConsoleCapture = this.startConsoleCapture({
             passthrough: testConfig.consoleOutput === "live"
           })
@@ -870,7 +921,7 @@ export default class TestRunner {
             // Run the whole per-test lifecycle (dummy/server startup, connection
             // acquisition, beforeEach hooks, the test body and afterEach hooks) as
             // one promise so the timeout below can cover all of it.
-            const testLifecycle = this.runWithDummyIfNeeded(testArgs, async () => {
+            testLifecycle = this.runWithDummyIfNeeded(testArgs, async () => {
               // Pin one connection per test so beforeEach, the test body and afterEach
               // all run on the SAME connection. This is required for transaction-based
               // database cleaning (beforeEach starts a transaction, afterEach rolls it
@@ -917,6 +968,23 @@ export default class TestRunner {
           } catch (error) {
             caughtError = error
             lastError = error
+
+            // A timeout REJECTS while the lifecycle keeps running detached on the
+            // shared per-suite connection — including its afterEach database
+            // cleanup (e.g. transaction rollback). If the next test starts before
+            // that rollback runs, its own startTransaction() implicitly COMMITS
+            // the timed-out test's rows on the shared connection, poisoning every
+            // later test in the shard (duplicate-key / foreign-key cascades from
+            // leaked fixtures). Wait — bounded — for the abandoned lifecycle to
+            // settle so its cleanup lands first. Bounded so a genuinely hung test
+            // still can't stall the whole run: if it will not settle within the
+            // grace, we proceed exactly as before (no worse than today).
+            const timedOut = Boolean(/** @type {TestTimeoutError} */ (error)?.velociousTestTimeout)
+
+            if (timedOut && testLifecycle) {
+              await awaitSettledOrGrace(testLifecycle, timeoutMs ?? 60000)
+            }
+
             willRetry = retriesUsed < retryCount
 
             if (willRetry) {