Rushlight

Real-time collaborative code editing on your own infrastructure

MarkdownReal-time
ekzhang/rushlightrushlight.up.railway.apprushlight

README

🕯️ Rushlight


_Make collaborative code editors that run on your own infrastructure: just Redis
and a database._


Supports multiple real-time documents, with live cursors. Based on
CodeMirror 6 and
operational transformation, so all
changes are resolved by server code. It's designed to be as easy to integrate as
possible (read: boring). The backend is stateless, and _you can bring your own
transport_; even a single HTTP handler is enough.

Unlike most toy examples, Rushlight supports persistence in any durable database
you choose. Real-time updates are replicated in-memory by Redis, with automatic
log compaction.

An experiment by Eric Zhang, author of
Rustpad.

Motivation


Let's say you're writing a web application. You already have a database, and you
want to add real-time collaborative editing. However, most libraries are
unsuitable because they:

- Require proprietary gadgets
- Are not flexible enough, e.g., to customize appearance
- Make you subscribe to a cloud service where you can't control the data
- Use decentralized algorithms like CRDTs that are hard to reason about
- Make it difficult to authenticate users or apply rate limits
- Rely on a single stateful server, which breaks with replication / horizontal
  autoscaling
- Need WebSockets or other protocols that aren't supported by some providers
- Are just generally too opinionated

This library tries to take a more practical approach.

Usage


Install the client and server packages.

  1. ```bash
  2. # client
  3. npm install rushlight

  5. # server
  6. npm install rushlight-server
  7. ```

On the frontend, create a CollabClient object and attach it to your CodeMirror
instance via extensions.

  1. ```ts
  2. import { EditorView } from "codemirror";
  3. import { CollabClient } from "rushlight";

  5. const rushlight = await CollabClient.of({
  6.   async connection(message) {
  7.     // You can use any method to send messages to the server. This example
  8.     // executes a simple POST request.
  9.     const resp = await fetch(`/doc/${id}`, {
  10.       method: "POST",
  11.       body: JSON.stringify(message),
  12.       headers: { "Content-Type": "application/json" },
  13.     });
  14.     if (resp.status !== 200) {
  15.       throw new Error(`Request failed with status ${resp.status}`);
  16.     }
  17.     return await resp.json();
  18.   },
  19. });

  21. const view = new EditorView({
  22.   extensions: [
  23.     // ...
  24.     rushlight,
  25.     rushlight.presence, // Optional, if you want to show remote cursors.
  26.   ],
  27.   // ...
  28. });
  29. ```

Then, on the server, we need to write a corresponding handler for the POST
request. Create a CollabServer object, which requires a Redis connection
string and a persistent database for document storage.

The example below is with express, but you can use any framework.

  1. ```ts
  2. import express from "express";
  3. import { Checkpoint, CollabServer } from "rushlight-server";

  5. const rushlight = await CollabServer.of({
  6.   redisUrl: process.env.REDIS_URL || "redis://localhost:6473",
  7.   async loadCheckpoint(id: string): Promise<Checkpoint> {
  8.     // ... Load the document from your database.
  9.     return { version, doc };
  10.   },
  11.   async saveCheckpoint(id: string, { version, doc }: Checkpoint) {
  12.     // ... Save the new version of the document to your database.
  13.   },
  14. });

  16. rushlight.compactionTask(); // Run this in the background.

  18. const app = express();

  20. app.post("/doc/:id", express.json(), async (req, res) => {
  21.   const id = req.params.id;
  22.   try {
  23.     res.json(await rushlight.handle(id, req.body));
  24.   } catch (e: any) {
  25.     console.log("Failed to handle user message:", e.toString());
  26.     res.status(400).send(e.toString());
  27.   }
  28. });

  30. app.listen(8080);
  31. ```

That's it! See the ClientOptions and ServerOptions types for more
configuration options.

To view a full demo application, a collaborative Markdown editor using Postgres
to store documents, see the [app/](app/) folder in this repository.