velocious 1.0.475 → 1.0.476

package/src/environment-handlers/node/cli/commands/generate/base-models.js

@@ -120,6 +120,7 @@ export default class DbGenerateModel extends BaseCommand {
 
         const columns = await table.getColumns()
         const writeAttributeTypeName = `${modelNameCamelized}WriteAttributes`
+        const belongsToWriteAttributes = await this.belongsToWriteAttributesForModel({modelClass, modelsDir})
         const nestedWriteAttributes = this.nestedWriteAttributesForModel({modelClass})
 
         fileContent += `import DatabaseRecord from "${velociousPath}/database/record/index.js"\n\n`
@@ -135,6 +136,9 @@ export default class DbGenerateModel extends BaseCommand {
             fileContent += ` * @property {${setterJsdocType}${column.getNull() ? " | null" : ""}} [${camelizedColumnName}] - Value for the ${camelizedColumnName} attribute.\n`
           }
         }
+        for (const belongsToWriteAttribute of belongsToWriteAttributes) {
+          fileContent += ` * @property {${belongsToWriteAttribute.propertyType}} [${belongsToWriteAttribute.propertyName}] - Related ${belongsToWriteAttribute.relationshipName} record.\n`
+        }
         for (const nestedWriteAttribute of nestedWriteAttributes) {
           fileContent += ` * @property {${nestedWriteAttribute.propertyType}} [${nestedWriteAttribute.propertyName}] - Nested ${nestedWriteAttribute.relationshipName} attributes.\n`
         }
@@ -440,6 +444,38 @@ export default class DbGenerateModel extends BaseCommand {
     return this.jsDocTypeFromColumn(column, modelClass)
   }
 
+  /**
+   * Runs belongs to write attributes for model.
+   * @param {object} args - Arguments.
+   * @param {typeof import("../../../../../database/record/index.js").default} args.modelClass - Model class.
+   * @param {string} args.modelsDir - Source models directory.
+   * @returns {Promise<Array<{propertyName: string, propertyType: string, relationshipName: string}>>} - Belongs-to write attributes.
+   */
+  async belongsToWriteAttributesForModel({modelClass, modelsDir}) {
+    const writeAttributes = []
+
+    for (const relationship of modelClass.getRelationships()) {
+      if (relationship.getType() !== "belongsTo") continue
+      if (relationship.getPolymorphic()) continue
+
+      const targetModelClass = relationship.getTargetModelClass()
+
+      if (!targetModelClass) throw new Error(`Relationship '${relationship.getRelationshipName()}' on '${modelClass.getModelName()}' has no target model class`)
+
+      const targetModelFileName = inflection.dasherize(inflection.underscore(targetModelClass.getModelName()))
+      const targetModelPath = `${modelsDir}/${targetModelFileName}.js`
+      const targetImportPath = await fileExists(targetModelPath) ? `../models/${targetModelFileName}.js` : `./${targetModelFileName}.js`
+
+      writeAttributes.push({
+        propertyName: relationship.getRelationshipName(),
+        propertyType: `import("${targetImportPath}").default`,
+        relationshipName: relationship.getRelationshipName()
+      })
+    }
+
+    return writeAttributes
+  }
+
   /**
    * Runs nested write attributes for model.
    * @param {object} args - Arguments.

package/src/frontend-model-controller.js

@@ -6,7 +6,8 @@ import FrontendModelBaseResource from "./frontend-model-resource/base-resource.j
 import Response from "./http-server/client/response.js"
 import {frontendModelResourcesWithBuiltInsForBackendProject} from "./frontend-models/built-in-resources.js"
 import {frontendModelResourceClassFromDefinition, frontendModelResourceConfigurationFromDefinition, frontendModelResourcePath, frontendModelResourcesForBackendProject, frontendModelSyncManifestForBackendProjects} from "./frontend-models/resource-definition.js"
-import {createOfflineGrantFromBootstrap} from "./sync/offline-grant.js"
+import {createOfflineGrantFromBootstrap, verifyOfflineGrant} from "./sync/offline-grant.js"
+import {mutationIdempotencyKey, verifySignedMutation} from "./sync/device-identity.js"
 import {FrontendModelQueryError, normalizeGroup as normalizeQueryGroup, normalizeJoins as normalizeQueryJoins, normalizePluck as normalizeQueryPluck, normalizePreload as normalizeQueryPreload, normalizeSearchOperator as normalizeQuerySearchOperator, normalizeSort as normalizeQuerySort} from "./frontend-models/query.js"
 import {assignSafeProperty, deserializeFrontendModelTransportValue, isBackendModelInstance, serializeFrontendModelTransportValue} from "./frontend-models/transport-serialization.js"
 import {requestDetails} from "./error-reporting/request-details.js"
@@ -172,6 +173,19 @@ const frontendModelWhereNoMatchSymbol = Symbol("frontendModelWhereNoMatch")
 const frontendModelClientSafeErrorMessage = "Request failed."
 const frontendModelDebugErrorEnvironments = new Set(["development", "test"])
 
+/**
+ * Builds a client-safe sync replay validation error.
+ * @param {string} message - Client-safe validation message.
+ * @param {unknown} [cause] - Original cause.
+ * @returns {VelociousError} - Client-safe replay error.
+ */
+function frontendSyncReplaySafeError(message, cause) {
+  return VelociousError.safe(message, {
+    cause,
+    code: "frontend_sync_replay_error"
+  })
+}
+
 /**
  * Runs frontend model query metadata.
  * @param {import("./database/query/model-class-query.js").default} query - Query instance.
@@ -3561,6 +3575,266 @@ export default class FrontendModelController extends Controller {
     throw new Error("Expected sync bootstrap current user")
   }
 
+  /**
+   * Runs frontend sync replay.
+   * @returns {Promise<void>} - Sync replay response with per-mutation results.
+   */
+  async frontendSyncReplay() {
+    if (this.request().httpMethod() === "OPTIONS") {
+      await this.render({status: 204, json: {}})
+      return
+    }
+
+    const params = /** @type {Record<string, ?>} */ (deserializeFrontendModelTransportValue(this.params()))
+    const signedMutations = this.frontendSyncReplaySignedMutations(params)
+    const results = []
+
+    for (const signedMutation of signedMutations) {
+      let idempotencyKey = null
+
+      try {
+        idempotencyKey = mutationIdempotencyKey(/** @type {import("./sync/device-identity.js").SignedSyncMutation} */ (signedMutation))
+        const response = await this.frontendSyncReplaySignedMutation(signedMutation)
+
+        results.push({idempotencyKey, response, status: "success"})
+      } catch (error) {
+        const errorContext = this.frontendModelEndpointErrorContext({
+          action: "frontendSyncReplay",
+          commandType: signedMutation && typeof signedMutation === "object" && "mutation" in signedMutation
+            ? /** @type {{mutation?: {operation?: ?}}} */ (signedMutation).mutation?.operation
+            : undefined,
+          error,
+          model: signedMutation && typeof signedMutation === "object" && "mutation" in signedMutation
+            ? /** @type {{mutation?: {model?: ?}}} */ (signedMutation).mutation?.model
+            : undefined
+        })
+
+        await this.frontendModelLogEndpointError({
+          action: errorContext.action,
+          commandType: errorContext.commandType,
+          error,
+          model: errorContext.model
+        })
+
+        results.push({
+          idempotencyKey,
+          response: await this.frontendModelClientErrorPayloadForError(error, errorContext),
+          status: "error"
+        })
+      }
+    }
+
+    await this.render({
+      json: /** @type {Record<string, ?>} */ (serializeFrontendModelTransportValue({
+        results,
+        status: "success"
+      }, this.transportSerializationOptions()))
+    })
+  }
+
+  /**
+   * Resolves signed replay mutations from request params.
+   * @param {Record<string, ?>} params - Request params.
+   * @returns {Array<?>} - Signed mutation envelopes.
+   */
+  frontendSyncReplaySignedMutations(params) {
+    if (Array.isArray(params.mutations)) return params.mutations
+    if (params.mutation) return [params.mutation]
+
+    throw new Error("Expected sync replay mutation or mutations")
+  }
+
+  /**
+   * Verifies and replays one signed sync mutation.
+   * @param {?} signedMutation - Signed mutation envelope.
+   * @returns {Promise<Record<string, ?>>} - Frontend-model command response.
+   */
+  async frontendSyncReplaySignedMutation(signedMutation) {
+    const configuration = this.getConfiguration()
+    const syncConfiguration = configuration.getSyncConfiguration()
+    const backendPublicKey = syncConfiguration.deviceCertificateBackendPublicKey
+
+    if (!backendPublicKey) throw frontendSyncReplaySafeError("sync.deviceCertificateBackendPublicKey is required for sync replay")
+
+    let mutation
+
+    try {
+      mutation = await verifySignedMutation({
+        backendPublicKey,
+        signedMutation: /** @type {import("./sync/device-identity.js").SignedSyncMutation} */ (signedMutation)
+      })
+    } catch (error) {
+      throw frontendSyncReplaySafeError(error instanceof Error ? error.message : String(error), error)
+    }
+
+    const syncManifest = frontendModelSyncManifestForBackendProjects(configuration.getBackendProjects())
+    const syncResource = syncManifest[mutation.model]
+
+    if (!syncResource) throw frontendSyncReplaySafeError(`Sync replay model is not enabled: ${mutation.model}`)
+    if (!syncResource.operations.includes(mutation.operation)) {
+      throw frontendSyncReplaySafeError(`Sync replay operation is not enabled for ${mutation.model}: ${mutation.operation}`)
+    }
+    if (syncResource.policyHash !== mutation.policyHash) {
+      throw frontendSyncReplaySafeError(`Sync replay policy hash mismatch for ${mutation.model}`)
+    }
+    if (!["create", "update", "destroy"].includes(mutation.operation)) {
+      throw frontendSyncReplaySafeError(`Sync replay operation is not supported yet: ${mutation.operation}`)
+    }
+
+    const signedOfflineGrant = this.frontendSyncReplaySignedOfflineGrant(signedMutation)
+    const offlineGrant = await this.frontendSyncReplayVerifiedOfflineGrant({
+      signedOfflineGrant,
+      signingKeys: syncConfiguration.offlineGrantSigningKeys
+    })
+
+    this.frontendSyncReplayValidateOfflineGrant({mutation, offlineGrant, syncResource})
+
+    const commandParams = await this.frontendSyncReplayCommandParams(mutation)
+
+    try {
+      return await this.withFrontendModelParams(commandParams, async () => {
+        return await this.withFrontendModelRequestContext(commandParams, this.response(), async () => {
+          return await this.frontendModelCommandPayload(/** @type {"create" | "update" | "destroy"} */ (mutation.operation)) || this.frontendModelErrorPayload("Action halted by beforeAction.")
+        })
+      })
+    } catch (error) {
+      const errorContext = this.frontendModelEndpointErrorContext({
+        action: "frontendSyncReplay",
+        commandType: /** @type {"create" | "update" | "destroy"} */ (mutation.operation),
+        error,
+        model: mutation.model
+      })
+
+      await this.frontendModelLogEndpointError({
+        action: errorContext.action,
+        commandType: errorContext.commandType,
+        error,
+        model: errorContext.model
+      })
+
+      return await this.frontendModelClientErrorPayloadForError(error, errorContext)
+    }
+  }
+
+  /**
+   * Resolves the signed offline grant carried by a replay request.
+   * @param {?} signedMutation - Signed mutation envelope.
+   * @returns {?} - Signed offline grant envelope.
+   */
+  frontendSyncReplaySignedOfflineGrant(signedMutation) {
+    if (!signedMutation || typeof signedMutation !== "object" || Array.isArray(signedMutation)) {
+      throw frontendSyncReplaySafeError("Expected sync replay signed offline grant")
+    }
+
+    const signedMutationRecord = /** @type {Record<string, ?>} */ (signedMutation)
+    const signedOfflineGrant = signedMutationRecord.signedOfflineGrant || signedMutationRecord.offlineGrant || signedMutationRecord.signedGrant
+
+    if (!signedOfflineGrant) throw frontendSyncReplaySafeError("Expected sync replay signed offline grant")
+
+    return signedOfflineGrant
+  }
+
+  /**
+   * Verifies a sync replay signed offline grant.
+   * @param {object} args - Arguments.
+   * @param {?} args.signedOfflineGrant - Signed offline grant envelope.
+   * @param {import("./sync/offline-grant.js").OfflineGrantSigningKey[]} args.signingKeys - Available signing keys.
+   * @returns {Promise<import("./sync/offline-grant.js").OfflineGrant>} - Verified offline grant.
+   */
+  async frontendSyncReplayVerifiedOfflineGrant({signedOfflineGrant, signingKeys}) {
+    try {
+      return await verifyOfflineGrant({
+        now: new Date(),
+        signedGrant: /** @type {import("./sync/offline-grant.js").SignedOfflineGrant} */ (signedOfflineGrant),
+        signingKeys
+      })
+    } catch (error) {
+      throw frontendSyncReplaySafeError(error instanceof Error ? error.message : String(error), error)
+    }
+  }
+
+  /**
+   * Validates that a verified offline grant authorizes a replayed mutation.
+   * @param {object} args - Arguments.
+   * @param {import("./sync/device-identity.js").SyncMutation} args.mutation - Verified mutation.
+   * @param {import("./sync/offline-grant.js").OfflineGrant} args.offlineGrant - Verified grant.
+   * @param {Record<string, ?>} args.syncResource - Current sync resource entry.
+   * @returns {void} - Throws when unauthorized.
+   */
+  frontendSyncReplayValidateOfflineGrant({mutation, offlineGrant, syncResource}) {
+    if (offlineGrant.grantId !== mutation.offlineGrantId) {
+      throw frontendSyncReplaySafeError("Sync replay offline grant does not match mutation")
+    }
+    if (offlineGrant.deviceId !== mutation.actorDeviceId) {
+      throw frontendSyncReplaySafeError("Sync replay offline grant device does not match mutation")
+    }
+    if (offlineGrant.userId !== mutation.actorUserId) {
+      throw frontendSyncReplaySafeError("Sync replay offline grant user does not match mutation")
+    }
+
+    const grantResource = /** @type {Record<string, ?> | undefined} */ (offlineGrant.resources[mutation.model])
+    const grantOperations = Array.isArray(grantResource?.operations) ? grantResource.operations : []
+    const grantPolicyHash = grantResource?.policyHash
+
+    if (!grantResource || grantResource.enabled !== true) throw frontendSyncReplaySafeError(`Sync replay offline grant does not authorize ${mutation.model}`)
+    if (!grantOperations.includes(mutation.operation)) {
+      throw frontendSyncReplaySafeError(`Sync replay offline grant does not authorize ${mutation.model}: ${mutation.operation}`)
+    }
+    if (grantPolicyHash !== mutation.policyHash || grantPolicyHash !== syncResource.policyHash) {
+      throw frontendSyncReplaySafeError(`Sync replay offline grant policy hash mismatch for ${mutation.model}`)
+    }
+    if (!offlineGrant.scopes || typeof offlineGrant.scopes !== "object" || Array.isArray(offlineGrant.scopes)) {
+      throw frontendSyncReplaySafeError("Sync replay offline grant scopes are invalid")
+    }
+  }
+
+  /**
+   * Builds frontend-model command params for a verified replay mutation.
+   * @param {import("./sync/device-identity.js").SyncMutation} mutation - Verified mutation.
+   * @returns {Promise<Record<string, ?>>} - Frontend-model command params.
+   */
+  async frontendSyncReplayCommandParams(mutation) {
+    const payload = mutation.payload && typeof mutation.payload === "object" && !Array.isArray(mutation.payload) ? mutation.payload : {}
+    const {attributes, primaryKeyValue} = await this.frontendSyncReplayCommandAttributes(mutation)
+    const commandParams = /** @type {Record<string, ?>} */ ({
+      ...payload,
+      attributes,
+      model: mutation.model
+    })
+
+    if (mutation.operation !== "create") {
+      const id = commandParams.id || commandParams.recordId || primaryKeyValue
+
+      if (typeof id !== "string" && typeof id !== "number") throw frontendSyncReplaySafeError(`Sync replay ${mutation.operation} requires an id`)
+
+      commandParams.id = id
+    }
+
+    return commandParams
+  }
+
+  /**
+   * Resolves command attributes and primary key from a replay mutation.
+   * @param {import("./sync/device-identity.js").SyncMutation} mutation - Verified mutation.
+   * @returns {Promise<{attributes: Record<string, ?>, primaryKeyValue: string | number | undefined}>} - Command attributes and primary key value.
+   */
+  async frontendSyncReplayCommandAttributes(mutation) {
+    const attributes = /** @type {Record<string, ?>} */ ({...(mutation.attributes || {})})
+    const frontendModelResource = this.getConfiguration().getBackendProjects()
+      .map((backendProject) => this.frontendModelResourceConfigurationForBackendProjectModelName({backendProject, modelName: mutation.model}))
+      .find((resourceConfiguration) => resourceConfiguration)
+
+    if (!frontendModelResource) return {attributes, primaryKeyValue: undefined}
+
+    const primaryKey = typeof frontendModelResource.resourceConfiguration.primaryKey === "string" ? frontendModelResource.resourceConfiguration.primaryKey : "id"
+    const primaryKeyAttribute = attributes[primaryKey]
+    const primaryKeyValue = typeof primaryKeyAttribute === "string" || typeof primaryKeyAttribute === "number" ? primaryKeyAttribute : undefined
+
+    if (primaryKeyValue !== undefined && mutation.operation !== "create") delete attributes[primaryKey]
+
+    return {attributes, primaryKeyValue}
+  }
+
   /**
    * Runs frontend api.
    * @returns {Promise<void>} - Shared frontend model API action with batch support.

package/src/routes/hooks/frontend-model-command-route-hook.js

@@ -25,6 +25,14 @@ export default async function frontendModelCommandRouteHook({configuration, curr
     }
   }
 
+  if (normalizedCurrentPath === "/frontend-models/sync/replay") {
+    return {
+      action: "frontend-sync-replay",
+      controller: "velocious/api",
+      controllerPath: FRONTEND_MODEL_CONTROLLER_PATH
+    }
+  }
+
   if (normalizedCurrentPath === SHARED_FRONTEND_MODEL_API_PATH) {
     return {
       action: "frontend-api",