Files
Tom MoorandClaude Opus 5 7f54d5ea10 Re-authorize collaboration connections when access changes (#13454)
* feat: Re-authorize collaboration connections when access changes

Collaboration connections are authorized once, when the websocket is first
established, so a connection outlives changes to the access it was granted.

Add a processor that publishes access changes to the collaboration servers
over Redis. Each server closes the connections it holds within the scope of
the change and clients reconnect, at which point they are authorized as
normal. Authorization stays in one place, the published scope only has to
cover the connections that may be affected.

The API update subscriber now shares a single Redis connection rather than
opening its own.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* refactor: Log an access change once rather than per connection

Every closed connection is already logged by LoggerExtension, so record the
reason and the number of connections affected once instead. The count also
makes a scope that matches nothing visible.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-16 12:49:34 -04:00

198 lines
5.5 KiB
TypeScript

import type {
Extension,
afterLoadDocumentPayload,
onConfigurePayload,
onDestroyPayload,
onDisconnectPayload,
} from "@hocuspocus/server";
import type { Document as HocuspocusDocument } from "@hocuspocus/server";
import * as Y from "yjs";
import Logger from "@server/logging/Logger";
import { trace } from "@server/logging/tracing";
import Document from "@server/models/Document";
import RedisAdapter from "@server/storage/redis";
/**
* Redis channel prefix for API update notifications.
*/
const CHANNEL_PREFIX = "collaboration:api-update";
/**
* Extension that listens for document updates made through the API and syncs
* them to the collaborative editing state held in memory.
*
* When a document is updated via the API (e.g., documents.update endpoint),
* a message is published to Redis. This extension receives that message and
* reloads the document state from the database, then broadcasts the update
* to all connected clients.
*/
@trace()
export class APIUpdateExtension implements Extension {
/**
* Map of document names to their Hocuspocus Document instances.
*/
private documents: Map<string, HocuspocusDocument> = new Map();
/**
* Redis subscriber client for receiving update notifications.
*/
private subscriber: RedisAdapter | null = null;
/**
* Whether the extension has been configured.
*/
private configured = false;
async onConfigure(_data: onConfigurePayload): Promise<void> {
if (this.configured) {
return;
}
this.configured = true;
try {
this.subscriber = RedisAdapter.collaborationSubscriber;
// Subscribe to the API update channel pattern
await this.subscriber.psubscribe(`${CHANNEL_PREFIX}:*`, (err) => {
if (err) {
Logger.error("Failed to subscribe to API update channel", err);
return;
}
Logger.debug(
"multiplayer",
`Subscribed to ${CHANNEL_PREFIX}:* for API updates`
);
});
// Handle incoming messages
this.subscriber.on("pmessage", this.handleMessage);
} catch (error) {
Logger.error(
"Failed to configure APIUpdateExtension Redis subscriber",
error as Error
);
this.subscriber = null;
this.configured = false;
}
}
async afterLoadDocument({
documentName,
document,
}: afterLoadDocumentPayload): Promise<void> {
const [, documentId] = documentName.split(".");
this.documents.set(documentId, document);
}
async onDestroy(_data: onDestroyPayload): Promise<void> {
if (this.subscriber) {
this.subscriber.off("pmessage", this.handleMessage);
await this.subscriber.punsubscribe(`${CHANNEL_PREFIX}:*`);
this.subscriber = null;
}
this.documents.clear();
}
/**
* Handle a document being disconnected (no more clients).
*/
async onDisconnect({
documentName,
clientsCount,
}: onDisconnectPayload): Promise<void> {
if (clientsCount === 0) {
const [, documentId] = documentName.split(".");
this.documents.delete(documentId);
}
}
/**
* Handle incoming Redis messages for API updates.
*/
private handleMessage = async (
_pattern: string,
channel: string,
message: string
): Promise<void> => {
try {
const documentId = channel.replace(`${CHANNEL_PREFIX}:`, "");
const document = this.documents.get(documentId);
if (!document) {
// Document not loaded in this instance, ignore
return;
}
const data = JSON.parse(message);
Logger.debug("multiplayer", `Received API update for document`, {
documentId,
actorId: data.actorId,
});
// Fetch the latest state from the database
const dbDocument = await Document.unscoped().findOne({
attributes: ["state", "content", "text"],
where: { id: documentId },
});
if (!dbDocument) {
Logger.warn(`Document ${documentId} not found in database`);
return;
}
if (!dbDocument.state) {
Logger.warn(`Document ${documentId} has no state in database`);
return;
}
// Create a Y.Doc from the database state
const dbYdoc = new Y.Doc();
Y.applyUpdate(dbYdoc, dbDocument.state);
// Calculate the diff between the current in-memory state and the database state
const currentStateVector = Y.encodeStateVector(document);
const update = Y.encodeStateAsUpdate(dbYdoc, currentStateVector);
// Apply the update if there are changes
if (update.length > 0) {
Y.applyUpdate(document, update);
Logger.info("multiplayer", `Applied API update to document`, {
documentId,
updateSize: update.length,
});
}
dbYdoc.destroy();
} catch (error) {
Logger.error("Failed to process API update message", error as Error);
}
};
/**
* Publish a notification that a document was updated via the API.
* This should be called from the document update command.
*
* @param documentId - the id of the document that was updated.
* @param actorId - the id of the user who made the update.
*/
static async notifyUpdate(
documentId: string,
actorId: string
): Promise<void> {
const channel = `${CHANNEL_PREFIX}:${documentId}`;
const message = JSON.stringify({
actorId,
timestamp: Date.now(),
});
await RedisAdapter.collaborationClient.publish(channel, message);
Logger.debug("multiplayer", `Published API update notification`, {
documentId,
actorId,
});
}
}