@cuboapp/crdt 1.0.21 → 1.0.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cuboapp/crdt",
-  "version": "1.0.21",
+  "version": "1.0.23",
   "description": "CRDT for CUBO",
   "main": "src/index.ts",
   "repository": {

package/src/client/index.ts

@@ -2,7 +2,7 @@ import { keyBy, pick, uuid } from '@cuboapp/utils'
 import { WsClientEvent } from '@cuboapp/ws'
 import { computed, reactive, shallowReactive } from 'vue'
 import { applyAwarenessUpdate, Awareness, encodeAwarenessUpdate, removeAwarenessStates } from 'y-protocols/awareness'
-import { applyUpdate, Doc } from 'yjs'
+import { applyUpdate, Doc, encodeStateAsUpdate, encodeStateVector } from 'yjs'
 
 import { CUBO_CRDT_EVENT } from '../constants'
 import { CuboCrdtServerDocumentIncomingAction } from '../server'
@@ -450,48 +450,92 @@ export class CuboCrdtClient<M> {
     dto: K extends Extract<keyof M, string> ? Partial<M[K]> : object,
     opts?: CuboCrdtClientDocOrigin
   ) {
-    const cardRow = this.store[`${entity}:${entity_id}`]?.state.rows?.[0]
-    const listRow = this.store[entity]?.state?.rows.find((r: any) => r.id === entity_id)
-    const cardDoc = this.store[`${entity}:${entity_id}`]?.docs.get(entity_id)
-    const listDoc = this.store[entity]?.docs.get(entity_id)
-
-    // обновляем документы
-    for (const doc of [cardDoc, listDoc]) {
-      if (doc) {
-        const map = doc.getMap()
-
-        const row = (cardRow || listRow) as any
-        const toUpdate = Object.fromEntries(Object.entries(dto).filter(([key, value]) => row[key] !== value))
-
-        if (Object.keys(toUpdate).length) {
-          const origin: CuboCrdtClientDocOrigin = {
-            store: opts?.store ?? true,
-            expose: opts?.expose ?? 'other',
-            keys: opts?.keys ?? Object.keys(toUpdate),
-            react: true // отправляем на бэк
+    // Если строка открыта через useRow, mutating API работает только с её
+    // каноническим документом. Списки могут содержать тот же id, но не должны
+    // становиться источником записи для карточки.
+    const rowStore = this.store[`${entity}:${entity_id}`]
+    const store = rowStore?.state.status === 'ready' && rowStore.docs.has(entity_id)
+      ? rowStore
+      : [...this.subscriptions.values()]
+          .filter((subscription) => subscription.entity === entity)
+          .map((subscription) => this.store[subscription.storeKey])
+          .find((candidate) => candidate?.docs.has(entity_id) && candidate.state.status === 'ready')
+    const document = store?.docs.get(entity_id)
+
+    if (!store || !document) {
+      return false
+    }
+
+    const map = document.getMap()
+    const toUpdate = Object.fromEntries(
+      Object.entries(dto).filter(([key, value]) => map.get(key) !== value)
+    )
+
+    if (!Object.keys(toUpdate).length) {
+      // Состояние уже совпадает (например, update успел прийти из другой
+      // вкладки). Это успешный no-op, а не ошибка изменения.
+      return true
+    }
+
+    const origin: CuboCrdtClientDocOrigin = {
+      store: opts?.store ?? true,
+      expose: opts?.expose ?? 'other',
+      keys: opts?.keys ?? Object.keys(toUpdate),
+      // update() сам отправляет ровно один пакет ниже. Общий listener остаётся
+      // для изменений, которые создаются напрямую сторонними Yjs-binding'ами.
+      react: false
+    }
+
+    const stateVector = encodeStateVector(document)
+
+    // Одна сущность может присутствовать в нескольких подписках с разными
+    // storeKey. Мутацию отправляем только из одного документа: остальные
+    // подписки получат подтверждённый update через обычную CRDT-рассылку.
+    document.transact(() => {
+      Object.entries(toUpdate).forEach(([key, value]) => {
+        map.set(key, value)
+      })
+    }, origin)
+
+    const update = encodeStateAsUpdate(document, stateVector)
+    const receipt = this.ws
+      .request(
+        {
+          method: CUBO_CRDT_EVENT.EVENT,
+          data: {
+            action: 'update',
+            entity,
+            entity_id,
+            data: Array.from(update),
+            origin: {
+              ...pick(origin, ['store', 'keys', 'expose']),
+              subscribe_id: [...this.subscriptions.entries()]
+                .find(([, subscription]) => this.store[subscription.storeKey] === store)?.[0]
+            }
           }
+        },
+        { wait: true, timeout: 10_000 }
+      )
+      .then(() => true)
+      .catch((error) => {
+        console.error('[CRDT] update request failed', error)
+        return false
+      })
 
-          doc.transact(() => {
-            Object.entries(toUpdate).forEach(([key, value]) => {
-              map.set(key, value)
-            })
-          }, origin)
-        }
-      }
-    }
+    // Этот документ является каноническим локальным состоянием строки. Обновляем
+    // его реактивную строку сразу, а другие подписки получат тот же Yjs-update
+    // через серверную рассылку.
+    this.applyRowJson(`${entity}:${entity_id}`, entity_id, document)
 
-    // обновляем реактивку
-    for (const row of [cardRow, listRow]) {
-      if (row) {
-        const toUpdate = Object.fromEntries(Object.entries(dto).filter(([key, value]) => row[key as keyof typeof row] !== value))
+    const row = store.state.rows.find((item: any) => Number(item.id) === Number(entity_id))
 
-        if (Object.keys(toUpdate).length) {
-          Object.entries(toUpdate).forEach(([key, value]) => {
-            row[key as keyof typeof row] = value
-          })
-        }
-      }
+    if (row) {
+      Object.entries(toUpdate).forEach(([key, value]) => {
+        row[key] = value
+      })
     }
+
+    return receipt
   }
 
   public upgrade(subscribe_id: string, filters?: Record<string, any>) {
@@ -645,10 +689,10 @@ export class CuboCrdtClient<M> {
           }
         }
 
-        this.ws.request({
+        void this.ws.request({
           method: CUBO_CRDT_EVENT.EVENT,
           data
-        })
+        }).catch((error) => console.error('[CRDT] update request failed', error))
       }
     })
 

package/src/server/document/index.ts

@@ -1,12 +1,23 @@
-import { cloneDeep, debounce, pick } from '@cuboapp/utils'
+import { cloneDeep, pick } from '@cuboapp/utils'
 import { applyUpdate, Doc, encodeStateAsUpdate } from 'yjs'
 import { Awareness, encodeAwarenessUpdate } from 'y-protocols/awareness'
 
-import { CuboCrdtServerDocumentOptions, CuboCrdtServerDocumentOrigin } from '../types'
+import {
+  CuboCrdtServerDocumentOptions,
+  CuboCrdtServerDocumentOrigin,
+  CuboCrdtServerDocumentPendingStore
+} from '../types'
+import { getCrdtStoreChangeKey } from '../utils'
+
+const STORE_DEBOUNCE_MS = 300
 
 export class CuboCrdtServerDocument {
   private ydoc: Doc
   private persistedState: object = {}
+  private observedState: object = {}
+  private storeQueue?: Promise<void>
+  private pendingStore?: CuboCrdtServerDocumentPendingStore
+  private storeTimeout?: ReturnType<typeof setTimeout>
   public awareness: Awareness
   public awarenessBySubscribe = new Map<string, Set<number>>()
 
@@ -23,6 +34,7 @@ export class CuboCrdtServerDocument {
     }
 
     this.persistedState = cloneDeep(opts.initialState ?? {})
+    this.observedState = cloneDeep(opts.initialState ?? {})
 
     // записываем исходное состояние
     this.write(opts.initialState ?? {})
@@ -37,7 +49,8 @@ export class CuboCrdtServerDocument {
       this.opts?.onUpdate?.(data, origin)
       // }
 
-      // если нужно сохранять стейт документа - вызываем store по дебаунсу
+      // Состояние отслеживается синхронно с Y.Doc. Для клиентских изменений
+      // debounceStore сам обновит observedState после вычисления leaf-diff.
       if (origin?.store) {
         const row = this.getJson()
         const body = pick(row, origin.keys ?? Object.keys(row))
@@ -47,6 +60,8 @@ export class CuboCrdtServerDocument {
             console.error('[CRDT] store document', this.name, error)
           })
         }
+      } else {
+        this.observedState = cloneDeep(this.getJson())
       }
     })
   }
@@ -141,13 +156,138 @@ export class CuboCrdtServerDocument {
     this.ydoc.destroy()
   }
 
-  public async store(body: object, origin: CuboCrdtServerDocumentOrigin) {
-    const previousRow = this.getPersistedState()
-    const row = this.getJson()
+  /**
+   * Немедленно передаёт trailing-пакет в очередь и ждёт все уже принятые
+   * сохранения документа. Используется перед вытеснением Y.Doc из серверного
+   * кэша, чтобы refresh последнего клиента не потерял его update.
+   */
+  public async flushStoreQueue() {
+    this.flushPendingStore()
+
+    while (this.storeQueue) {
+      await this.storeQueue
+      this.flushPendingStore()
+    }
+  }
+
+  /** Есть ли принятое клиентское изменение в debounce или очереди записи. */
+  public hasPendingStore() {
+    return !!this.pendingStore || !!this.storeQueue
+  }
+
+  public store(body: object, origin: CuboCrdtServerDocumentOrigin, row = this.getJson()) {
+    const queuedBody = cloneDeep(body)
+    const queuedRow = cloneDeep(row)
+    // debounce ограничивает частоту вызовов, но не сериализует async store.
+    // Без очереди следующий PATCH мог завершиться раньше предыдущего и затем
+    // быть затёрт старым полным снимком составного поля (например case.extra).
+    const previous = this.storeQueue?.catch(() => undefined) ?? Promise.resolve()
+    const current = previous
+      .then(async () => {
+        const previousRow = this.getPersistedState()
+
+        await this.opts?.onStore?.(queuedBody, origin, {
+          previousRow,
+          row: queuedRow
+        })
+        this.setPersistedState(queuedRow)
+      })
+
+    const queued = current.finally(() => {
+      // Если после этой записи не добавилась следующая, очередь опустела.
+      // Сама Promise-цепочка является источником истины — отдельный счётчик не нужен.
+      if (this.storeQueue === queued) {
+        this.storeQueue = undefined
+      }
+    })
+    this.storeQueue = queued
+
+    return queued
+  }
+
+  /**
+   * Схлопывает только соседние изменения одного origin и одного набора
+   * leaf-путей. Смена пользователя или поля немедленно фиксирует предыдущий
+   * пакет, сохраняя фактический порядок collaborative-обновлений.
+   */
+  public debounceStore(body: object, origin: CuboCrdtServerDocumentOrigin) {
+    const row = cloneDeep(this.getJson())
+    const bodyKeys = Object.keys(body)
+    const previousBody = pick(this.observedState, bodyKeys)
+    const changeKey = getCrdtStoreChangeKey(previousBody, body)
+    const originKey = `${origin.client_id || ''}:${origin.subscribe_id || ''}`
+
+    this.observedState = cloneDeep(row)
+
+    if (!changeKey) {
+      return Promise.resolve()
+    }
+
+    return new Promise<void>((resolve, reject) => {
+      const sameBatch = this.pendingStore?.originKey === originKey &&
+        this.pendingStore.changeKey === changeKey
+
+      if (this.pendingStore && !sameBatch) {
+        this.flushPendingStore()
+      }
+
+      if (!this.pendingStore) {
+        this.pendingStore = {
+          body: cloneDeep(body),
+          changeKey,
+          origin: cloneDeep(origin),
+          originKey,
+          row,
+          waiters: []
+        }
+      } else {
+        const keys = new Set([
+          ...(this.pendingStore.origin.keys || []),
+          ...(origin.keys || [])
+        ])
+
+        this.pendingStore.body = {
+          ...this.pendingStore.body,
+          ...cloneDeep(body)
+        }
+        this.pendingStore.origin = {
+          ...cloneDeep(origin),
+          keys: [...keys]
+        }
+        this.pendingStore.row = row
+      }
+
+      this.pendingStore.waiters.push({ resolve, reject })
+      this.schedulePendingStore()
+    })
+  }
+
+  /** Перезапускает trailing debounce для текущего однородного пакета. */
+  private schedulePendingStore() {
+    if (this.storeTimeout) {
+      clearTimeout(this.storeTimeout)
+    }
 
-    await this.opts?.onStore?.(body, origin, { previousRow, row })
-    this.setPersistedState(row)
+    this.storeTimeout = setTimeout(() => this.flushPendingStore(), STORE_DEBOUNCE_MS)
   }
 
-  public debounceStore = debounce(this.store.bind(this), 300)
+  /** Передаёт накопленный пакет в общую последовательную очередь записи. */
+  private flushPendingStore() {
+    if (!this.pendingStore) {
+      return
+    }
+
+    if (this.storeTimeout) {
+      clearTimeout(this.storeTimeout)
+      this.storeTimeout = undefined
+    }
+
+    const pending = this.pendingStore
+    this.pendingStore = undefined
+
+    this.store(pending.body, pending.origin, pending.row).then(
+      () => pending.waiters.forEach(({ resolve }) => resolve()),
+      (error) => pending.waiters.forEach(({ reject }) => reject(error))
+    )
+  }
 }

package/src/server/index.ts

@@ -40,6 +40,7 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
   private subscribeGenerations = new Map<string, number>()
 
   private documents = new Map<string, CuboCrdtServerDocument>()
+  private documentEvictions = new Map<string, object>()
   private subscribesByDocument = new Map<string, Set<string>>()
   // обратный индекс: подписка -> имена документов, к которым она привязана.
   // Нужен, чтобы отписка/очистка не сканировала ВСЕ документы сервера (O(subs x docs)).
@@ -111,34 +112,53 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
       this.cleanSubscribe(subscribe_id)
     })
 
-    this.ws.registerHandler(CUBO_CRDT_EVENT.EVENT, async ({ message }) => {
+    this.ws.registerHandler(CUBO_CRDT_EVENT.EVENT, async ({ client, message }) => {
       let data = message.data as any
       if (!Array.isArray(data)) {
         data = [data]
       }
 
       if (this.debug) {
-        console.log('[CRDT] incoming event', data)
+        console.log('[CRDT] incoming event', data.map((row: any) => ({
+          action: row.action,
+          entity: row.entity,
+          entity_id: row.entity_id,
+          keys: row.origin?.keys,
+          subscribe_id: row.origin?.subscribe_id
+        })))
       }
 
       for (const row of data) {
         const update = new Uint8Array(row.data)
+        const origin: CuboCrdtServerDocumentOrigin = {
+          ...(row.origin || {}),
+          client_id: client.id,
+          store_context: {
+            client_id: client.id,
+            auth: cloneDeep(client.auth)
+          }
+        }
+        const action = { ...row, origin }
 
         switch (row.action) {
           case 'create':
-            this.onDocumentExternalCreate(update, row)
+            this.onDocumentExternalCreate(update, action)
             break
           case 'update':
-            this.onDocumentExternalUpdate(update, row)
+            this.onDocumentExternalUpdate(update, action)
             break
           case 'delete':
-            this.onDocumentExternalDelete(update, row)
+            this.onDocumentExternalDelete(update, action)
             break
           case 'awareness':
-            this.onAwarenessExternalUpdate(update, row)
+            this.onAwarenessExternalUpdate(update, action)
             break
         }
       }
+
+      // Ответ означает только «update применён к живому серверному Y.Doc».
+      // Debounce и последовательная запись в БД продолжаются независимо.
+      return { accepted: true }
     })
 
     this.ws.registerHttpHandler('GET', '/stats', () => {
@@ -174,6 +194,7 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
     this.subscribeRefreshStates.forEach((state) => clearTimeout(state.timer))
     this.subscribeRefreshStates.clear()
     this.subscribeGenerations.clear()
+    this.documentEvictions.clear()
 
     this.subscribes.forEach((sub) => this.ws.deleteHandler(sub.id))
   }
@@ -286,6 +307,10 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
 
   // привязываем подписку к документу (в обоих индексах)
   private linkSubscribeToDocument(subscribe_id: string, docName: string) {
+    // Новая подписка снова использует живой Y.Doc. Асинхронный flush может
+    // продолжаться, но больше не имеет права уничтожить этот документ.
+    this.documentEvictions.delete(docName)
+
     let byDoc = this.subscribesByDocument.get(docName)
     if (!byDoc) {
       byDoc = new Set()
@@ -309,17 +334,56 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
 
   // если у документа нет подписок - сносим его
   private checkDocumentNeedRemove(name: string) {
-    if (!this.subscribesByDocument.get(name)?.size) {
-      if (this.debug) {
-        console.log('[CRDT] delete document', name)
-      }
+    if (this.subscribesByDocument.get(name)?.size || this.documentEvictions.has(name)) {
+      return
+    }
 
-      this.documents.get(name)?.destroy()
-      this.documents.delete(name)
-      // не оставляем пустой Set в индексе (иначе — медленная утечка записей мапы);
-      // getOrCreateDocument пересоздаст его при повторном появлении документа
+    const document = this.documents.get(name)
+    if (!document) {
       this.subscribesByDocument.delete(name)
+      return
     }
+
+    // Последний клиент мог закрыться сразу после update (обычный refresh).
+    // Сначала сохраняем всю принятую очередь, а до её завершения оставляем Y.Doc
+    // доступным повторной подписке. Никакого фиксированного ожидания здесь нет.
+    const eviction = {}
+    this.documentEvictions.set(name, eviction)
+
+    if (this.debug) {
+      console.log('[CRDT] flush document before eviction', name)
+    }
+
+    void document.flushStoreQueue()
+      .then(() => {
+        if (
+          this.documentEvictions.get(name) !== eviction ||
+          this.subscribesByDocument.get(name)?.size ||
+          this.documents.get(name) !== document
+        ) {
+          return
+        }
+
+        this.documentEvictions.delete(name)
+
+        if (this.debug) {
+          console.log('[CRDT] delete document', name)
+        }
+
+        document.destroy()
+        this.documents.delete(name)
+        this.subscribesByDocument.delete(name)
+      })
+      .catch((error) => {
+        // Не уничтожаем единственную живую копию документа, если запись в БД
+        // не завершилась. Снимаем eviction, чтобы следующая отписка или явная
+        // проверка могла повторно инициировать flush.
+        if (this.documentEvictions.get(name) === eviction) {
+          this.documentEvictions.delete(name)
+        }
+
+        console.error('[CRDT] flush document before eviction', name, error)
+      })
   }
 
   // очистка подписки (при отписке клиента - через emit-метод или options-хук).
@@ -609,21 +673,6 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
         document.enableAwareness()
       }
 
-      // Освежаем существующий документ строкой из БД.
-      //
-      // Раньше документ возвращался как есть, а подписка отправляла клиенту его
-      // stateAsUpdate — то есть КЭШ документа, а не только что прочитанную строку.
-      // Документ, проспавший мутацию, оставался устаревшим навсегда: даже перезагрузка
-      // страницы отдавала старое значение, потому что reconcile брал его же.
-      //
-      // Стало заметно после того, как документы без подписчиков начали удаляться:
-      // документ может быть создан, остаться без подписок, пропустить мутации и
-      // «воскреснуть» на новой подписке уже неактуальным.
-      //
-      // store: false — это не правка от клиента, а синхронизация с БД, писать обратно нечего.
-      document.write(row, { expose: 'all', store: false })
-      document.setPersistedState(row)
-
       return document
     }
 
@@ -639,7 +688,13 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
       },
       onStore: (item: object, origin: CuboCrdtServerDocumentOrigin, store) => {
         const subscribe = origin.subscribe_id && this.subscribes.get(origin.subscribe_id)
-        const client = subscribe && this.clients.get(subscribe.client_id)
+        const liveClient = subscribe && this.clients.get(subscribe.client_id)
+        const client = liveClient || (origin.store_context
+          ? ({
+              id: origin.store_context.client_id,
+              auth: origin.store_context.auth
+            } as CuboCrdtSocketClient<A>)
+          : undefined)
 
         if (client) {
           return this.options?.storeRow?.(entity as any, entity_id, item as any, {
@@ -675,7 +730,13 @@ export class CuboCrdtServer<M, A = {}, E extends Extract<keyof M, string> = Extr
     const existed = this.documents.has(documentName)
     const document = this.getOrCreateDocument(entity, row, awareness)
 
-    if (!existed) {
+    if (existed && !document.hasPendingStore()) {
+      // Только внешний CRUD является подтверждённым источником из БД.
+      // Обычная повторная подписка не должна применять потенциально старую строку
+      // поверх живого документа с ещё не сохранённым collaborative update.
+      document.write(row, { expose: 'all', store: false })
+      document.setPersistedState(row)
+    } else {
       this.pushDocumentAction('create', entity, document, document.stateAsUpdate)
     }
 

package/src/server/types/document.ts

@@ -5,6 +5,20 @@ export type CuboCrdtServerDocumentStoreContext = {
   row: object
 }
 
+export type CuboCrdtServerDocumentStoreWaiter = {
+  resolve: () => void
+  reject: (reason?: unknown) => void
+}
+
+export type CuboCrdtServerDocumentPendingStore = {
+  body: object
+  changeKey: string
+  origin: CuboCrdtServerDocumentOrigin
+  originKey: string
+  row: object
+  waiters: CuboCrdtServerDocumentStoreWaiter[]
+}
+
 export type CuboCrdtServerDocumentOptions = {
   name: string
   onStore?: (
@@ -63,4 +77,16 @@ export type CuboCrdtServerDocumentOrigin = {
 
   // id клиента
   client_id?: string
+
+  /**
+   * Снимок серверного контекста автора в момент получения update.
+   *
+   * Он нужен только для отложенного сохранения: исходная подписка и сокет могут
+   * закрыться при refresh раньше, чем сработает debounce. Клиентское значение
+   * этого поля сервер всегда перезаписывает собственными данными.
+   */
+  store_context?: {
+    client_id: string
+    auth?: unknown
+  }
 }

package/src/server/utils/index.ts

@@ -0,0 +1,41 @@
+const isObject = (value: unknown): value is Record<string, unknown> => {
+  return value !== null && typeof value === 'object'
+}
+
+const collectChangedPaths = (
+  previous: unknown,
+  current: unknown,
+  path: string,
+  result: string[]
+) => {
+  if (Object.is(previous, current)) {
+    return
+  }
+
+  if (!isObject(previous) || !isObject(current)) {
+    result.push(path || '$')
+    return
+  }
+
+  const keys = new Set([
+    ...Object.keys(previous),
+    ...Object.keys(current)
+  ])
+
+  for (const key of [...keys].sort()) {
+    const nextPath = Array.isArray(previous) || Array.isArray(current)
+      ? `${path}[${key}]`
+      : path ? `${path}.${key}` : key
+
+    collectChangedPaths(previous[key], current[key], nextPath, result)
+  }
+}
+
+/** Возвращает стабильный ключ фактически изменённых leaf-путей объекта. */
+export const getCrdtStoreChangeKey = (previous: object, current: object) => {
+  const paths: string[] = []
+
+  collectChangedPaths(previous, current, '', paths)
+
+  return paths.join('|')
+}