feat(collaborator): add appendContent RPC for merge (non-clobbering) writes

foundations/core/packages/collaborator-client/src/client.ts

@@ -45,11 +45,21 @@ export interface UpdateContentRequest {
 // eslint-disable-next-line @typescript-eslint/no-empty-interface
 export interface UpdateContentResponse {}
 
+/** @public */
+export interface AppendContentRequest {
+  content: Record<string, Markup>
+}
+
+/** @public */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface AppendContentResponse {}
+
 /** @public */
 export interface CollaboratorClient {
   getMarkup: (document: CollaborativeDoc, source?: Ref<Blob> | null) => Promise<Markup>
   createMarkup: (document: CollaborativeDoc, markup: Markup) => Promise<MarkupBlobRef>
   updateMarkup: (document: CollaborativeDoc, markup: Markup) => Promise<void>
+  appendMarkup: (document: CollaborativeDoc, markup: Markup) => Promise<void>
   copyContent: (source: CollaborativeDoc, target: CollaborativeDoc) => Promise<void>
 }
 
@@ -140,6 +150,20 @@ class CollaboratorClientImpl implements CollaboratorClient {
     )
   }
 
+  async appendMarkup (document: CollaborativeDoc, markup: Markup): Promise<void> {
+    const content = {
+      [document.objectAttr]: markup
+    }
+
+    await retry(
+      3,
+      async () => {
+        await this.rpc<AppendContentRequest, AppendContentResponse>(document, 'appendContent', { content })
+      },
+      50
+    )
+  }
+
   async copyContent (source: CollaborativeDoc, target: CollaborativeDoc, content?: Ref<Blob>): Promise<void> {
     const markup = await this.getMarkup(source, content)
     await this.updateMarkup(target, markup)

server/collaborator/src/__tests__/appendContent.test.ts

@@ -0,0 +1,91 @@
+//
+// Copyright © 2024 Hardcore Engineering Inc.
+//
+// Licensed under the Eclipse Public License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License. You may
+// obtain a copy of the License at https://www.eclipse.org/legal/epl-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+import { XmlElement, XmlFragment, XmlText, Doc as YDoc, applyUpdate, encodeStateAsUpdate } from 'yjs'
+
+// These tests pin the one behavioural difference between updateContent and
+// appendContent: both encode the incoming markup as a Y.js update and apply it
+// inside the document's XmlFragment, but updateContent clears the fragment
+// first (fragment.delete(0, fragment.length)) while appendContent does not.
+// Clearing => replace; not clearing => the CRDT merges the new content in,
+// giving append semantics while preserving concurrent edits.
+
+const field = 'content'
+
+function makeDoc (text: string): YDoc {
+  const doc = new YDoc()
+  const fragment = doc.getXmlFragment(field)
+  const paragraph = new XmlElement('paragraph')
+  paragraph.insert(0, [new XmlText(text)])
+  fragment.insert(0, [paragraph])
+  return doc
+}
+
+function textOf (doc: YDoc): string {
+  return doc.getXmlFragment(field).toString()
+}
+
+describe('appendContent semantics', () => {
+  it('append (no fragment.delete) into an empty document adds the new content', () => {
+    const target = new YDoc()
+    const incoming = makeDoc('new')
+
+    applyUpdate(target, encodeStateAsUpdate(incoming))
+
+    expect(textOf(target)).toContain('new')
+  })
+
+  it('append (no fragment.delete) preserves prior content and adds the new content', () => {
+    const target = makeDoc('existing')
+    const incoming = makeDoc('new')
+
+    applyUpdate(target, encodeStateAsUpdate(incoming))
+
+    const result = textOf(target)
+    expect(result).toContain('existing')
+    expect(result).toContain('new')
+  })
+
+  it('update (with fragment.delete) replaces prior content', () => {
+    const target = makeDoc('existing')
+    const incoming = makeDoc('new')
+
+    target.transact(() => {
+      const fragment: XmlFragment = target.getXmlFragment(field)
+      fragment.delete(0, fragment.length)
+      applyUpdate(target, encodeStateAsUpdate(incoming))
+    })
+
+    const result = textOf(target)
+    expect(result).not.toContain('existing')
+    expect(result).toContain('new')
+  })
+
+  it('two independent appends both land (CRDT merge, no clobber)', () => {
+    const target = makeDoc('base')
+    const appendA = makeDoc('alpha')
+    const appendB = makeDoc('beta')
+
+    // Simulate two automations appending concurrently: each encodes against a
+    // fresh doc and its update is merged into the shared target.
+    applyUpdate(target, encodeStateAsUpdate(appendA))
+    applyUpdate(target, encodeStateAsUpdate(appendB))
+
+    const result = textOf(target)
+    expect(result).toContain('base')
+    expect(result).toContain('alpha')
+    expect(result).toContain('beta')
+  })
+})

server/collaborator/src/rpc/methods/appendContent.ts

@@ -0,0 +1,67 @@
+//
+// Copyright © 2024 Hardcore Engineering Inc.
+//
+// Licensed under the Eclipse Public License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License. You may
+// obtain a copy of the License at https://www.eclipse.org/legal/epl-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+//
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+
+import { type AppendContentRequest, type AppendContentResponse } from '@hcengineering/collaborator-client'
+import { MeasureContext } from '@hcengineering/core'
+import { applyUpdate, encodeStateAsUpdate } from 'yjs'
+import { Context } from '../../context'
+import { RpcMethodParams } from '../rpc'
+
+// Like updateContent, but WITHOUT clearing the existing fragment first. Applying
+// the incoming update onto the untouched Y.XmlFragment merges (appends) the new
+// content into whatever is already there, instead of replacing it. Because the
+// mutation runs inside the same hocuspocus direct connection updateContent uses,
+// it is race-free against concurrent browser editors via the Y.js CRDT layer.
+export async function appendContent (
+  ctx: MeasureContext,
+  context: Context,
+  documentName: string,
+  payload: AppendContentRequest,
+  params: RpcMethodParams
+): Promise<AppendContentResponse> {
+  const { content } = payload
+  const { hocuspocus, transformer } = params
+
+  const updates = ctx.withSync('transform', {}, () => {
+    const updates: Record<string, Uint8Array> = {}
+
+    Object.entries(content).forEach(([field, markup]) => {
+      const ydoc = transformer.toYdoc(markup, field)
+      updates[field] = encodeStateAsUpdate(ydoc)
+    })
+
+    return updates
+  })
+
+  const connection = await ctx.with('connect', {}, () => {
+    return hocuspocus.openDirectConnection(documentName, context)
+  })
+
+  try {
+    await ctx.with('append', {}, () =>
+      connection.transact((document) => {
+        document.transact(() => {
+          Object.entries(updates).forEach(([field, update]) => {
+            applyUpdate(document, update)
+          })
+        }, connection)
+      })
+    )
+  } finally {
+    await connection.disconnect()
+  }
+
+  return {}
+}

server/collaborator/src/rpc/methods/index.ts

@@ -16,10 +16,12 @@
 import { getContent } from './getContent'
 import { createContent } from './createContent'
 import { updateContent } from './updateContent'
+import { appendContent } from './appendContent'
 import { RpcMethod } from '../rpc'
 
 export const methods: Record<string, RpcMethod> = {
   getContent,
   createContent,
-  updateContent
+  updateContent,
+  appendContent
 }