mirror of
https://github.com/outline/outline.git
synced 2026-11-22 05:51:43 +03:00
246 lines
7.0 KiB
TypeScript
246 lines
7.0 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 {
|
|
MultiplayerEntityType,
|
|
parseMultiplayerName,
|
|
} from "@shared/collaboration/EntityName";
|
|
import env from "@server/env";
|
|
import Logger from "@server/logging/Logger";
|
|
import { trace } from "@server/logging/tracing";
|
|
import Collection from "@server/models/Collection";
|
|
import Document from "@server/models/Document";
|
|
import type { HookContext } from "@server/models/base/Model";
|
|
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 {
|
|
// Create a dedicated subscriber for API update notifications
|
|
this.subscriber = new RedisAdapter(
|
|
env.REDIS_COLLABORATION_URL || env.REDIS_URL,
|
|
{
|
|
connectionNameSuffix: "collab-api-updates",
|
|
maxRetriesPerRequest: null,
|
|
}
|
|
);
|
|
|
|
// Handle Redis connection errors
|
|
this.subscriber.on("error", (err) => {
|
|
Logger.error("Redis subscriber error in APIUpdateExtension", err);
|
|
});
|
|
|
|
// 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> {
|
|
this.documents.set(documentName, document);
|
|
}
|
|
|
|
async onDestroy(_data: onDestroyPayload): Promise<void> {
|
|
if (this.subscriber) {
|
|
await this.subscriber.punsubscribe(`${CHANNEL_PREFIX}:*`);
|
|
await this.subscriber.quit();
|
|
this.subscriber = null;
|
|
}
|
|
this.documents.clear();
|
|
}
|
|
|
|
/**
|
|
* Handle a document being disconnected (no more clients).
|
|
*/
|
|
async onDisconnect({
|
|
documentName,
|
|
clientsCount,
|
|
}: onDisconnectPayload): Promise<void> {
|
|
if (clientsCount === 0) {
|
|
this.documents.delete(documentName);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Handle incoming Redis messages for API updates.
|
|
*/
|
|
private handleMessage = async (
|
|
_pattern: string,
|
|
channel: string,
|
|
message: string
|
|
): Promise<void> => {
|
|
try {
|
|
const documentName = channel.replace(`${CHANNEL_PREFIX}:`, "");
|
|
const document = this.documents.get(documentName);
|
|
|
|
if (!document) {
|
|
// Document not loaded in this instance, ignore
|
|
return;
|
|
}
|
|
|
|
const data = JSON.parse(message);
|
|
const { type, id } = parseMultiplayerName(documentName);
|
|
|
|
Logger.debug("multiplayer", `Received API update for ${type}`, {
|
|
documentId: id,
|
|
actorId: data.actorId,
|
|
});
|
|
|
|
// Fetch the latest state from the database
|
|
const dbEntity =
|
|
type === MultiplayerEntityType.Collection
|
|
? await Collection.unscoped().findOne({
|
|
attributes: ["state"],
|
|
where: { id },
|
|
})
|
|
: await Document.unscoped().findOne({
|
|
attributes: ["state"],
|
|
where: { id },
|
|
});
|
|
|
|
if (!dbEntity) {
|
|
Logger.warn(`${documentName} not found in database`);
|
|
return;
|
|
}
|
|
|
|
if (!dbEntity.state) {
|
|
Logger.warn(`${documentName} has no state in database`);
|
|
return;
|
|
}
|
|
|
|
// Create a Y.Doc from the database state
|
|
const dbYdoc = new Y.Doc();
|
|
Y.applyUpdate(dbYdoc, dbEntity.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 ${type}`, {
|
|
documentId: id,
|
|
updateSize: update.length,
|
|
});
|
|
}
|
|
|
|
dbYdoc.destroy();
|
|
} catch (error) {
|
|
Logger.error("Failed to process API update message", error as Error);
|
|
}
|
|
};
|
|
|
|
/**
|
|
* Publish a notification that an entity was updated via the API once the
|
|
* current transaction, if any, has committed. This should be called from
|
|
* the entity's update hook.
|
|
*
|
|
* @param documentName - the multiplayer name of the entity that was updated, eg "document.123".
|
|
* @param ctx - the hook context of the update.
|
|
*/
|
|
static notifyUpdateAfterCommit(documentName: string, ctx: HookContext) {
|
|
const actorId = ctx.auth?.user?.id;
|
|
if (!actorId) {
|
|
return;
|
|
}
|
|
|
|
const notify = () => APIUpdateExtension.notifyUpdate(documentName, actorId);
|
|
|
|
if (ctx.transaction) {
|
|
const transaction = ctx.transaction.parent || ctx.transaction;
|
|
transaction.afterCommit(notify);
|
|
} else {
|
|
void notify();
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Publish a notification that an entity was updated via the API.
|
|
* This should be called from the entity's update command.
|
|
*
|
|
* @param documentName - the multiplayer name of the entity that was updated, eg "document.123".
|
|
* @param actorId - the id of the user who made the update.
|
|
*/
|
|
static async notifyUpdate(
|
|
documentName: string,
|
|
actorId: string
|
|
): Promise<void> {
|
|
const channel = `${CHANNEL_PREFIX}:${documentName}`;
|
|
const message = JSON.stringify({
|
|
actorId,
|
|
timestamp: Date.now(),
|
|
});
|
|
|
|
await RedisAdapter.defaultClient.publish(channel, message);
|
|
|
|
Logger.debug("multiplayer", `Published API update notification`, {
|
|
documentName,
|
|
actorId,
|
|
});
|
|
}
|
|
}
|