@echovisionlab/geul-common 0.4.0 → 0.6.0

package/src/collaboration/protocol.ts

@@ -0,0 +1,609 @@
+/**
+ * Collaboration control-plane protocol v3: the single definition of every Hocuspocus stateless
+ * message exchanged by the editor (geul-web) and the collaboration server (geul-editor-collab).
+ * Specification: docs/collaboration-protocol.md. Both sides parse with these schemas; neither
+ * defines its own message shapes.
+ *
+ * Typed bodies (`document`, `presentLocaleValues`, metadata payload values, form schemas) are
+ * protobuf or domain JSON validated by their owning modules after the envelope is accepted.
+ */
+import * as z from "zod/mini";
+import { editorRuntimeEventSchema } from "./runtime-events.ts";
+
+export const COLLABORATION_PROTOCOL_VERSION = 3 as const;
+/** Upper bound for a client control frame; bootstrap is the only large message and is server-sent. */
+export const MAX_CLIENT_CONTROL_MESSAGE_BYTES = 16 * 1024;
+/** `form.schema.patch` carries the previous and next full schemas, so it gets its own bound. */
+export const MAX_FORM_SCHEMA_PATCH_MESSAGE_BYTES = 1024 * 1024;
+
+/**
+ * Connection parameters naming the typed body a client already holds (the SSR read). Collab omits
+ * `room.bootstrap.document` only when both the revision and the body digest match its own body.
+ */
+export const KNOWN_DOCUMENT_REVISION_PARAM = "knownDocumentRevision";
+export const KNOWN_DOCUMENT_DIGEST_PARAM = "knownDocumentDigest";
+
+/**
+ * 64-bit non-cryptographic digest (cyrb64) of a typed body's protobuf binary. It only decides
+ * whether a body may be omitted; the client still verifies the Yjs update against the body it
+ * holds, so a collision costs a reconnect, never correctness.
+ */
+export function documentBodyDigest(bytes: Uint8Array): string {
+  let h1 = 0xdeadbeef ^ bytes.length;
+  let h2 = 0x41c6ce57 ^ bytes.length;
+  for (const byte of bytes) {
+    h1 = Math.imul(h1 ^ byte, 2654435761);
+    h2 = Math.imul(h2 ^ byte, 1597334677);
+  }
+  h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);
+  h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+  h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);
+  h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+  return (
+    (h2 >>> 0).toString(16).padStart(8, "0") +
+    (h1 >>> 0).toString(16).padStart(8, "0")
+  );
+}
+
+const v = z.literal(COLLABORATION_PROTOCOL_VERSION);
+const nonEmpty = z.string().check(z.trim(), z.minLength(1));
+const uuid = z.string().check(z.uuid());
+const base64 = z
+  .string()
+  .check(
+    z.regex(
+      /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u,
+    ),
+  );
+/** Opaque target-locale revision token issued by the API. */
+export const targetRevisionSchema = z
+  .string()
+  .check(
+    z.refine(
+      (value) => value.trim().length > 0,
+      "Target revision must be a nonblank opaque token.",
+    ),
+  );
+const json = z.unknown();
+
+export const blockRoomDocumentTypeSchema = z.enum([
+  "post",
+  "page",
+  "work",
+  "program-event",
+  "artist",
+  "label",
+  "release",
+  "campaign",
+  "email-template",
+  "terms-history",
+  "privacy-history",
+]);
+
+export const reloadReasonSchema = z.enum([
+  "deploy_or_restart",
+  "epoch_mismatch",
+  "external_update",
+  "conflict",
+  "permission",
+  "state_mismatch",
+]);
+export type ReloadReason = z.infer<typeof reloadReasonSchema>;
+
+export const accessEndedReasonSchema = z.enum([
+  "permission_revoked",
+  "session_expired",
+]);
+export type AccessEndedReason = z.infer<typeof accessEndedReasonSchema>;
+
+/**
+ * Reasons a refused admission is temporary (the Hocuspocus permission-denied frame carries the
+ * reason): the collab host is stopping or could not reach authorization. The client keeps its
+ * state and retries with backoff; any other unknown reason is not retried.
+ */
+export const admissionRetryReasonSchema = z.enum([
+  "service_stopping",
+  "authorization_unavailable",
+]);
+export type AdmissionRetryReason = z.infer<typeof admissionRetryReasonSchema>;
+
+export function isAdmissionRetryReason(
+  reason: string,
+): reason is AdmissionRetryReason {
+  return admissionRetryReasonSchema.safeParse(reason).success;
+}
+
+export const localeMetadataSchema = z.strictObject({
+  locale: nonEmpty,
+  title: z.optional(z.string()),
+  summary: z.optional(z.string()),
+  subject: z.optional(z.string()),
+  creditNotes: z.optional(
+    z.array(z.strictObject({ creditId: nonEmpty, note: z.string() })),
+  ),
+});
+export type LocaleMetadata = z.infer<typeof localeMetadataSchema>;
+
+export const metadataOperationSchema = z.enum([
+  "locale",
+  "document",
+  "page_layout",
+]);
+export type MetadataOperation = z.infer<typeof metadataOperationSchema>;
+
+export const metadataUpdateSchema = z.strictObject({
+  operation: metadataOperationSchema,
+  values: z.record(z.string(), json),
+  sequence: z.number().check(z.int(), z.positive()),
+});
+export type MetadataUpdate = z.infer<typeof metadataUpdateSchema>;
+
+export const metadataAckSchema = z.strictObject({
+  documentRevision: uuid,
+  targetRevision: z.optional(targetRevisionSchema),
+  changed: z.boolean(),
+  sourceChanged: z.boolean(),
+  changedLocales: z.array(z.string()),
+  locale: nonEmpty,
+  metadataUpdate: metadataUpdateSchema,
+});
+export type MetadataAck = z.infer<typeof metadataAckSchema>;
+
+/** Yjs coverage a durable save acknowledges: client clocks plus deleted ranges. */
+export const durabilityCoverageSchema = z.strictObject({
+  stateVector: base64,
+  deleted: z.record(
+    z.string().check(z.regex(/^\d+$/u)),
+    z.array(
+      z.strictObject({
+        clock: z.number().check(z.int(), z.nonnegative()),
+        len: z.number().check(z.int(), z.positive()),
+      }),
+    ),
+  ),
+});
+export type DurabilityCoverage = z.infer<typeof durabilityCoverageSchema>;
+
+export const roomRevisionSchema = z.strictObject({
+  documentRevision: uuid,
+  targetRevision: z.optional(targetRevisionSchema),
+  sourceLocale: nonEmpty,
+  locale: nonEmpty,
+  localeExists: z.boolean(),
+});
+export type RoomRevision = z.infer<typeof roomRevisionSchema>;
+
+export const protocolErrorSchema = z.strictObject({
+  code: nonEmpty,
+  message: z.optional(z.string()),
+  reloadReason: z.optional(reloadReasonSchema),
+  /**
+   * false: repeating the same request cannot succeed (permission, validation, missing entity), so
+   * the client stops retrying and keeps the intent as a recoverable backup. Absent means retryable.
+   */
+  retryable: z.optional(z.boolean()),
+});
+export type ProtocolError = z.infer<typeof protocolErrorSchema>;
+
+function result<
+  Kind extends string,
+  Value extends Record<string, z.core.$ZodType>,
+>(kind: Kind, value: Value) {
+  return z.discriminatedUnion("ok", [
+    z.strictObject({
+      v,
+      kind: z.literal(kind),
+      requestId: uuid,
+      ok: z.literal(true),
+      ...value,
+    }),
+    z.strictObject({
+      v,
+      kind: z.literal(kind),
+      requestId: uuid,
+      ok: z.literal(false),
+      error: protocolErrorSchema,
+    }),
+  ]);
+}
+
+// ---- Client → server -------------------------------------------------------------------------
+
+export const bootstrapAckSchema = z.strictObject({
+  v,
+  kind: z.literal("room.bootstrap_ack"),
+  challenge: nonEmpty,
+  stateVector: base64,
+});
+export const metadataRequestSchema = z.strictObject({
+  v,
+  kind: z.literal("room.metadata"),
+  requestId: uuid,
+  operation: metadataOperationSchema,
+  payload: json,
+});
+export const revisionRequestSchema = z.strictObject({
+  v,
+  kind: z.literal("room.revision"),
+  requestId: uuid,
+});
+export const flushRequestSchema = z.strictObject({
+  v,
+  kind: z.literal("room.flush"),
+  requestId: uuid,
+});
+export const formSchemaPatchRequestSchema = z.strictObject({
+  v,
+  kind: z.literal("form.schema.patch"),
+  requestId: uuid,
+  previousSchema: json,
+  nextSchema: json,
+});
+
+export const clientMessageSchema = z.discriminatedUnion("kind", [
+  bootstrapAckSchema,
+  metadataRequestSchema,
+  revisionRequestSchema,
+  flushRequestSchema,
+  formSchemaPatchRequestSchema,
+]);
+export type ClientMessage = z.infer<typeof clientMessageSchema>;
+
+// ---- Server → client -------------------------------------------------------------------------
+
+export const bootstrapSchema = z.strictObject({
+  v,
+  kind: z.literal("room.bootstrap"),
+  bootstrapChallenge: nonEmpty,
+  documentName: nonEmpty,
+  documentType: blockRoomDocumentTypeSchema,
+  /** Omitted when the connection's known revision and body digest match this body. */
+  document: z.optional(json),
+  documentRevision: uuid,
+  sourceLocale: nonEmpty,
+  locale: nonEmpty,
+  localeExists: z.boolean(),
+  targetRevision: z.optional(targetRevisionSchema),
+  presentLocaleValues: z.array(json),
+  sourceMetadata: localeMetadataSchema,
+  localeMetadata: z.optional(localeMetadataSchema),
+  documentMetadata: z.record(z.string(), json),
+  metadataSequence: z.number().check(z.int(), z.nonnegative()),
+  blockCatalogFingerprint: nonEmpty,
+  serverInstanceId: nonEmpty,
+  roomEpoch: uuid,
+  yjsBootstrapUpdate: base64,
+});
+export type BootstrapMessage = z.infer<typeof bootstrapSchema>;
+
+export const readySchema = z.strictObject({
+  v,
+  kind: z.literal("room.ready"),
+  bootstrapChallenge: nonEmpty,
+});
+export const metadataResultSchema = result("room.metadata_result", {
+  ack: metadataAckSchema,
+});
+export const revisionResultSchema = result("room.revision_result", {
+  revision: roomRevisionSchema,
+});
+export const flushResultSchema = result("room.flush_result", {
+  persisted: durabilityCoverageSchema,
+});
+export const formSchemaPatchResultSchema = result("form.schema.patch_result", {
+  canonicalSchema: json,
+});
+export const persistedSchema = z.strictObject({
+  v,
+  kind: z.literal("room.persisted"),
+  documentName: nonEmpty,
+  ...durabilityCoverageSchema.shape,
+});
+export const metadataChangedSchema = z.strictObject({
+  v,
+  kind: z.literal("room.metadata_changed"),
+  documentName: nonEmpty,
+  ack: metadataAckSchema,
+});
+export const formSchemaChangedSchema = z.strictObject({
+  v,
+  kind: z.literal("form.schema.changed"),
+  documentName: nonEmpty,
+  canonicalSchema: json,
+});
+export const reloadSchema = z.strictObject({
+  v,
+  kind: z.literal("room.reload"),
+  reloadReason: reloadReasonSchema,
+});
+/**
+ * The connection's access level changed while it stays open: `view` makes it read-only (edits are
+ * no longer accepted), `edit` restores editing. Access that ends entirely is `room.access_ended`.
+ */
+export const accessLevelSchema = z.enum(["view", "edit"]);
+export type AccessLevel = z.infer<typeof accessLevelSchema>;
+export const accessChangedSchema = z.strictObject({
+  v,
+  kind: z.literal("room.access_changed"),
+  access: accessLevelSchema,
+});
+export const accessEndedSchema = z.strictObject({
+  v,
+  kind: z.literal("room.access_ended"),
+  reason: accessEndedReasonSchema,
+});
+export const entityChangedSchema = z.strictObject({
+  v,
+  kind: z.literal("entity.changed"),
+  /** `{type}:{entityUUID}` of the resource. */
+  entity: nonEmpty,
+  scope: z.enum(["metadata", "document", "locale"]),
+  /** The authoritative document revision after the change. */
+  revision: z.optional(uuid),
+  locale: z.optional(nonEmpty),
+  /** Opaque per-tab write origin; never an authentication identity. */
+  origin: z.optional(nonEmpty),
+});
+export type EntityChangedMessage = z.infer<typeof entityChangedSchema>;
+export const interactiveMutationBeginSchema = z.strictObject({
+  v,
+  kind: z.literal("interactive_mutation.begin"),
+  mutationId: uuid,
+});
+export const interactiveMutationEndSchema = z.strictObject({
+  v,
+  kind: z.literal("interactive_mutation.end"),
+  mutationId: uuid,
+  outcome: z.enum(["accepted", "aborted"]),
+});
+
+/** Translation, OG, media and ingest status, carried unchanged inside the v3 envelope. */
+export const runtimeEventMessageSchema = z.strictObject({
+  v,
+  kind: z.literal("runtime.event"),
+  event: editorRuntimeEventSchema,
+});
+
+// The two-branch result unions are matched by kind before their `ok` discriminator.
+const serverSingleSchemas = [
+  bootstrapSchema,
+  readySchema,
+  persistedSchema,
+  metadataChangedSchema,
+  formSchemaChangedSchema,
+  reloadSchema,
+  accessChangedSchema,
+  accessEndedSchema,
+  entityChangedSchema,
+  interactiveMutationBeginSchema,
+  interactiveMutationEndSchema,
+  runtimeEventMessageSchema,
+] as const;
+const serverResultSchemas = {
+  "room.metadata_result": metadataResultSchema,
+  "room.revision_result": revisionResultSchema,
+  "room.flush_result": flushResultSchema,
+  "form.schema.patch_result": formSchemaPatchResultSchema,
+} as const;
+
+/** The result kind answering each client request kind. */
+const resultKindByRequestKind = new Map<
+  string,
+  keyof typeof serverResultSchemas
+>([
+  ["room.metadata", "room.metadata_result"],
+  ["room.revision", "room.revision_result"],
+  ["room.flush", "room.flush_result"],
+  ["form.schema.patch", "form.schema.patch_result"],
+]);
+
+export type ServerMessage =
+  | z.infer<(typeof serverSingleSchemas)[number]>
+  | z.infer<(typeof serverResultSchemas)[keyof typeof serverResultSchemas]>;
+export type ServerMessageKind = ServerMessage["kind"];
+export type ServerMessageOf<Kind extends ServerMessageKind> = Extract<
+  ServerMessage,
+  { kind: Kind }
+>;
+export type ClientMessageOf<Kind extends ClientMessage["kind"]> = Extract<
+  ClientMessage,
+  { kind: Kind }
+>;
+
+function kindOf(schema: { shape: { kind: z.ZodMiniLiteral<string> } }): string {
+  return schema.shape.kind.def.values[0] as string;
+}
+// Maps, not object literals: an inherited key such as "constructor" must not resolve to a schema.
+const serverSchemaByKind = new Map<string, z.ZodMiniType>([
+  ...serverSingleSchemas.map(
+    (schema) => [kindOf(schema), schema] as [string, z.ZodMiniType],
+  ),
+  ...Object.entries(serverResultSchemas),
+]);
+const clientMaxBytesByKind = new Map<string, number>([
+  [kindOf(bootstrapAckSchema), MAX_CLIENT_CONTROL_MESSAGE_BYTES],
+  [kindOf(metadataRequestSchema), MAX_CLIENT_CONTROL_MESSAGE_BYTES],
+  [kindOf(revisionRequestSchema), MAX_CLIENT_CONTROL_MESSAGE_BYTES],
+  [kindOf(flushRequestSchema), MAX_CLIENT_CONTROL_MESSAGE_BYTES],
+  [kindOf(formSchemaPatchRequestSchema), MAX_FORM_SCHEMA_PATCH_MESSAGE_BYTES],
+]);
+const MAX_ANY_CLIENT_CONTROL_MESSAGE_BYTES = Math.max(
+  ...clientMaxBytesByKind.values(),
+);
+
+/**
+ * `requestId` is present when a recognized request was rejected, so the receiver can answer it
+ * with a failed result (see `encodeRequestRejection`) instead of leaving the sender waiting.
+ */
+export type ParseFailure =
+  | { ok: false; reason: "invalid_json" | "not_an_object" }
+  | { ok: false; reason: "too_large"; kind?: string; requestId?: string }
+  | { ok: false; reason: "unsupported_version"; version: unknown }
+  | { ok: false; reason: "unknown_kind"; kind: unknown }
+  | {
+      ok: false;
+      reason: "invalid_shape";
+      kind: string;
+      issues: string;
+      requestId?: string;
+    };
+
+/** UTF-8 byte length, computed only when the UTF-16 length cannot already decide the bound. */
+function exceedsBytes(payload: string, maxBytes: number): boolean {
+  if (payload.length * 3 <= maxBytes) return false;
+  if (payload.length > maxBytes) return true;
+  return new TextEncoder().encode(payload).byteLength > maxBytes;
+}
+
+function requestIdOf(record: Record<string, unknown>): string | undefined {
+  return typeof record.requestId === "string" ? record.requestId : undefined;
+}
+
+function readEnvelope(
+  payload: string,
+  maxBytes?: number,
+): { ok: true; record: Record<string, unknown>; kind: unknown } | ParseFailure {
+  if (maxBytes !== undefined && exceedsBytes(payload, maxBytes)) {
+    return { ok: false, reason: "too_large" };
+  }
+  let value: unknown;
+  try {
+    value = JSON.parse(payload);
+  } catch {
+    return { ok: false, reason: "invalid_json" };
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return { ok: false, reason: "not_an_object" };
+  }
+  const record = value as Record<string, unknown>;
+  if (record.v !== COLLABORATION_PROTOCOL_VERSION) {
+    return { ok: false, reason: "unsupported_version", version: record.v };
+  }
+  return { ok: true, record, kind: record.kind };
+}
+
+function issues(error: z.core.$ZodError): string {
+  return error.issues
+    .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
+    .join("; ");
+}
+
+type ParseResult<Message> = { ok: true; message: Message } | ParseFailure;
+
+/**
+ * Several independent listeners receive every stateless frame (save tracking, runtime events,
+ * entity changes, ...). Remembering the last frame lets them share one parse of the same payload.
+ * Parsed messages are shared between listeners and must be treated as read-only.
+ */
+function lastPayloadMemo<Message>(
+  parse: (payload: string) => ParseResult<Message>,
+): (payload: string) => ParseResult<Message> {
+  let lastPayload: string | undefined;
+  let lastResult: ParseResult<Message> | undefined;
+  return (payload) => {
+    if (payload !== lastPayload || !lastResult) {
+      lastResult = parse(payload);
+      lastPayload = payload;
+    }
+    return lastResult;
+  };
+}
+
+/** Parse a client→server control frame. Never throws. */
+export const parseClientMessage = lastPayloadMemo(
+  (payload): ParseResult<ClientMessage> => {
+    const envelope = readEnvelope(
+      payload,
+      MAX_ANY_CLIENT_CONTROL_MESSAGE_BYTES,
+    );
+    if (!envelope.ok) return envelope;
+    const kind = envelope.kind;
+    const maxBytes =
+      typeof kind === "string" ? clientMaxBytesByKind.get(kind) : undefined;
+    if (maxBytes === undefined)
+      return { ok: false, reason: "unknown_kind", kind };
+    const requestId = requestIdOf(envelope.record);
+    if (exceedsBytes(payload, maxBytes)) {
+      return {
+        ok: false,
+        reason: "too_large",
+        kind: kind as string,
+        requestId,
+      };
+    }
+    const parsed = clientMessageSchema.safeParse(envelope.record);
+    if (parsed.success) return { ok: true, message: parsed.data };
+    return {
+      ok: false,
+      reason: "invalid_shape",
+      kind: kind as string,
+      issues: issues(parsed.error),
+      requestId,
+    };
+  },
+);
+
+/** Parse a server→client control frame. Never throws. */
+export const parseServerMessage = lastPayloadMemo(
+  (payload): ParseResult<ServerMessage> => {
+    const envelope = readEnvelope(payload);
+    if (!envelope.ok) return envelope;
+    const kind = envelope.kind;
+    const schema =
+      typeof kind === "string" ? serverSchemaByKind.get(kind) : undefined;
+    if (!schema) return { ok: false, reason: "unknown_kind", kind };
+    const parsed = schema.safeParse(envelope.record);
+    return parsed.success
+      ? { ok: true, message: parsed.data as ServerMessage }
+      : {
+          ok: false,
+          reason: "invalid_shape",
+          kind: kind as string,
+          issues: issues(parsed.error),
+        };
+  },
+);
+
+type Unversioned<Message> = Message extends unknown
+  ? Omit<Message, "v">
+  : never;
+
+/** Serialize a control frame, stamping the protocol version. */
+export function encodeMessage(
+  message: Unversioned<ClientMessage> | Unversioned<ServerMessage>,
+): string {
+  return JSON.stringify({ v: COLLABORATION_PROTOCOL_VERSION, ...message });
+}
+
+/**
+ * The failed result answering a rejected request, or undefined when the frame was not a
+ * recognizable request. The error code is the parse failure reason.
+ */
+export function encodeRequestRejection(
+  failure: ParseFailure,
+): string | undefined {
+  if (failure.reason !== "too_large" && failure.reason !== "invalid_shape")
+    return undefined;
+  const resultKind =
+    failure.kind === undefined
+      ? undefined
+      : resultKindByRequestKind.get(failure.kind);
+  const requestId = failure.requestId;
+  if (!resultKind || !requestId || !uuid.safeParse(requestId).success)
+    return undefined;
+  return encodeMessage({
+    kind: resultKind,
+    requestId,
+    ok: false,
+    error: { code: failure.reason, retryable: false },
+  });
+}
+
+/** Whether a client frame fits the bound the receiver enforces for its kind. */
+export function fitsClientMessageBound(
+  kind: ClientMessage["kind"],
+  payload: string,
+): boolean {
+  const maxBytes = clientMaxBytesByKind.get(kind);
+  return maxBytes !== undefined && !exceedsBytes(payload, maxBytes);
+}