在 Durable Streams 上同步 Yjs CRDT 文档y-durable-streams 集成指南【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electricy-durable-streams 是一个基于 Durable Streams 的 Yjs 连接提供者connection provider它让开发者可以只用普通 HTTP 协议无需任何 WebSocket 基础设施完成 Yjs CRDT 文档的快照发现、实时更新、服务端自动压缩compaction与可选的存在感知Awareness / presence同步。读完本文你将掌握durable-streams/y-durable-streams的安装、Provider 配置、生命周期管理与四步同步协议的完整原理并了解它在本仓库 Durable Streams 生态中的定位与源码级实现依据。核心特性HTTP 之上的 CRDT 同步Yjs 是 Web 协作编辑领域的事实标准 CRDT 库但大多数 Yjs 部署依赖 WebSocket 中继服务器通过维持点对点长连接来实时分发变更。y-durable-streams 换了一种思路把每个 Yjs 文档CRDT映射为一条持久化、可追加append-only的 Durable Stream 日志客户端通过普通 HTTP 请求写入编辑内容再通过 SSE 或长轮询long-polling订阅实时更新。这一模式带来的核心能力包括快照发现snapshot discovery新客户端快速定位最新快照偏移实现快速追平实时更新live updates通过 SSE 或长轮询持续接收增量更新服务端自动压缩compaction当累积更新超过阈值时自动生成新快照保证新客户端的初始同步足够快可选 Awareness 支持用于光标、选区、用户状态等存在信息广播。本仓库的 Durable Streams 官方博客 指出Durable Streams 采用fan-out 架构变更只写入日志一次即可通过边缘缓存或 CDN 同步给任意数量的已连接客户端——这与 WebSocket 中继在参与者增多时面临的扩展瓶颈形成鲜明对比特别适合协作编辑与多参与者的 agentic 系统。安装npm install durable-streams/y-durable-streams yjs y-protocols lib0其中yjs、y-protocols、lib0是peer dependencies对等依赖需要由你的项目自行安装而y-durable-streams运行时直接使用它们。快速开始创建 Provider、连接服务端并完成首次同步只需少量代码import { YjsProvider } from durable-streams/y-durable-streams import * as Y from yjs import { Awareness } from y-protocols/awareness const doc new Y.Doc() const awareness new Awareness(doc) const provider new YjsProvider({ doc, baseUrl: http://localhost:4438/v1/yjs/my-service, docId: my-document, awareness, }) provider.on(synced, (synced) { console.log(Synced:, synced) })Provider 构造后会自动连接先发现最新快照、将其加载到本地Y.Doc随后持续接收实时更新。synced事件会在首次完成追平后触发。Provider 选项YjsProviderOptions是 Provider 的全部配置入口各字段含义如下interface YjsProviderOptions { doc: Y.Doc // Yjs document to sync baseUrl: string // Server URL, e.g. http://localhost:4438/v1/yjs/my-service docId: string // Document ID (can include slashes, e.g. project/chapter-1) awareness?: Awareness // Optional awareness for presence headers?: HeadersRecord // Optional auth headers liveMode?: sse | long-poll // Live update transport (default: sse) connect?: boolean // Auto-connect on construction (default: true) }各选项说明选项必填说明doc是需要同步的 Yjs 文档实例baseUrl是服务端地址形如http://localhost:4438/v1/yjs/my-servicedocId是文档 ID允许包含斜杠如project/chapter-1便于按层级组织文档awareness否传入y-protocols/awareness的 Awareness 实例以启用存在同步headers否附加 HTTP 请求头常用于鉴权liveMode否实时更新传输方式sse默认或long-poll长轮询connect否构造时是否自动连接默认true事件Provider 基于事件驱动主要暴露三类事件用于状态感知与错误处理// Sync state changes provider.on(synced, (synced: boolean) { if (synced) { console.log(Document is synced with server) } }) // Connection status changes provider.on(status, (status: disconnected | connecting | connected) { console.log(Status:, status) }) // Error handling provider.on(error, (error: Error) { console.error(Provider error:, error) })synced布尔值表示本地文档是否已与服务端完全同步快照加增量全部应用完毕status连接状态机disconnected → connecting → connected的切换通知error同步过程中出现的错误。生命周期管理Provider 提供了完整的连接生命周期控制适用于组件卸载、文档切换、离线恢复等场景// Manual connection const provider new YjsProvider({ doc, baseUrl, docId, connect: false, // Dont connect automatically }) provider.on(synced, handleSync) provider.on(error, handleError) await provider.connect() // Disconnect temporarily provider.disconnect() // Reconnect await provider.connect() // Destroy permanently provider.destroy()三条生命周期方法的定位connect()建立连接并开始同步可多次调用已经连接时调用会被安全忽略disconnect()临时断开连接如用户切换离线状态之后仍可通过connect()恢复destroy()永久销毁清理事件监听并关闭所有连接不可逆。务必在结束使用时调用destroy()以释放事件监听器和网络连接资源。认证通过headers选项为所有请求附加鉴权头例如 Bearer Tokenconst provider new YjsProvider({ doc, baseUrl: http://localhost:4438/v1/yjs/my-service, docId: my-document, awareness, headers: { Authorization: Bearer your-token, }, })服务端可基于这些请求头完成身份校验与访问控制适用于需要私有文档或按用户授权的场景。Awareness存在感知 / Presence将y-protocols/awareness的Awareness实例传给 Provider 即可启用存在同步。y-durable-streams 会广播本地的 awareness 状态光标、选区、用户信息并通过独立的 SSE 流订阅远端 awareness 更新import * as Y from yjs import { Awareness } from y-protocols/awareness import { YjsProvider } from durable-streams/y-durable-streams const doc new Y.Doc() const awareness new Awareness(doc) const provider new YjsProvider({ doc, baseUrl: http://localhost:4438/v1/yjs/my-service, docId: my-document, awareness, }) // Set local user presence awareness.setLocalStateField(user, { name: Alice, color: #ff0000, }) // Listen for remote awareness changes awareness.on(change, () { const states awareness.getStates() console.log(Online users:, states.size) })两个重要的传输细节心跳Awareness 心跳每15 秒发送一次用于维持在线状态离开通知Provider 断开时会主动广播移除消息让其他客户端立即看到该用户下线而无需等待心跳超时。工作原理四步 HTTP 同步协议y-durable-streams 通过 HTTP 完成全部同步协议分四步快照发现Snapshot discovery—— 请求?offsetsnapshot服务端以307 重定向指向最新快照的偏移若无快照则返回-1。快照加载Snapshot loading—— 拉取二进制 Yjs 快照并应用到本地文档响应头stream-next-offset指明后续增量从哪个偏移继续。实时更新Live updates—— 从该偏移起通过长轮询或 SSE 持续接收增量更新本地编辑则经**幂等生产者idempotent producer写入服务端保证恰好一次exactly-once**投递语义。Awareness—— 可选的独立 SSE 流通过具名 awareness 通道承载光标、选区、用户信息等存在数据。这里同样可以看到 Durable Streams 的通用机制在起作用offset是流式读取的核心游标服务端将日志持久化存储客户端以偏移量为锚点实现断点续传resume这在本仓库的 Durable State 文档 中也有对应体现。自动压缩Compaction当文档累积的更新超过大小阈值时y-durable-streams 会自动执行压缩在当前偏移处生成一个新快照把此前的历史更新折叠进快照主体。这样新加入的客户端只需加载一个快照即可快速追上而无需重放全部增量历史。压缩对已连接客户端完全透明——现有连接不会被打断继续从各自偏移接收后续增量即可。从本仓库的 Durable Streams 服务端实现 看日志的分层存储tier与快照/增量文件的组织正是为这类读写路径优化的基础相关逻辑分布在 tier.rs、store.rs 等模块中。URL 结构每个文档通过单一 URL 查询参数访问{baseUrl}/docs/{docPath}?{queryParams}其中docPath可以包含正斜杠如project/chapter-1因此服务名、文档路径、偏移量、传输模式等信息都可以通过 URL 与查询参数完整表达天然适合 HTTP 缓存与 CDN 边缘加速。最佳实践始终调用destroy()在组件卸载或离开文档时清理 Provider防止事件泄漏与连接残留useEffect(() { const provider new YjsProvider({ doc, baseUrl, docId, awareness }) return () provider.destroy() }, [])使用层级化文档路径利用docId支持斜杠的特性按业务逻辑组织文档// Good docId: org/project/chapter-1 // Also works docId: simple-doc优雅处理错误y-durable-streams 会在瞬时故障时自动重连但 UI 层仍应监听error事件给出反馈provider.on(error, (error) { showToast(Connection issue — retrying...) })仓库内的相关参考资源Durable State 文档 —— 了解 Durable Streams 之上结构化的状态同步模型Durable Streams 官方发布博客 —— y-durable-streams 的架构背景与 fan-out 设计动机Y-Electric 包 README —— 仓库内另一条 Yjs 集成路线通过electric-sql/y-electric把 Yjs 文档同步到 Postgres依赖 Electric sync 引擎而非 Durable StreamsYjs 示例应用 —— 基于 CodeMirror Yjs 的多人协作编辑器示例展示了 Awareness、本地 IndexedDB 持久化与 resume state 的完整落地其服务端 server.ts 演示了如何在自定义服务中接收 Yjs 更新并写入数据库Y-Electric 源码 ——ElectricProvider的实现细节包括文档更新的合并批量发送mergeUpdates、去抖动debounceMs与断开时 awareness 移除等机制可作为理解 Provider 内部状态机的对照参考。【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 在 Durable Streams 上同步 Yjs CRDT 文档：y-durable-streams 集成指南
在 Durable Streams 上同步 Yjs CRDT 文档y-durable-streams 集成指南【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electricy-durable-streams 是一个基于 Durable Streams 的 Yjs 连接提供者connection provider它让开发者可以只用普通 HTTP 协议无需任何 WebSocket 基础设施完成 Yjs CRDT 文档的快照发现、实时更新、服务端自动压缩compaction与可选的存在感知Awareness / presence同步。读完本文你将掌握durable-streams/y-durable-streams的安装、Provider 配置、生命周期管理与四步同步协议的完整原理并了解它在本仓库 Durable Streams 生态中的定位与源码级实现依据。核心特性HTTP 之上的 CRDT 同步Yjs 是 Web 协作编辑领域的事实标准 CRDT 库但大多数 Yjs 部署依赖 WebSocket 中继服务器通过维持点对点长连接来实时分发变更。y-durable-streams 换了一种思路把每个 Yjs 文档CRDT映射为一条持久化、可追加append-only的 Durable Stream 日志客户端通过普通 HTTP 请求写入编辑内容再通过 SSE 或长轮询long-polling订阅实时更新。这一模式带来的核心能力包括快照发现snapshot discovery新客户端快速定位最新快照偏移实现快速追平实时更新live updates通过 SSE 或长轮询持续接收增量更新服务端自动压缩compaction当累积更新超过阈值时自动生成新快照保证新客户端的初始同步足够快可选 Awareness 支持用于光标、选区、用户状态等存在信息广播。本仓库的 Durable Streams 官方博客 指出Durable Streams 采用fan-out 架构变更只写入日志一次即可通过边缘缓存或 CDN 同步给任意数量的已连接客户端——这与 WebSocket 中继在参与者增多时面临的扩展瓶颈形成鲜明对比特别适合协作编辑与多参与者的 agentic 系统。安装npm install durable-streams/y-durable-streams yjs y-protocols lib0其中yjs、y-protocols、lib0是peer dependencies对等依赖需要由你的项目自行安装而y-durable-streams运行时直接使用它们。快速开始创建 Provider、连接服务端并完成首次同步只需少量代码import { YjsProvider } from durable-streams/y-durable-streams import * as Y from yjs import { Awareness } from y-protocols/awareness const doc new Y.Doc() const awareness new Awareness(doc) const provider new YjsProvider({ doc, baseUrl: http://localhost:4438/v1/yjs/my-service, docId: my-document, awareness, }) provider.on(synced, (synced) { console.log(Synced:, synced) })Provider 构造后会自动连接先发现最新快照、将其加载到本地Y.Doc随后持续接收实时更新。synced事件会在首次完成追平后触发。Provider 选项YjsProviderOptions是 Provider 的全部配置入口各字段含义如下interface YjsProviderOptions { doc: Y.Doc // Yjs document to sync baseUrl: string // Server URL, e.g. http://localhost:4438/v1/yjs/my-service docId: string // Document ID (can include slashes, e.g. project/chapter-1) awareness?: Awareness // Optional awareness for presence headers?: HeadersRecord // Optional auth headers liveMode?: sse | long-poll // Live update transport (default: sse) connect?: boolean // Auto-connect on construction (default: true) }各选项说明选项必填说明doc是需要同步的 Yjs 文档实例baseUrl是服务端地址形如http://localhost:4438/v1/yjs/my-servicedocId是文档 ID允许包含斜杠如project/chapter-1便于按层级组织文档awareness否传入y-protocols/awareness的 Awareness 实例以启用存在同步headers否附加 HTTP 请求头常用于鉴权liveMode否实时更新传输方式sse默认或long-poll长轮询connect否构造时是否自动连接默认true事件Provider 基于事件驱动主要暴露三类事件用于状态感知与错误处理// Sync state changes provider.on(synced, (synced: boolean) { if (synced) { console.log(Document is synced with server) } }) // Connection status changes provider.on(status, (status: disconnected | connecting | connected) { console.log(Status:, status) }) // Error handling provider.on(error, (error: Error) { console.error(Provider error:, error) })synced布尔值表示本地文档是否已与服务端完全同步快照加增量全部应用完毕status连接状态机disconnected → connecting → connected的切换通知error同步过程中出现的错误。生命周期管理Provider 提供了完整的连接生命周期控制适用于组件卸载、文档切换、离线恢复等场景// Manual connection const provider new YjsProvider({ doc, baseUrl, docId, connect: false, // Dont connect automatically }) provider.on(synced, handleSync) provider.on(error, handleError) await provider.connect() // Disconnect temporarily provider.disconnect() // Reconnect await provider.connect() // Destroy permanently provider.destroy()三条生命周期方法的定位connect()建立连接并开始同步可多次调用已经连接时调用会被安全忽略disconnect()临时断开连接如用户切换离线状态之后仍可通过connect()恢复destroy()永久销毁清理事件监听并关闭所有连接不可逆。务必在结束使用时调用destroy()以释放事件监听器和网络连接资源。认证通过headers选项为所有请求附加鉴权头例如 Bearer Tokenconst provider new YjsProvider({ doc, baseUrl: http://localhost:4438/v1/yjs/my-service, docId: my-document, awareness, headers: { Authorization: Bearer your-token, }, })服务端可基于这些请求头完成身份校验与访问控制适用于需要私有文档或按用户授权的场景。Awareness存在感知 / Presence将y-protocols/awareness的Awareness实例传给 Provider 即可启用存在同步。y-durable-streams 会广播本地的 awareness 状态光标、选区、用户信息并通过独立的 SSE 流订阅远端 awareness 更新import * as Y from yjs import { Awareness } from y-protocols/awareness import { YjsProvider } from durable-streams/y-durable-streams const doc new Y.Doc() const awareness new Awareness(doc) const provider new YjsProvider({ doc, baseUrl: http://localhost:4438/v1/yjs/my-service, docId: my-document, awareness, }) // Set local user presence awareness.setLocalStateField(user, { name: Alice, color: #ff0000, }) // Listen for remote awareness changes awareness.on(change, () { const states awareness.getStates() console.log(Online users:, states.size) })两个重要的传输细节心跳Awareness 心跳每15 秒发送一次用于维持在线状态离开通知Provider 断开时会主动广播移除消息让其他客户端立即看到该用户下线而无需等待心跳超时。工作原理四步 HTTP 同步协议y-durable-streams 通过 HTTP 完成全部同步协议分四步快照发现Snapshot discovery—— 请求?offsetsnapshot服务端以307 重定向指向最新快照的偏移若无快照则返回-1。快照加载Snapshot loading—— 拉取二进制 Yjs 快照并应用到本地文档响应头stream-next-offset指明后续增量从哪个偏移继续。实时更新Live updates—— 从该偏移起通过长轮询或 SSE 持续接收增量更新本地编辑则经**幂等生产者idempotent producer写入服务端保证恰好一次exactly-once**投递语义。Awareness—— 可选的独立 SSE 流通过具名 awareness 通道承载光标、选区、用户信息等存在数据。这里同样可以看到 Durable Streams 的通用机制在起作用offset是流式读取的核心游标服务端将日志持久化存储客户端以偏移量为锚点实现断点续传resume这在本仓库的 Durable State 文档 中也有对应体现。自动压缩Compaction当文档累积的更新超过大小阈值时y-durable-streams 会自动执行压缩在当前偏移处生成一个新快照把此前的历史更新折叠进快照主体。这样新加入的客户端只需加载一个快照即可快速追上而无需重放全部增量历史。压缩对已连接客户端完全透明——现有连接不会被打断继续从各自偏移接收后续增量即可。从本仓库的 Durable Streams 服务端实现 看日志的分层存储tier与快照/增量文件的组织正是为这类读写路径优化的基础相关逻辑分布在 tier.rs、store.rs 等模块中。URL 结构每个文档通过单一 URL 查询参数访问{baseUrl}/docs/{docPath}?{queryParams}其中docPath可以包含正斜杠如project/chapter-1因此服务名、文档路径、偏移量、传输模式等信息都可以通过 URL 与查询参数完整表达天然适合 HTTP 缓存与 CDN 边缘加速。最佳实践始终调用destroy()在组件卸载或离开文档时清理 Provider防止事件泄漏与连接残留useEffect(() { const provider new YjsProvider({ doc, baseUrl, docId, awareness }) return () provider.destroy() }, [])使用层级化文档路径利用docId支持斜杠的特性按业务逻辑组织文档// Good docId: org/project/chapter-1 // Also works docId: simple-doc优雅处理错误y-durable-streams 会在瞬时故障时自动重连但 UI 层仍应监听error事件给出反馈provider.on(error, (error) { showToast(Connection issue — retrying...) })仓库内的相关参考资源Durable State 文档 —— 了解 Durable Streams 之上结构化的状态同步模型Durable Streams 官方发布博客 —— y-durable-streams 的架构背景与 fan-out 设计动机Y-Electric 包 README —— 仓库内另一条 Yjs 集成路线通过electric-sql/y-electric把 Yjs 文档同步到 Postgres依赖 Electric sync 引擎而非 Durable StreamsYjs 示例应用 —— 基于 CodeMirror Yjs 的多人协作编辑器示例展示了 Awareness、本地 IndexedDB 持久化与 resume state 的完整落地其服务端 server.ts 演示了如何在自定义服务中接收 Yjs 更新并写入数据库Y-Electric 源码 ——ElectricProvider的实现细节包括文档更新的合并批量发送mergeUpdates、去抖动debounceMs与断开时 awareness 移除等机制可作为理解 Provider 内部状态机的对照参考。【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考