Skip to content

AI-native design editor. Open-source Figma alternative.

13.4 KB
Raw Blame
import { deflateSync, Inflate } from 'fflate'
import * as decoding from 'lib0/decoding'
import * as encoding from 'lib0/encoding'
import * as Y from 'yjs'

/** Where the relay accepts WebSocket upgrades, under the Cloud API origin. */
export const RELAY_PATH = '/api/collaboration/relay'

/**
 * The relay URL's query parameter naming the ticket's document, so a runtime that keeps each
 * document's room in its own place can route the socket there before the ticket arrives.
 */
export const RELAY_DOCUMENT_PARAM = 'document'

/** The relay's public URL on the same origin as the API, unless the deployment names another. */
export function defaultRelayURL(publicURL: string): string {
  const url = new URL(RELAY_PATH, publicURL)
  url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:'
  return url.href
}

/**
 * The room messages collaboration sends. The relay reads the document ones to keep its copy,
 * persist it, and drop writes from viewers; it forwards the rest unread.
 */
export const COLLAB_ACTIONS = {
  yjsUpdate: 'yjs-update',
  syncStep1: 'sync-step1',
  syncReply: 'sync-reply',
  awareness: 'awareness',
  agentPreview: 'agent-preview',
  upload: 'upload',
  /** From the server only: the document's version history changed, so open lists load it again. */
  versions: 'versions'
} as const

/**
 * The most a room message may decode to, compressed or not. A peer's update past it is dropped
 * before it is decoded, so a small compressed reply cannot expand without bound.
 */
export const MAX_COLLAB_MESSAGE_BYTES = 256 * 1024 * 1024

/**
 * What a peer joining needs is the whole document, which repeats the same field names across
 * every layer, so the reply to its state vector travels compressed; Yjs's V2 encoding already
 * groups that repetition, and together they make a room's first sync about a twelfth the size.
 * Edits travel as V2 updates uncompressed: they are small, and arrive in a stream.
 */
export function encodeSyncReply(document: Y.Doc, stateVector: Uint8Array): Uint8Array {
  return deflateSync(Y.encodeStateAsUpdateV2(document, stateVector))
}

/**
 * Compressed input is inflated this much at a time, so a reply stops within a step of passing
 * the limit: deflate expands at most about 1,032 times, so a step can overshoot by about 16 MB.
 */
const INFLATE_STEP = 16 * 1024

/**
 * The V2 update a peer sent, inflated first when `compressed`, as a sync reply is; null once it
 * would decode past `limit` bytes. Throws on data that does not inflate.
 */
export function decodeRoomUpdate(
  data: Uint8Array,
  { limit, compressed = false }: { limit: number; compressed?: boolean }
): Uint8Array | null {
  if (!compressed) return data.length <= limit ? data : null
  const chunks: Uint8Array[] = []
  let size = 0
  const inflate = new Inflate((chunk) => {
    size += chunk.length
    if (size <= limit) chunks.push(chunk)
  })
  for (let offset = 0; offset < data.length; offset += INFLATE_STEP) {
    inflate.push(data.subarray(offset, offset + INFLATE_STEP), offset + INFLATE_STEP >= data.length)
    if (size > limit) return null
  }
  const inflated = new Uint8Array(size)
  let at = 0
  for (const chunk of chunks) {
    inflated.set(chunk, at)
    at += chunk.length
  }
  return inflated
}

/** The peer ID the relay itself uses: it holds the room's document and answers sync requests. */
export const RELAY_SERVER_PEER = 'server'

/** The longest name a peer's presence may carry; peers drop presence with a longer one. */
export const MAX_PRESENCE_NAME_LENGTH = 40

/** A name as presence carries it: trimmed and cut to what every peer accepts. */
export function presenceName(name: string): string {
  return name.trim().slice(0, MAX_PRESENCE_NAME_LENGTH)
}

/**
 * Close codes in the WebSocket application range. A client reconnects with a fresh ticket after
 * `expired`, and gives up on the others.
 */
export const RELAY_CLOSE = {
  unauthorized: 4401,
  expired: 4403,
  roomFull: 4409,
  messageTooLarge: 4413,
  protocol: 4400,
  /** The document was restored to a version, so its room started over under a new ID. */
  restored: 4410
} as const

const CLIENT_AUTH = 0
const CLIENT_MESSAGE = 1
const CLIENT_FRAGMENT = 2
const SERVER_WELCOME = 0
const SERVER_JOIN = 1
const SERVER_LEAVE = 2
const SERVER_MESSAGE = 3
const SERVER_FRAGMENT = 4

/**
 * The most one WebSocket message carries. A frame past it travels as fragments of this size that
 * the receiver joins again, so a large paste or a room's first sync fits under any host's message
 * cap, such as the 32 MiB of Cloudflare Workers, and the relay can turn away a viewer's or an
 * unadmitted peer's large frame before holding it whole.
 */
export const RELAY_FRAGMENT_BYTES = 256 * 1024

/** The smallest per-message limit a relay may set: one fragment and its few bytes of framing. */
export const RELAY_MINIMUM_MESSAGE_BYTES = RELAY_FRAGMENT_BYTES + 16

/**
 * What the relay adds to a frame it forwards: the frame type, the sender's peer ID, and lengths.
 * A client reads frames this much past the relay's own limit, so a forwarded edit at that limit
 * still arrives.
 */
export const RELAY_FORWARDING_BYTES = 64 * 1024

/** Frames a client sends: its ticket first, again to refresh it, then room messages. */
export type RelayClientFrame =
  | { type: 'auth'; token: string }
  | { type: 'message'; namespace: string; target: string | null; payload: Uint8Array }

/** Frames the relay sends: who is in the room, arrivals and departures, and forwarded messages. */
export type RelayServerFrame =
  | { type: 'welcome'; peerId: string; peers: string[] }
  | { type: 'join'; peerId: string }
  | { type: 'leave'; peerId: string }
  | { type: 'message'; namespace: string; from: string; payload: Uint8Array }

/** Encodes into a buffer of its own, which `WebSocket.send` accepts. */
function toSendable(write: (encoder: encoding.Encoder) => void): Uint8Array<ArrayBuffer> {
  return new Uint8Array(encoding.encode(write))
}

export function encodeRelayClientFrame(frame: RelayClientFrame): Uint8Array<ArrayBuffer> {
  return toSendable((encoder) => {
    if (frame.type === 'auth') {
      encoding.writeVarUint(encoder, CLIENT_AUTH)
      encoding.writeVarString(encoder, frame.token)
      return
    }
    encoding.writeVarUint(encoder, CLIENT_MESSAGE)
    encoding.writeVarString(encoder, frame.namespace)
    encoding.writeVarString(encoder, frame.target ?? '')
    encoding.writeVarUint8Array(encoder, frame.payload)
  })
}

export function encodeRelayServerFrame(frame: RelayServerFrame): Uint8Array<ArrayBuffer> {
  return toSendable((encoder) => {
    switch (frame.type) {
      case 'welcome':
        encoding.writeVarUint(encoder, SERVER_WELCOME)
        encoding.writeVarString(encoder, frame.peerId)
        encoding.writeVarUint(encoder, frame.peers.length)
        for (const peer of frame.peers) encoding.writeVarString(encoder, peer)
        return
      case 'join':
      case 'leave':
        encoding.writeVarUint(encoder, frame.type === 'join' ? SERVER_JOIN : SERVER_LEAVE)
        encoding.writeVarString(encoder, frame.peerId)
        return
      case 'message':
        encoding.writeVarUint(encoder, SERVER_MESSAGE)
        encoding.writeVarString(encoder, frame.namespace)
        encoding.writeVarString(encoder, frame.from)
        encoding.writeVarUint8Array(encoder, frame.payload)
    }
  })
}

/** The frame as it goes over the socket: itself, or fragments of it when it is large. */
function fragments(tag: number, frame: Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer>[] {
  if (frame.byteLength <= RELAY_FRAGMENT_BYTES) return [frame]
  const parts: Uint8Array<ArrayBuffer>[] = []
  for (let offset = 0; offset < frame.byteLength; offset += RELAY_FRAGMENT_BYTES) {
    const end = Math.min(offset + RELAY_FRAGMENT_BYTES, frame.byteLength)
    parts.push(
      toSendable((encoder) => {
        encoding.writeVarUint(encoder, tag)
        encoding.writeVarUint(encoder, end < frame.byteLength ? 1 : 0)
        encoding.writeVarUint8Array(encoder, frame.subarray(offset, end))
      })
    )
  }
  return parts
}

/** A client frame as the socket messages that carry it, in order. */
export function relayClientMessages(frame: RelayClientFrame): Uint8Array<ArrayBuffer>[] {
  return fragments(CLIENT_FRAGMENT, encodeRelayClientFrame(frame))
}

/** A server frame as the socket messages that carry it, in order. */
export function relayServerMessages(frame: RelayServerFrame): Uint8Array<ArrayBuffer>[] {
  return fragments(SERVER_FRAGMENT, encodeRelayServerFrame(frame))
}

/** What one socket message gave: a whole frame, part of one, or a reason to close. */
export type RelayAssembly =
  | { type: 'frame'; data: Uint8Array }
  | { type: 'partial' }
  | { type: 'too-large' }
  | { type: 'malformed' }

/**
 * Joins one socket's fragments into the frames they carry. A socket sends a frame's fragments in
 * a row, so a whole frame arriving between them is malformed. `limit` caps the joined frame and is
 * read for every message, so it can follow what the sender may do.
 */
function createAssembler(tag: number, limit: () => number) {
  let parts: Uint8Array[] = []
  let size = 0
  /** Set while the rest of a refused frame arrives, so its tail never reads as a frame of its own. */
  let discarding = false
  const reset = () => {
    parts = []
    size = 0
  }
  return {
    push(data: Uint8Array): RelayAssembly {
      let decoder: decoding.Decoder
      let type: number
      try {
        decoder = decoding.createDecoder(data)
        type = decoding.readVarUint(decoder)
      } catch {
        reset()
        return { type: 'malformed' }
      }
      if (type !== tag) {
        if (parts.length > 0) {
          reset()
          return { type: 'malformed' }
        }
        return { type: 'frame', data }
      }
      let more: number
      let chunk: Uint8Array
      try {
        more = decoding.readVarUint(decoder)
        chunk = decoding.readVarUint8Array(decoder)
      } catch {
        // A fragment that cannot be read is taken as unfinished: only a sound last one ends it.
        reset()
        discarding = true
        return { type: 'malformed' }
      }
      if (decoder.pos !== data.byteLength || more > 1) {
        reset()
        discarding = more !== 0
        return { type: 'malformed' }
      }
      if (discarding) {
        discarding = more === 1
        return { type: 'partial' }
      }
      size += chunk.byteLength
      if (size > limit()) {
        reset()
        discarding = more === 1
        return { type: 'too-large' }
      }
      parts.push(chunk.slice())
      if (more === 1) return { type: 'partial' }
      const joined = new Uint8Array(size)
      let at = 0
      for (const part of parts) {
        joined.set(part, at)
        at += part.byteLength
      }
      reset()
      return { type: 'frame', data: joined }
    }
  }
}

/** Joins the fragments a client sends; the relay holds one per socket. */
export function createRelayClientAssembler(limit: () => number) {
  return createAssembler(CLIENT_FRAGMENT, limit)
}

/** Joins the fragments the relay sends; a client holds one per socket. */
export function createRelayServerAssembler(limit: () => number) {
  return createAssembler(SERVER_FRAGMENT, limit)
}

/**
 * lib0 reads byte arrays as views of the underlying buffer, which can run past the end of the
 * frame's own view, as with pooled socket buffers. A frame is valid only when decoding consumed
 * exactly its bytes, and payloads are copied out of the shared buffer.
 */
function complete<T>(decoder: decoding.Decoder, data: Uint8Array, frame: T): T | null {
  return decoder.pos === data.byteLength ? frame : null
}

function readPayload(decoder: decoding.Decoder): Uint8Array {
  return decoding.readVarUint8Array(decoder).slice()
}

/** Returns null for a frame that is malformed or of an unknown type. */
export function decodeRelayClientFrame(data: Uint8Array): RelayClientFrame | null {
  try {
    const decoder = decoding.createDecoder(data)
    const type = decoding.readVarUint(decoder)
    if (type === CLIENT_AUTH) {
      return complete(decoder, data, { type: 'auth', token: decoding.readVarString(decoder) })
    }
    if (type !== CLIENT_MESSAGE) return null
    const namespace = decoding.readVarString(decoder)
    const target = decoding.readVarString(decoder)
    const payload = readPayload(decoder)
    return complete(decoder, data, { type: 'message', namespace, target: target || null, payload })
  } catch {
    return null
  }
}

/** Returns null for a frame that is malformed or of an unknown type. */
export function decodeRelayServerFrame(data: Uint8Array): RelayServerFrame | null {
  try {
    const decoder = decoding.createDecoder(data)
    switch (decoding.readVarUint(decoder)) {
      case SERVER_WELCOME: {
        const peerId = decoding.readVarString(decoder)
        const count = decoding.readVarUint(decoder)
        const peers: string[] = []
        for (let index = 0; index < count; index++) peers.push(decoding.readVarString(decoder))
        return complete(decoder, data, { type: 'welcome', peerId, peers })
      }
      case SERVER_JOIN:
        return complete(decoder, data, { type: 'join', peerId: decoding.readVarString(decoder) })
      case SERVER_LEAVE:
        return complete(decoder, data, { type: 'leave', peerId: decoding.readVarString(decoder) })
      case SERVER_MESSAGE: {
        const namespace = decoding.readVarString(decoder)
        const from = decoding.readVarString(decoder)
        const payload = readPayload(decoder)
        return complete(decoder, data, { type: 'message', namespace, from, payload })
      }
      default:
        return null
    }
  } catch {
    return null
  }
}