@edgedev/firebase 2.2.80 → 2.2.82

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgedev/firebase",
-  "version": "2.2.80",
+  "version": "2.2.82",
   "description": "Vue 3 / Nuxt 3 Plugin or Nuxt 3 plugin for firebase authentication and firestore.",
   "main": "index.ts",
   "scripts": {

package/src/cms.js

@@ -1839,12 +1839,18 @@ const buildBlockAiPrompt = ({
   ].join('\n')
 }
 
+const assertCallableUser = (request) => {
+  if (!request?.auth?.uid)
+    throw new HttpsError('unauthenticated', 'Authentication required.')
+  if (request?.data?.uid !== request.auth.uid)
+    throw new HttpsError('permission-denied', 'UID mismatch.')
+}
+
 exports.updateSeoFromAi = onCall({ timeoutSeconds: 180 }, async (request) => {
+  assertCallableUser(request)
   const data = request.data || {}
   const auth = request.auth
-  const { orgId, siteId, pageId, uid } = data
-  if (!auth?.uid || auth.uid !== uid)
-    throw new HttpsError('permission-denied', 'Unauthorized')
+  const { orgId, siteId, pageId } = data
   if (!orgId || !siteId || !pageId)
     throw new HttpsError('invalid-argument', 'Missing orgId, siteId, or pageId')
   const allowed = await permissionCheck(auth.uid, 'write', `organizations/${orgId}/sites/${siteId}/pages`)
@@ -1910,9 +1916,7 @@ exports.updateSeoFromAi = onCall({ timeoutSeconds: 180 }, async (request) => {
 })
 
 exports.getCloudflarePagesProject = onCall(async (request) => {
-  if (!request?.auth) {
-    throw new HttpsError('unauthenticated', 'Authentication required.')
-  }
+  assertCallableUser(request)
 
   if (!CLOUDFLARE_PAGES_PROJECT) {
     logger.warn('CLOUDFLARE_PAGES_PROJECT is not set.')
@@ -1923,12 +1927,10 @@ exports.getCloudflarePagesProject = onCall(async (request) => {
 })
 
 exports.generateBlockFields = onCall({ timeoutSeconds: 180 }, async (request) => {
+  assertCallableUser(request)
   const data = request.data || {}
   const auth = request.auth
-  const { orgId, uid, blockId, blockName, content, fields, currentValues, meta, instructions } = data
-
-  if (!auth?.uid || auth.uid !== uid)
-    throw new HttpsError('permission-denied', 'Unauthorized')
+  const { orgId, blockId, blockName, content, fields, currentValues, meta, instructions } = data
   if (!orgId || !blockId)
     throw new HttpsError('invalid-argument', 'Missing orgId or blockId')
   if (!Array.isArray(fields) || fields.length === 0)

package/src/edgeFirebase.js

@@ -14,6 +14,13 @@ function formatPhoneNumber(phone) {
   return `+1${numericPhone}`
 }
 
+const assertCallableUser = (request) => {
+  if (!request?.auth?.uid)
+    throw new HttpsError('unauthenticated', 'Authentication required.')
+  if (request?.data?.uid !== request.auth.uid)
+    throw new HttpsError('permission-denied', 'UID mismatch.')
+}
+
 exports.uploadDocumentDeleted = onDocumentDeleted(
   { document: 'organizations/{orgId}/files/{docId}', timeoutSeconds: 180 },
   async (event) => {
@@ -34,21 +41,19 @@ exports.uploadDocumentDeleted = onDocumentDeleted(
 )
 
 exports.addUpdateFileDoc = onCall(async (request) => {
+  assertCallableUser(request)
   const data = request.data
-  const auth = request.auth
   let docId = data?.docId
-  if (data.uid === auth.uid) {
-    console.log(data)
-    const orgId = data.orgId
-    if (docId) {
-      const docRef = db.collection(`organizations/${orgId}/files`).doc(docId)
-      await docRef.set(data, { merge: true })
-    }
-    else {
-      const docRef = db.collection(`organizations/${orgId}/files`).doc()
-      await docRef.set(data)
-      docId = docRef.id
-    }
+  console.log(data)
+  const orgId = data.orgId
+  if (docId) {
+    const docRef = db.collection(`organizations/${orgId}/files`).doc(docId)
+    await docRef.set(data, { merge: true })
+  }
+  else {
+    const docRef = db.collection(`organizations/${orgId}/files`).doc()
+    await docRef.set(data)
+    docId = docRef.id
   }
   console.log(docId)
   return { docId }
@@ -426,91 +431,87 @@ exports.initFirestore = onCall(async (request) => {
 })
 
 exports.removeNonRegisteredUser = onCall(async (request) => {
+  assertCallableUser(request)
   const data = request.data
-  const auth = request.auth
-  if (data.uid === auth.uid) {
-    const stagedUser = await db.collection('staged-users').doc(data.docId).get()
-    if (stagedUser.exists) {
-      const stagedUserData = stagedUser.data()
-
-      const rolesExist = stagedUserData.roles && Object.keys(stagedUserData.roles).length !== 0
-      const specialPermissionsExist = stagedUserData.specialPermissions && Object.keys(stagedUserData.specialPermissions).length !== 0
-      const userIdExistsAndNotBlank = stagedUserData.userId && stagedUserData.userId !== ''
-
-      if (!rolesExist && !specialPermissionsExist && !userIdExistsAndNotBlank) {
-        await db.collection('staged-users').doc(data.docId).delete()
-        return { success: true, message: '' }
+  const stagedUser = await db.collection('staged-users').doc(data.docId).get()
+  if (stagedUser.exists) {
+    const stagedUserData = stagedUser.data()
+
+    const rolesExist = stagedUserData.roles && Object.keys(stagedUserData.roles).length !== 0
+    const specialPermissionsExist = stagedUserData.specialPermissions && Object.keys(stagedUserData.specialPermissions).length !== 0
+    const userIdExistsAndNotBlank = stagedUserData.userId && stagedUserData.userId !== ''
+
+    if (!rolesExist && !specialPermissionsExist && !userIdExistsAndNotBlank) {
+      await db.collection('staged-users').doc(data.docId).delete()
+      return { success: true, message: '' }
+    }
+    else {
+      let message = ''
+      if (rolesExist && specialPermissionsExist) {
+        message = 'Cannot delete because the non-registered user still has roles and special permissions assigned.'
       }
-      else {
-        let message = ''
-        if (rolesExist && specialPermissionsExist) {
-          message = 'Cannot delete because the non-registered user still has roles and special permissions assigned.'
-        }
-        else if (rolesExist) {
-          message = 'Cannot delete because the non-registered user still has roles assigned.'
-        }
-        else if (specialPermissionsExist) {
-          message = 'Cannot delete because the non-registered user still has special permissions assigned.'
-        }
-        else if (userIdExistsAndNotBlank) {
-          message = 'Cannot delete because the user is registered.'
-        }
-        return { success: false, message }
+      else if (rolesExist) {
+        message = 'Cannot delete because the non-registered user still has roles assigned.'
+      }
+      else if (specialPermissionsExist) {
+        message = 'Cannot delete because the non-registered user still has special permissions assigned.'
+      }
+      else if (userIdExistsAndNotBlank) {
+        message = 'Cannot delete because the user is registered.'
       }
+      return { success: false, message }
     }
   }
   return { success: false, message: 'Non-registered user not found.' }
 })
 
 exports.currentUserRegister = onCall(async (request) => {
+  assertCallableUser(request)
   const data = request.data
-  const auth = request.auth
-  if (data.uid === auth.uid) {
-    const stagedUser = await db.collection('staged-users').doc(data.registrationCode).get()
-    if (!stagedUser.exists) {
-      return { success: false, message: 'Registration code not found.' }
+  const stagedUser = await db.collection('staged-users').doc(data.registrationCode).get()
+  if (!stagedUser.exists) {
+    return { success: false, message: 'Registration code not found.' }
+  }
+  else {
+    const stagedUserData = await stagedUser.data()
+    let process = false
+    if (stagedUserData.isTemplate) {
+      process = true
     }
-    else {
-      const stagedUserData = await stagedUser.data()
-      let process = false
-      if (stagedUserData.isTemplate) {
-        process = true
-      }
-      if (!stagedUserData.isTemplate && stagedUserData.userId === '') {
-        process = true
-      }
-      if (!process) {
-        return { success: false, message: 'Registration code not valid.' }
-      }
-      const newRoles = stagedUserData.roles || {}
-      const currentUser = await db.collection('users').doc(data.uid).get()
-      const currentUserData = await currentUser.data()
-      const currentRoles = currentUserData.roles || {}
-      const currentUserCollectionPaths = currentUserData.collectionPaths || []
-      let newRole = {}
-      if (stagedUserData.subCreate && Object.keys(stagedUserData.subCreate).length !== 0 && stagedUserData.isTemplate) {
-        if (!data.dynamicDocumentFieldValue) {
-          return { success: false, message: 'Dynamic document field value is required.' }
-        }
-        const rootPath = stagedUserData.subCreate.rootPath
-        const newDoc = stagedUserData.subCreate.documentStructure
-        newDoc[stagedUserData.subCreate.dynamicDocumentField] = data.dynamicDocumentFieldValue
-        const addedDoc = await db.collection(rootPath).add(newDoc)
-        await db.collection(rootPath).doc(addedDoc.id).update({ docId: addedDoc.id })
-        newRole = { [`${rootPath}-${addedDoc.id}`]: { collectionPath: `${rootPath}-${addedDoc.id}`, role: stagedUserData.subCreate.role } }
+    if (!stagedUserData.isTemplate && stagedUserData.userId === '') {
+      process = true
+    }
+    if (!process) {
+      return { success: false, message: 'Registration code not valid.' }
+    }
+    const newRoles = stagedUserData.roles || {}
+    const currentUser = await db.collection('users').doc(data.uid).get()
+    const currentUserData = await currentUser.data()
+    const currentRoles = currentUserData.roles || {}
+    const currentUserCollectionPaths = currentUserData.collectionPaths || []
+    let newRole = {}
+    if (stagedUserData.subCreate && Object.keys(stagedUserData.subCreate).length !== 0 && stagedUserData.isTemplate) {
+      if (!data.dynamicDocumentFieldValue) {
+        return { success: false, message: 'Dynamic document field value is required.' }
       }
-      const combinedRoles = { ...currentRoles, ...newRoles, ...newRole }
-      Object.values(combinedRoles).forEach((role) => {
-        if (!currentUserCollectionPaths.includes(role.collectionPath)) {
-          currentUserCollectionPaths.push(role.collectionPath)
-        }
-      })
-      await db.collection('staged-users').doc(currentUserData.stagedDocId).update({ roles: combinedRoles, collectionPaths: currentUserCollectionPaths })
-      if (!stagedUserData.isTemplate) {
-        await db.collection('staged-users').doc(data.registrationCode).delete()
+      const rootPath = stagedUserData.subCreate.rootPath
+      const newDoc = stagedUserData.subCreate.documentStructure
+      newDoc[stagedUserData.subCreate.dynamicDocumentField] = data.dynamicDocumentFieldValue
+      const addedDoc = await db.collection(rootPath).add(newDoc)
+      await db.collection(rootPath).doc(addedDoc.id).update({ docId: addedDoc.id })
+      newRole = { [`${rootPath}-${addedDoc.id}`]: { collectionPath: `${rootPath}-${addedDoc.id}`, role: stagedUserData.subCreate.role } }
+    }
+    const combinedRoles = { ...currentRoles, ...newRoles, ...newRole }
+    Object.values(combinedRoles).forEach((role) => {
+      if (!currentUserCollectionPaths.includes(role.collectionPath)) {
+        currentUserCollectionPaths.push(role.collectionPath)
       }
-      return { success: true, message: '' }
+    })
+    await db.collection('staged-users').doc(currentUserData.stagedDocId).update({ roles: combinedRoles, collectionPaths: currentUserCollectionPaths })
+    if (!stagedUserData.isTemplate) {
+      await db.collection('staged-users').doc(data.registrationCode).delete()
     }
+    return { success: true, message: '' }
   }
 })
 
@@ -522,52 +523,51 @@ exports.checkOrgIdExists = onCall(async (request) => {
 })
 
 exports.deleteSelf = onCall(async (request) => {
-  if (request.data.uid === request.auth.uid) {
-    try {
-      const userDoc = await db.collection('staged-users').doc(request.auth.uid).get()
-      const userData = userDoc.data()
-      const userCollectionPaths = userData.collectionPaths || []
-
-      for (const path of userCollectionPaths) {
-        const usersWithSamePath = await db.collection('staged-users').where('collectionPaths', 'array-contains', path).get()
-
-        // If no other users have the same collection path, delete the path and all documents and collections under it
-        if (usersWithSamePath.size <= 1) {
-          const adjustedPath = path.replace(/-/g, '/')
-          const docRef = db.doc(adjustedPath)
-          const doc = await docRef.get()
-
-          if (doc.exists) {
-            // If the path is a document, delete it directly
-            await docRef.delete()
-          }
-          else {
-            // If the path is a collection, delete all documents under it
-            const docsToDelete = await db.collection(adjustedPath).get()
-            const batch = db.batch()
-            docsToDelete.docs.forEach((doc) => {
-              batch.delete(doc.ref)
-            })
-            await batch.commit()
-          }
+  assertCallableUser(request)
+  try {
+    const userDoc = await db.collection('staged-users').doc(request.auth.uid).get()
+    const userData = userDoc.data()
+    const userCollectionPaths = userData.collectionPaths || []
+
+    for (const path of userCollectionPaths) {
+      const usersWithSamePath = await db.collection('staged-users').where('collectionPaths', 'array-contains', path).get()
+
+      // If no other users have the same collection path, delete the path and all documents and collections under it
+      if (usersWithSamePath.size <= 1) {
+        const adjustedPath = path.replace(/-/g, '/')
+        const docRef = db.doc(adjustedPath)
+        const doc = await docRef.get()
+
+        if (doc.exists) {
+          // If the path is a document, delete it directly
+          await docRef.delete()
+        }
+        else {
+          // If the path is a collection, delete all documents under it
+          const docsToDelete = await db.collection(adjustedPath).get()
+          const batch = db.batch()
+          docsToDelete.docs.forEach((doc) => {
+            batch.delete(doc.ref)
+          })
+          await batch.commit()
         }
       }
+    }
 
-      // Delete from 'staged-users' collection
-      await db.collection('staged-users').doc(request.data.uid).delete()
+    // Delete from 'staged-users' collection
+    await db.collection('staged-users').doc(request.data.uid).delete()
 
-      // Delete from 'users' collection
-      await db.collection('users').doc(request.data.uid).delete()
+    // Delete from 'users' collection
+    await db.collection('users').doc(request.data.uid).delete()
 
-      // Delete the user from Firebase
-      await admin.auth().deleteUser(request.data.uid)
+    // Delete the user from Firebase
+    await admin.auth().deleteUser(request.data.uid)
 
-      return { success: true }
-    }
-    catch (error) {
-      console.error('Error deleting user:', error)
-      return { success: false, error }
-    }
+    return { success: true }
+  }
+  catch (error) {
+    console.error('Error deleting user:', error)
+    return { success: false, error }
   }
 })
 

package/src/functions.js

@@ -1,4 +1,6 @@
 // START @edge/firebase functions
+const { kvMirrorRetryWorker } = require('./kv/kvRetryWorker')
+exports.kvMirrorRetryWorker = kvMirrorRetryWorker
 exports.edgeFirebase = require('./edgeFirebase')
 exports.cms = require('./cms')
-// END @edge/firebase functions
+// END @edge/firebase functions

package/src/index.js

@@ -1,6 +1,8 @@
 require('dotenv').config({ path: process.env.NODE_ENV === 'production' ? '.env.prod' : '.env.dev' })
 
 // START @edge/firebase functions
+const { kvMirrorRetryWorker } = require('./kv/kvRetryWorker')
+exports.kvMirrorRetryWorker = kvMirrorRetryWorker
 exports.edgeFirebase = require('./edgeFirebase')
 exports.cms = require('./cms')
 // END @edge/firebase functions

package/src/kv/kvClient.js

@@ -11,6 +11,56 @@ if (!accountId || !namespaceId || !apiKey) {
 }
 
 const base = `https://api.cloudflare.com/client/v4/accounts/${accountId}/storage/kv/namespaces/${namespaceId}`
+const MAX_RETRIES = Number(process.env.KV_HTTP_MAX_RETRIES || 5)
+const BASE_DELAY_MS = Number(process.env.KV_HTTP_BASE_DELAY_MS || 250)
+const MAX_DELAY_MS = Number(process.env.KV_HTTP_MAX_DELAY_MS || 5000)
+
+const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
+
+function parseRetryAfterMs(retryAfterHeader) {
+  if (!retryAfterHeader)
+    return 0
+  const raw = Array.isArray(retryAfterHeader) ? retryAfterHeader[0] : retryAfterHeader
+  const asNumber = Number(raw)
+  if (Number.isFinite(asNumber) && asNumber >= 0)
+    return asNumber * 1000
+  const asDate = Date.parse(String(raw))
+  if (!Number.isNaN(asDate))
+    return Math.max(0, asDate - Date.now())
+  return 0
+}
+
+function shouldRetryError(err) {
+  const status = Number(err?.response?.status || 0)
+  if (status === 429 || status === 408)
+    return true
+  if (status >= 500 && status <= 599)
+    return true
+  if (!status && (err?.code || err?.message))
+    return true
+  return false
+}
+
+async function requestWithRetry(run, label = 'kv-request') {
+  let attempt = 0
+  for (;;) {
+    try {
+      return await run()
+    }
+    catch (err) {
+      if (!shouldRetryError(err) || attempt >= MAX_RETRIES)
+        throw err
+      const retryAfterMs = parseRetryAfterMs(err?.response?.headers?.['retry-after'])
+      const expo = Math.min(MAX_DELAY_MS, BASE_DELAY_MS * (2 ** attempt))
+      const jitter = Math.floor(Math.random() * 200)
+      const delayMs = Math.max(retryAfterMs, expo + jitter)
+      const status = err?.response?.status || 'network'
+      console.warn(`[kvClient] retrying ${label} (attempt ${attempt + 1}/${MAX_RETRIES}, status ${status}) in ${delayMs}ms`)
+      await sleep(delayMs)
+      attempt += 1
+    }
+  }
+}
 
 function parseJsonIfNeeded(body) {
   if (body === null || body === undefined) {
@@ -61,7 +111,7 @@ async function put(key, value, opts = undefined) {
     form.append('metadata', JSON.stringify(opts.metadata))
     const formHeaders = form.getHeaders()
     Object.assign(headers, formHeaders)
-    const res = await axios.put(url, form, { headers })
+    const res = await requestWithRetry(() => axios.put(url, form, { headers }), `put:${key}`)
     if (res.status !== 200) {
       throw new Error(`KV put failed: ${res.status} ${res.statusText}`)
     }
@@ -77,7 +127,7 @@ async function put(key, value, opts = undefined) {
     headers['Content-Type'] = 'text/plain'
   }
 
-  const res = await axios.put(url, data, { headers })
+  const res = await requestWithRetry(() => axios.put(url, data, { headers }), `put:${key}`)
   if (res.status !== 200) {
     throw new Error(`KV put failed: ${res.status} ${res.statusText}`)
   }
@@ -99,11 +149,11 @@ async function putIndexMeta(key, metadata, opts = undefined) {
 async function get(key, type = 'text') {
   const url = `${base}/values/${encodeURIComponent(key)}`
   try {
-    const res = await axios.get(url, {
+    const res = await requestWithRetry(() => axios.get(url, {
       headers: { Authorization: `Bearer ${apiKey}` },
       responseType: 'text',
       transformResponse: [x => x],
-    })
+    }), `get:${key}`)
     if (type === 'json') {
       return parseJsonIfNeeded(res.data)
     }
@@ -119,9 +169,17 @@ async function get(key, type = 'text') {
 
 async function del(key) {
   const url = `${base}/values/${encodeURIComponent(key)}`
-  await Promise.allSettled([
-    axios.delete(url, { headers: { Authorization: `Bearer ${apiKey}` } }),
-  ])
+  try {
+    await requestWithRetry(
+      () => axios.delete(url, { headers: { Authorization: `Bearer ${apiKey}` } }),
+      `del:${key}`,
+    )
+  }
+  catch (err) {
+    if (err?.response?.status === 404)
+      return
+    throw err
+  }
 }
 
 /**
@@ -139,7 +197,10 @@ async function listKeys({ prefix = '', limit = 1000, cursor = '' } = {}) {
   if (cursor) {
     u.searchParams.set('cursor', cursor)
   }
-  const res = await axios.get(u.toString(), { headers: { Authorization: `Bearer ${apiKey}` } })
+  const res = await requestWithRetry(
+    () => axios.get(u.toString(), { headers: { Authorization: `Bearer ${apiKey}` } }),
+    `list:${prefix || 'all'}`,
+  )
   return res.data
 }
 

package/src/kv/kvMirror.js

@@ -5,13 +5,115 @@
 // - Index-key metadata always includes { canonical: <canonicalKey> }.
 // - Keeps a small manifest per canonical key to clean up all index keys on delete.
 
-const { onDocumentWritten } = require('../config.js')
+const { onDocumentWritten, db, Firestore, logger } = require('../config.js')
 const kv = require('./kvClient')
 
 function json(x) {
   return JSON.stringify(x)
 }
 
+const KV_RETRY_TOPIC = process.env.KV_RETRY_TOPIC || 'kv-mirror-retry'
+const INDEX_WRITE_CONCURRENCY = Number(process.env.KV_MIRROR_INDEX_CONCURRENCY || 20)
+
+function toSortedUniqueStrings(values = []) {
+  return [...new Set((Array.isArray(values) ? values : [])
+    .filter(Boolean)
+    .map(String))]
+    .sort()
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableStringify).join(',')}]`
+  }
+  if (value && typeof value === 'object') {
+    const keys = Object.keys(value).sort()
+    return `{${keys.map(k => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(',')}}`
+  }
+  return JSON.stringify(value)
+}
+
+function areSameStrings(a = [], b = []) {
+  if (a.length !== b.length)
+    return false
+  for (let i = 0; i < a.length; i += 1) {
+    if (a[i] !== b[i])
+      return false
+  }
+  return true
+}
+
+function normalizeConcurrency(value) {
+  const n = Number(value)
+  if (!Number.isFinite(n) || n < 1)
+    return 1
+  return Math.floor(n)
+}
+
+async function runWithConcurrency(items, limit, worker) {
+  const values = Array.isArray(items) ? items : []
+  if (!values.length)
+    return
+  const max = normalizeConcurrency(limit)
+  let cursor = 0
+  const workers = Array.from({ length: Math.min(max, values.length) }, async () => {
+    for (;;) {
+      const idx = cursor
+      cursor += 1
+      if (idx >= values.length)
+        return
+      await worker(values[idx], idx)
+    }
+  })
+  await Promise.all(workers)
+}
+
+async function enqueueKvRetry(payload, minuteDelay = 1) {
+  const safePayload = payload && typeof payload === 'object' ? payload : {}
+  await db.collection('topic-queue').add({
+    topic: KV_RETRY_TOPIC,
+    payload: {
+      ...safePayload,
+      attempt: Number(safePayload.attempt || 0),
+    },
+    minuteDelay: Number(minuteDelay || 0),
+    retry: 0,
+    timestamp: Firestore.FieldValue.serverTimestamp(),
+  })
+}
+
+async function safeKvOperation({
+  run,
+  payload,
+  label,
+}) {
+  try {
+    await run()
+    return true
+  }
+  catch (err) {
+    const message = String(err?.message || err || 'KV operation failed')
+    logger.warn('KV operation failed; queued for retry', {
+      label,
+      error: message.slice(0, 500),
+      key: payload?.key,
+      op: payload?.op,
+    })
+    try {
+      await enqueueKvRetry(payload)
+    }
+    catch (queueErr) {
+      logger.error('Failed to enqueue KV retry', {
+        label,
+        key: payload?.key,
+        op: payload?.op,
+        error: String(queueErr?.message || queueErr || 'enqueue failed').slice(0, 500),
+      })
+    }
+    return false
+  }
+}
+
 function slugIndexValue(value, maxLength = 80) {
   return String(value ?? '')
     .trim()
@@ -53,6 +155,10 @@ function createKvMirrorHandler({
     const data = after?.exists ? after.data() : null
 
     const canonicalKey = makeCanonicalKey(params, data)
+    if (!canonicalKey) {
+      logger.warn('KV mirror skipped due to missing canonical key', { document })
+      return
+    }
     const indexingEnabled = typeof makeIndexKeys === 'function'
     const manifestKey = indexingEnabled ? `idx:manifest:${canonicalKey}` : null
 
@@ -65,16 +171,25 @@ function createKvMirrorHandler({
         catch (_) {
           prev = null
         }
-        const keys = Array.isArray(prev?.indexKeys) ? prev.indexKeys : []
-        const deletions = [
-          ...keys.map(k => kv.del(k)),
-          kv.del(canonicalKey),
-          kv.del(manifestKey),
-        ]
-        await Promise.allSettled(deletions)
+        const keys = toSortedUniqueStrings([
+          ...(Array.isArray(prev?.indexKeys) ? prev.indexKeys : []),
+          canonicalKey,
+          manifestKey,
+        ])
+        await runWithConcurrency(keys, INDEX_WRITE_CONCURRENCY, async (key) => {
+          await safeKvOperation({
+            run: () => kv.del(key),
+            payload: { op: 'del', key, source: 'kvMirror' },
+            label: `del:${key}`,
+          })
+        })
       }
       else {
-        await kv.del(canonicalKey)
+        await safeKvOperation({
+          run: () => kv.del(canonicalKey),
+          payload: { op: 'del', key: canonicalKey, source: 'kvMirror' },
+          label: `del:${canonicalKey}`,
+        })
       }
       return
     }
@@ -85,15 +200,25 @@ function createKvMirrorHandler({
       ? { ...customMetaCandidate, canonical: canonicalKey }
       : baseMeta
 
-    await kv.put(canonicalKey, serialize(data), { metadata: metaValue })
+    const serializedData = serialize(data)
+    await safeKvOperation({
+      run: () => kv.put(canonicalKey, serializedData, { metadata: metaValue }),
+      payload: {
+        op: 'put',
+        key: canonicalKey,
+        value: serializedData,
+        opts: { metadata: metaValue },
+        source: 'kvMirror',
+      },
+      label: `put:${canonicalKey}`,
+    })
 
     if (!indexingEnabled) {
       return
     }
 
-    const nextIndexKeys = (await Promise.resolve(makeIndexKeys(params, data)) || [])
-      .filter(Boolean)
-      .map(String)
+    const resolvedIndexKeys = await Promise.resolve(makeIndexKeys(params, data))
+    const nextIndexKeys = toSortedUniqueStrings(resolvedIndexKeys || [])
 
     let prev = null
     try {
@@ -103,16 +228,49 @@ function createKvMirrorHandler({
       prev = null
     }
 
-    const oldIndexKeys = Array.isArray(prev?.indexKeys) ? prev.indexKeys : []
-    const { toRemove } = setDiff(oldIndexKeys, nextIndexKeys)
+    const oldIndexKeys = toSortedUniqueStrings(Array.isArray(prev?.indexKeys) ? prev.indexKeys : [])
+    const previousMetaHash = typeof prev?.metadataHash === 'string' ? prev.metadataHash : ''
+    const currentMetaHash = stableStringify(metaValue)
+    const { toRemove, toAdd } = setDiff(oldIndexKeys, nextIndexKeys)
+    const shouldRewriteAllIndexKeys = previousMetaHash !== currentMetaHash
+    const keysToUpsert = shouldRewriteAllIndexKeys ? nextIndexKeys : toAdd
 
-    const upserts = nextIndexKeys.map(k => kv.putIndexMeta(k, metaValue))
-    await Promise.allSettled(upserts)
+    await runWithConcurrency(keysToUpsert, INDEX_WRITE_CONCURRENCY, async (key) => {
+      await safeKvOperation({
+        run: () => kv.putIndexMeta(key, metaValue),
+        payload: {
+          op: 'putIndexMeta',
+          key,
+          metadata: metaValue,
+          source: 'kvMirror',
+        },
+        label: `putIndexMeta:${key}`,
+      })
+    })
 
-    const removals = toRemove.map(k => kv.del(k))
-    await Promise.allSettled(removals)
+    await runWithConcurrency(toRemove, INDEX_WRITE_CONCURRENCY, async (key) => {
+      await safeKvOperation({
+        run: () => kv.del(key),
+        payload: { op: 'del', key, source: 'kvMirror' },
+        label: `del:${key}`,
+      })
+    })
 
-    await kv.put(manifestKey, { indexKeys: nextIndexKeys })
+    const manifestUnchanged = areSameStrings(oldIndexKeys, nextIndexKeys)
+      && previousMetaHash === currentMetaHash
+    if (!manifestUnchanged) {
+      const manifestValue = { indexKeys: nextIndexKeys, metadataHash: currentMetaHash }
+      await safeKvOperation({
+        run: () => kv.put(manifestKey, manifestValue),
+        payload: {
+          op: 'put',
+          key: manifestKey,
+          value: manifestValue,
+          source: 'kvMirror',
+        },
+        label: `put:${manifestKey}`,
+      })
+    }
   })
 }
 
@@ -121,6 +279,7 @@ function createKvMirrorHandlerFromFields({
   uniqueKey,
   indexKeys = [],
   metadataKeys = [],
+  metaKeyTruncate = {},
   serialize = json,
 }) {
   if (!uniqueKey || typeof uniqueKey !== 'string') {
@@ -193,8 +352,18 @@ function createKvMirrorHandlerFromFields({
   const makeMetadata = (data) => {
     const meta = {}
     const keys = Array.isArray(metadataKeys) ? metadataKeys : []
+    const truncateMap = metaKeyTruncate && typeof metaKeyTruncate === 'object'
+      ? metaKeyTruncate
+      : {}
     for (const key of keys) {
-      meta[key] = data?.[key] ?? ''
+      const raw = data?.[key] ?? ''
+      const truncateLength = Number(truncateMap?.[key])
+      if (Number.isFinite(truncateLength) && truncateLength >= 0 && typeof raw === 'string') {
+        meta[key] = raw.slice(0, Math.floor(truncateLength))
+      }
+      else {
+        meta[key] = raw
+      }
     }
     return meta
   }

package/src/kv/kvRetryWorker.js

@@ -0,0 +1,138 @@
+const { onMessagePublished, db, Firestore, logger } = require('../config.js')
+const kv = require('./kvClient')
+
+const KV_RETRY_TOPIC = process.env.KV_RETRY_TOPIC || 'kv-mirror-retry'
+const KV_RETRY_MAX_ATTEMPTS = Number(process.env.KV_RETRY_MAX_ATTEMPTS || 8)
+const KV_RETRY_BASE_MIN_DELAY = Number(process.env.KV_RETRY_BASE_MIN_DELAY || 1)
+const KV_RETRY_MAX_MIN_DELAY = Number(process.env.KV_RETRY_MAX_MIN_DELAY || 60)
+
+function toPositiveInt(value, fallback = 1) {
+  const n = Number(value)
+  if (!Number.isFinite(n) || n < 1)
+    return fallback
+  return Math.floor(n)
+}
+
+function parseTopicPayload(event) {
+  const message = event?.data?.message || {}
+  if (message.json && typeof message.json === 'object')
+    return message.json
+  if (message.data) {
+    try {
+      const text = Buffer.from(message.data, 'base64').toString('utf8')
+      const parsed = JSON.parse(text)
+      return parsed && typeof parsed === 'object' ? parsed : {}
+    }
+    catch (_) {
+      return {}
+    }
+  }
+  return {}
+}
+
+function computeRetryDelayMinutes(attempt) {
+  const safeAttempt = toPositiveInt(attempt, 1)
+  const base = toPositiveInt(KV_RETRY_BASE_MIN_DELAY, 1)
+  const max = toPositiveInt(KV_RETRY_MAX_MIN_DELAY, 60)
+  return Math.min(max, base * (2 ** Math.max(0, safeAttempt - 1)))
+}
+
+async function enqueueKvRetry(payload, minuteDelay = 0) {
+  await db.collection('topic-queue').add({
+    topic: KV_RETRY_TOPIC,
+    payload,
+    minuteDelay: Number(minuteDelay || 0),
+    retry: 0,
+    timestamp: Firestore.FieldValue.serverTimestamp(),
+  })
+}
+
+async function runKvOperation(payload) {
+  const op = String(payload?.op || '')
+  const key = String(payload?.key || '')
+  if (!op || !key)
+    throw new Error('Invalid KV retry payload: missing op/key')
+
+  if (op === 'put')
+    return kv.put(key, payload.value, payload.opts)
+  if (op === 'putIndexMeta')
+    return kv.putIndexMeta(key, payload.metadata, payload.opts)
+  if (op === 'del')
+    return kv.del(key)
+
+  throw new Error(`Unsupported KV retry operation: ${op}`)
+}
+
+const kvMirrorRetryWorker = onMessagePublished(
+  {
+    topic: KV_RETRY_TOPIC,
+    retry: false,
+    timeoutSeconds: 180,
+    memory: '512MiB',
+    concurrency: 20,
+  },
+  async (event) => {
+    const payload = parseTopicPayload(event)
+    const op = String(payload?.op || '')
+    const key = String(payload?.key || '')
+    const attempt = Number(payload?.attempt || 0)
+
+    if (!op || !key) {
+      logger.warn('KV retry worker received invalid payload', { payload })
+      return
+    }
+
+    try {
+      await runKvOperation(payload)
+    }
+    catch (err) {
+      const nextAttempt = attempt + 1
+      const maxAttempts = toPositiveInt(KV_RETRY_MAX_ATTEMPTS, 8)
+      const errorMessage = String(err?.message || err || 'KV retry failed')
+
+      if (nextAttempt > maxAttempts) {
+        logger.error('KV retry exhausted max attempts', { op, key, attempt: nextAttempt, error: errorMessage.slice(0, 500) })
+        try {
+          await db.collection('kv-retry-dead').add({
+            topic: KV_RETRY_TOPIC,
+            payload: {
+              ...payload,
+              attempt: nextAttempt,
+            },
+            error: errorMessage.slice(0, 1000),
+            timestamp: Firestore.FieldValue.serverTimestamp(),
+          })
+        }
+        catch (deadErr) {
+          logger.error('KV retry dead-letter write failed', {
+            op,
+            key,
+            attempt: nextAttempt,
+            error: String(deadErr?.message || deadErr || 'dead-letter write failed').slice(0, 500),
+          })
+        }
+        return
+      }
+
+      const minuteDelay = computeRetryDelayMinutes(nextAttempt)
+      try {
+        await enqueueKvRetry({
+          ...payload,
+          attempt: nextAttempt,
+        }, minuteDelay)
+        logger.warn('KV retry requeued', { op, key, attempt: nextAttempt, minuteDelay, error: errorMessage.slice(0, 500) })
+      }
+      catch (queueErr) {
+        logger.error('KV retry requeue write failed', {
+          op,
+          key,
+          attempt: nextAttempt,
+          minuteDelay,
+          error: String(queueErr?.message || queueErr || 'requeue write failed').slice(0, 500),
+        })
+      }
+    }
+  },
+)
+
+module.exports = { kvMirrorRetryWorker }