y-durableobjects

The y-durableobjects library is designed to facilitate real-time collaboration in Cloudflare Workers environment using Yjs and Durable Objects. It provides a straightforward way to integrate Yjs for decentralized, scalable real-time editing features.

Requirements

Hono version 4.2 or higher is required.

Installation

To use y-durableobjects, you need to install the package along with hono, as it is a peer dependency.

npm install y-durableobjects hono

or using yarn:

yarn add y-durableobjects hono

or pnpm:

pnpm add y-durableobjects hono

Below is an updated section for your README, including the recommended wrangler.toml configuration for Durable Objects, followed by the new section providing guidance on configuring Durable Objects:

Configuring Durable Objects

To use Durable Objects with y-durableobjects, include the following configuration in your wrangler.toml file. This setup is essential for defining the Durable Object bindings that your Cloudflare Worker will use.

name = "your-worker-name"
main = "index.js"
compatibility_date = "2021-10-01"

account_id = "your-account-id"
workers_dev = true
route = ""
zone_id = ""

# Durable Objects binding
[durable_objects]
bindings = [
  { name = "Y_DURABLE_OBJECTS", class_name = "YDurableObjects" }
]

# Add your KV Namespaces and other bindings here
# [kv_namespaces]
# ...

# Your environment variables
# [vars]
# ...

Configuration for Durable Objects

To properly utilize Durable Objects, you need to configure bindings in your wrangler.toml file. This involves specifying the name of the Durable Object binding and the class name that represents your Durable Object. For detailed instructions on how to set up your wrangler.toml for Durable Objects, including setting up environment variables and additional resources, refer to Cloudflare's Durable Objects documentation.

This configuration ensures that your Cloudflare Worker can correctly instantiate and interact with Durable Objects, allowing y-durableobjects to manage real-time collaboration sessions.

Extending Hono with Bindings

To integrate y-durableobjects with Hono, extend the Env interface to include the Bindings type for better type safety and IntelliSense support in your editor.

export type Bindings = {
  Y_DURABLE_OBJECTS: DurableObjectNamespace;
};

declare module "hono" {
  interface Env {
    Bindings: Bindings;
  }
}

This allows you to use Y_DURABLE_OBJECTS directly in your Hono application with full type support.

Usage

With Hono shorthand

import { Hono } from "hono";
import { cors } from "hono/cors";
import { YDurableObjects, yRoute } from "y-durableobjects";

const app = new Hono();
app.use("*", cors());

const route = app.route(
  "/editor",
  yRoute((env) => env.Y_DURABLE_OBJECTS),
);

export default route;
export { YDurableObjects };

Without the shorthand

import { Hono } from "hono";
import { cors } from "hono/cors";
import { YDurableObjects } from "y-durableobjects";

const app = new Hono();
app.use("*", cors());
app.get("/editor/:id", async (c) => {
  const id = c.env.Y_DURABLE_OBJECTS.idFromName(c.req.param("id"));
  const obj = c.env.Y_DURABLE_OBJECTS.get(id);

  // get websocket connection
  const url = new URL("/", c.req.url);
  const res = await obj.fetch(url.href, {
    headers: c.req.raw.headers,
  });
  if (res.webSocket === null) return c.body(null, 500);

  return new Response(null, { webSocket: res.webSocket, status: res.status });
});

export default app;
export { YDurableObjects };

Hono RPC support

Utilizes Hono's WebSocket Helper, making the $ws method available in hono/client for WebSocket communications.
- For more information on server and client setup, see the Hono WebSocket Helper documentation.

Server Implementation

import { Hono } from "hono";
import { cors } from "hono/cors";
import { YDurableObjects, yRoute } from "y-durableobjects";

const app = new Hono();
app.use("*", cors());

const route = app.route(
  "/editor",
  yRoute((env) => env.Y_DURABLE_OBJECTS),
);

export default route;
export type AppType = typeof route;
export { YDurableObjects };

Client Implementation

import { hc } from "hono/client";
import type { AppType } from "./server"; // Adjust the import path as needed

const API_URL = "http://localhost:8787";

export const client = hc<AppType>(API_URL);
const ws = client.editor[":id"].$ws({ param: { id: "example" } });
//    ^?const ws: WebSocket

yDoc must be saved with each change.

Problems with existing implementation

In the Hibernation API, instances of DurableObjects go dormant as soon as no data is sent from the client, so yDocs stored in-memory are quickly volatile.

Therefore, the existing implementation of storing the in-memory state in transaction storage when the number of connections drops below a certain number is not appropriate.

Reason why it seems to work in the demo site

However, https://yjs.napochaan.dev, which is now available on the demo site, seems to work fine.
This is because the client implementation of y-websocket, WebSocketProvider, wrote a constructor that periodically sends local yDoc when the connection becomes Open, so it does not go into hibernation state even if Hibernation API is used, It is assumed that the server-side yDoc remained unvolatilized until the client communication was disconnected.

https://github.com/yjs/y-websocket/blob/master/src/y-websocket.js#L302-L311

What should be changed

Store changes received via webSocketMessage in transaction storage on a per-snapshot basis
- Introduce state with the following key to guarantee order.
  - snapshot_size.
  - snapshot:${count}
    - count: the total number of currently stored snapshots +1
Join snapshots with constructor and restore yDoc.
Control when to merge snapshot.
- idea1: when the number of concurrent connections reaches 0
- idea2: when size exceeds a certain number
- cf: https://docs.partykit.io/reference/y-partykit-api/#:~:text=%7D-,Persistence,-By%20default%2C%20PartyKit

napolab / y-durableobjects Goto Github PK