Skip to content

Linger is An Open-Source Personal Agent That Runs Fully on Your PC. We aim to break Big Tech’s grip on AI by bringing powerful local AI to everyday computers through efficient model–harness co-design, so everyone can run their own.

24.2 KB
Raw Blame
import { isCanonicalBase64 } from "./base64.js";
import { timingSafeEqual } from "node:crypto";

import {
  ROOM_DOCUMENT_MAX_REFERENCES,
  type RoomDocumentSemanticBlock,
  type RoomDocumentSemanticOperation,
} from "@linger/document-model";
import {
  registerDocumentRuntimeRoutes,
  type DocumentRuntimeHandlers,
} from "@linger/wire-contracts/node-services-internal/server";
import type { components } from "@linger/wire-contracts/node-services-internal/types";
import { Hono } from "hono";

import type { DocumentComputation } from "./computation-pool.js";
import {
  DocumentNotFoundError,
  type ComputedDocumentChange,
  type DocumentChangeComputation,
  type DocumentChangeCoordinator,
} from "./document-changes.js";
import { exportDocument } from "./export.js";
import { documentLogger } from "./log.js";
import { isRecord } from "@linger/service-kit";
import { sha256Hex } from "@linger/service-kit/node";
import { RuntimeInputError, sha256Pattern } from "./runtime-input.js";

type ImportRequest = components["schemas"]["ImportDocumentRequest"];
type ApplyRequest = components["schemas"]["ApplyDocumentChangeRequest"];
type SemanticChange = components["schemas"]["SemanticDocumentChange"];
type InternalErrorCode = components["schemas"]["InternalErrorCode"];
type RuntimeContext = Parameters<DocumentRuntimeHandlers["importDocument"]>[0];

type DisconnectRequest =
  components["schemas"]["DisconnectDocumentConnectionsRequest"];

export interface DocumentRuntimeAppOptions {
  teamHubToken: string;
  // Applies TeamHub's server changes to the online bodies.
  changes?: DocumentChangeCoordinator;
  // Closes open connections after TeamHub committed a permission change.
  disconnect?: (documentId: string, actorId?: string) => void;
  computation: DocumentComputation;
}

export function createDocumentRuntimeApp(
  options: DocumentRuntimeAppOptions,
): Hono {
  if (options.teamHubToken.trim() === "") {
    throw new TypeError("Document Runtime TeamHub token is required");
  }
  const app = new Hono();

  app.get("/healthz", (context) => context.json({ status: "ok" }));
  // The Runtime holds no state TeamHub waits on, so a live process is ready.
  app.get("/readyz", (context) => context.json({ status: "ok" }));

  const handlers: DocumentRuntimeHandlers = {
    importDocument: (context) => importDocument(context, options.computation),
    exportDocument: (context) => exportDocument(context, options.computation),
    applyDocumentChange: options.changes
      ? (context) =>
          applyDocumentChange(context, options.changes!, options.computation)
      : notImplemented,
    disconnectDocumentConnections: options.disconnect
      ? (context) => disconnectDocumentConnections(context, options.disconnect!)
      : notImplemented,
    methodNotAllowed: (context) =>
      internalError(
        context,
        405,
        "invalid_request",
        "Document Runtime operation requires POST",
        false,
      ),
  };
  registerDocumentRuntimeRoutes(app, handlers, {
    authenticate: ({ token }) =>
      tokensEqual(token, options.teamHubToken) ? { subject: "teamhub" } : null,
  });

  return app;
}

async function disconnectDocumentConnections(
  context: Parameters<
    DocumentRuntimeHandlers["disconnectDocumentConnections"]
  >[0],
  disconnect: (documentId: string, actorId?: string) => void,
): Promise<Response> {
  const documentId = context.req.param("documentId") ?? "";
  let body: unknown;
  try {
    body = await context.req.json();
  } catch {
    body = undefined;
  }
  const actorId = isRecord(body)
    ? (body as DisconnectRequest).actor_id
    : undefined;
  if (
    !internalIDPattern.test(documentId) ||
    !isRecord(body) ||
    Object.keys(body).some((key) => key !== "actor_id") ||
    (actorId !== undefined &&
      (typeof actorId !== "string" || !internalIDPattern.test(actorId)))
  ) {
    return internalError(
      context,
      400,
      "invalid_request",
      "Document disconnect request is invalid",
      false,
    );
  }
  disconnect(documentId, actorId);
  return context.body(null, 204);
}

async function importDocument(
  context: RuntimeContext,
  computation: DocumentComputation,
): Promise<Response> {
  let body: unknown;
  try {
    body = await context.req.json();
  } catch {
    return internalError(
      context,
      400,
      "invalid_request",
      "Import request body must be valid JSON",
      false,
    );
  }
  try {
    const request = parseImportRequest(body);
    const sourceBytes =
      request.source_bytes === undefined
        ? undefined
        : decodeBase64(request.source_bytes);
    if (request.source_kind === "document_state") {
      const result = await computation.run("duplicateRoomDocumentState", {
        duplicateOperationId: request.operation_id,
        stateBytes: sourceBytes!,
        assetIdMap: Object.fromEntries(
          (request.asset_mappings ?? []).map((mapping) => [
            mapping.source_asset_id,
            mapping.target_asset_id,
          ]),
        ),
      });
      return context.json({
        state_bytes: Buffer.from(result.stateBytes).toString("base64"),
        bytes_sha256: result.stateBytesSha256,
        state_vector: Buffer.from(result.stateVector).toString("base64"),
        state_hash: result.stateHash,
        state_hash_version: result.stateHashVersion,
        complete_references: {
          document_asset_ids: result.completeReferences.documentAssetIds,
          document_thread_ids: result.completeReferences.documentThreadIds,
        },
        warnings: [],
      });
    }
    const computed = await computation.run("materializeRoomDocument", {
      materializationId: request.operation_id,
      schemaVersion: request.schema_version,
      sourceKind: request.source_kind,
      ...(sourceBytes === undefined ? {} : { sourceBytes }),
      allowedDocumentAssetIds: request.allowed_document_asset_ids ?? [],
    });
    return context.json({
      state_bytes: Buffer.from(computed.stateBytes).toString("base64"),
      bytes_sha256: computed.bytesSha256,
      state_vector: Buffer.from(computed.stateVector).toString("base64"),
      state_hash: computed.stateHash,
      state_hash_version: computed.stateHashVersion,
      complete_references: {
        document_asset_ids: computed.completeReferences.documentAssetIds,
        document_thread_ids: computed.completeReferences.documentThreadIds,
      },
      warnings: computed.warnings,
    });
  } catch (error) {
    return modelErrorResponse(context, error);
  }
}

const uuidPattern =
  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
const textSourceKinds = new Set(["markdown", "plain_text", "sanitized_html"]);

function parseImportRequest(value: unknown): ImportRequest {
  if (
    !isRecord(value) ||
    !hasOnlyKeys(value, [
      "operation_id",
      "schema_version",
      "source_kind",
      "source_bytes",
      "allowed_document_asset_ids",
      "asset_mappings",
    ]) ||
    typeof value.schema_version !== "number" ||
    !Number.isInteger(value.schema_version) ||
    (value.source_bytes !== undefined &&
      typeof value.source_bytes !== "string") ||
    (value.allowed_document_asset_ids !== undefined &&
      !isIDArray(
        value.allowed_document_asset_ids,
        ROOM_DOCUMENT_MAX_REFERENCES,
        true,
      ))
  ) {
    throw invalidRequest("Import request is invalid");
  }
  const kind = value.source_kind;
  if (kind === "document_state") {
    if (
      !isID(value.operation_id) ||
      value.source_bytes === undefined ||
      value.allowed_document_asset_ids !== undefined ||
      !Array.isArray(value.asset_mappings) ||
      value.asset_mappings.length > ROOM_DOCUMENT_MAX_REFERENCES
    ) {
      throw invalidRequest("Document state import is invalid");
    }
    const sourceIds = new Set<string>();
    const targetIds = new Set<string>();
    for (const mapping of value.asset_mappings) {
      if (
        !isRecord(mapping) ||
        !hasOnlyKeys(mapping, ["source_asset_id", "target_asset_id"]) ||
        !isID(mapping.source_asset_id) ||
        !isID(mapping.target_asset_id) ||
        sourceIds.has(mapping.source_asset_id) ||
        targetIds.has(mapping.target_asset_id)
      ) {
        throw invalidRequest(
          "Document state import Asset mappings are invalid",
        );
      }
      sourceIds.add(mapping.source_asset_id);
      targetIds.add(mapping.target_asset_id);
    }
    return value as unknown as ImportRequest;
  }
  if (
    (kind !== "blank" && !textSourceKinds.has(String(kind))) ||
    typeof value.operation_id !== "string" ||
    !uuidPattern.test(value.operation_id) ||
    value.asset_mappings !== undefined
  ) {
    throw invalidRequest("Import request is invalid");
  }
  return value as unknown as ImportRequest;
}

async function applyDocumentChange(
  context: Parameters<DocumentRuntimeHandlers["applyDocumentChange"]>[0],
  changes: DocumentChangeCoordinator,
  computation: DocumentComputation,
): Promise<Response> {
  let body: unknown;
  try {
    body = await context.req.json();
  } catch {
    return internalError(
      context,
      400,
      "invalid_request",
      "Document change body must be valid JSON",
      false,
    );
  }
  let request: ApplyRequest;
  let compute: DocumentChangeComputation;
  const documentId = context.req.param("documentId") ?? "";
  try {
    request = parseApplyRequest(documentId, body);
    compute = changeComputation(request, computation);
  } catch (error) {
    return modelErrorResponse(context, error);
  }
  try {
    const result = await changes.apply({
      documentId,
      operationId: request.operation_id,
      actorId: request.actor_id,
      ...(request.expected_seq === undefined
        ? {}
        : { expectedSeq: request.expected_seq }),
      compute,
    });
    if (result.status === "conflicted") {
      return context.json({ status: result.status, reason: result.reason });
    }
    return context.json({
      status: result.status,
      seq: result.seq,
      state_hash: result.stateHash,
      title: result.title,
      complete_references: {
        document_asset_ids: result.assetIds,
        document_thread_ids: result.threadIds,
      },
    });
  } catch (error) {
    if (error instanceof DocumentNotFoundError) {
      return internalError(context, 404, "not_found", error.message, false);
    }
    if (isDocumentModelError(error) || error instanceof RuntimeInputError) {
      return modelErrorResponse(context, error);
    }
    documentLogger().log("error", "document.change_failed", {
      document_id: documentId,
      message: error instanceof Error ? error.message : String(error),
    });
    return internalError(
      context,
      503,
      "runtime_unavailable",
      "The Document change was not applied",
      true,
    );
  }
}

function changeComputation(
  request: ApplyRequest,
  computation: DocumentComputation,
): DocumentChangeComputation {
  const change = request.change;
  switch (change.kind) {
    case "semantic":
      return async (stateBytes) => {
        const result = await computation.run(
          "applyRoomDocumentSemanticMutation",
          {
            mutationId: request.operation_id,
            schemaVersion: change.schema_version,
            currentTitle: change.current_title,
            stateBytes,
            allowedDocumentAssetIds: change.allowed_document_asset_ids,
            operations: semanticModelOperations(change.operations),
          },
        );
        if (result.status === "conflicted") return { conflict: result.reason };
        return computedChange(result, result.title);
      };
    case "restore": {
      const targetStateBytes = decodeBase64(change.target_state_bytes);
      if (sha256Hex(targetStateBytes) !== change.target_state_bytes_sha256) {
        throw invalidRequest(
          "History restore Revision bytes do not match their declared hash",
        );
      }
      return async (currentStateBytes) =>
        computedChange(
          await computation.run("restoreRoomDocumentRevision", {
            restoreOperationId: request.operation_id,
            currentStateBytes,
            targetStateBytes,
          }),
          "",
        );
    }
    case "comment_anchor":
      return async (stateBytes) =>
        computedChange(
          await computation.run("attachRoomDocumentCommentAnchor", {
            attachmentOperationId: request.operation_id,
            threadId: change.thread_id,
            stateBytes,
            quotedText: change.quoted_text,
            blockId: change.block_id,
            contextBefore: change.context_before,
            contextAfter: change.context_after,
          }),
          "",
        );
  }
}

function computedChange(
  result: {
    update: Uint8Array;
    stateBytes: Uint8Array;
    endStateVector: Uint8Array;
    completeReferences: {
      documentAssetIds: string[];
      documentThreadIds: string[];
    };
  },
  title: string,
): ComputedDocumentChange {
  return {
    update: result.update,
    stateBytes: result.stateBytes,
    stateVector: result.endStateVector,
    title,
    assetIds: result.completeReferences.documentAssetIds,
    threadIds: result.completeReferences.documentThreadIds,
  };
}

function parseApplyRequest(documentId: string, value: unknown): ApplyRequest {
  if (
    !isID(documentId) ||
    !isRecord(value) ||
    !hasOnlyKeys(value, [
      "operation_id",
      "actor_id",
      "expected_seq",
      "change",
    ]) ||
    !isID(value.operation_id) ||
    !isID(value.actor_id) ||
    (value.expected_seq !== undefined &&
      (typeof value.expected_seq !== "number" ||
        !Number.isSafeInteger(value.expected_seq) ||
        value.expected_seq < 0)) ||
    !isRecord(value.change)
  ) {
    throw invalidRequest("Document change request is invalid");
  }
  const change = value.change;
  switch (change.kind) {
    case "semantic":
      if (!isSemanticChange(change)) {
        throw invalidRequest("Semantic Document change is invalid");
      }
      break;
    case "restore":
      if (
        !hasOnlyKeys(change, [
          "kind",
          "target_state_bytes",
          "target_state_bytes_sha256",
        ]) ||
        typeof change.target_state_bytes !== "string" ||
        typeof change.target_state_bytes_sha256 !== "string" ||
        !sha256Pattern.test(change.target_state_bytes_sha256)
      ) {
        throw invalidRequest("History restore change is invalid");
      }
      break;
    case "comment_anchor":
      if (
        !hasOnlyKeys(change, [
          "kind",
          "thread_id",
          "quoted_text",
          "block_id",
          "context_before",
          "context_after",
        ]) ||
        !isID(change.thread_id) ||
        typeof change.quoted_text !== "string" ||
        change.quoted_text.trim() === "" ||
        Array.from(change.quoted_text).length > 10_000 ||
        !isID(change.block_id) ||
        typeof change.context_before !== "string" ||
        Array.from(change.context_before).length > 2_000 ||
        typeof change.context_after !== "string" ||
        Array.from(change.context_after).length > 2_000
      ) {
        throw invalidRequest("Comment anchor change is invalid");
      }
      break;
    default:
      throw invalidRequest("Document change kind is unsupported");
  }
  return value as unknown as ApplyRequest;
}

function isSemanticChange(value: Record<string, unknown>): boolean {
  return (
    hasOnlyKeys(value, [
      "kind",
      "schema_version",
      "current_title",
      "allowed_document_asset_ids",
      "operations",
    ]) &&
    value.schema_version === "blocknote-semantic-v1" &&
    isTitle(value.current_title) &&
    isIDArray(
      value.allowed_document_asset_ids,
      ROOM_DOCUMENT_MAX_REFERENCES,
      true,
    ) &&
    Array.isArray(value.operations) &&
    value.operations.length >= 1 &&
    value.operations.length <= 64 &&
    new TextEncoder().encode(JSON.stringify(value.operations)).byteLength <=
      (value.operations.some(
        (op: unknown) =>
          isRecord(op) &&
          (op.kind === "replace_body_html" ||
            op.kind === "replace_body_blocks"),
      )
        ? 8 << 20
        : 256 << 10) &&
    value.operations.every(isSemanticOperation)
  );
}

const internalIDPattern = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;

function isNativeEditOperation(value: Record<string, unknown>): boolean {
  const fields: Record<string, string[]> = {
    append: ["content"],
    str_replace: ["content", "pattern", "block_id"],
    block_insert_before: ["content", "block_id"],
    block_insert_after: ["content", "block_id"],
    block_replace: ["content", "block_id", "start_block_id", "end_block_id"],
    block_delete: ["block_id", "start_block_id", "end_block_id"],
    set_title: ["title"],
    image_insert_after: ["block_id", "asset_id", "caption"],
    image_replace: ["block_id", "asset_id", "caption"],
    file_insert_after: ["block_id", "asset_id", "name"],
  };
  const allowed =
    typeof value.command === "string" ? fields[value.command] : undefined;
  return (
    allowed !== undefined &&
    value.parser_version === "markdown-v1" &&
    hasOnlyKeys(value, ["kind", "parser_version", "command", ...allowed]) &&
    Object.entries(value).every(
      ([key, entry]) =>
        ["kind", "parser_version", "command"].includes(key) ||
        typeof entry === "string",
    )
  );
}

function isSemanticOperation(value: unknown): boolean {
  if (!isRecord(value) || typeof value.kind !== "string") return false;
  switch (value.kind) {
    case "edit_document":
      return isNativeEditOperation(value);
    case "replace_body_blocks":
      return (
        hasOnlyKeys(value, ["kind", "blocks"]) &&
        isBlockArray(value.blocks, true) &&
        Buffer.byteLength(JSON.stringify(value.blocks)) <= 1 << 20
      );
    case "replace_body_html":
      return (
        hasOnlyKeys(value, ["kind", "html"]) &&
        typeof value.html === "string" &&
        value.html.length > 0 &&
        Buffer.byteLength(value.html) <= 1 << 20
      );
    case "set_title":
      return hasOnlyKeys(value, ["kind", "title"]) && isTitle(value.title);
    case "append_blocks":
      return (
        hasOnlyKeys(value, ["kind", "blocks"]) &&
        isBlockArray(value.blocks, true)
      );
    case "insert_blocks":
      return (
        hasOnlyKeys(value, ["kind", "position", "stable_block_id", "blocks"]) &&
        (value.position === "before" || value.position === "after") &&
        isID(value.stable_block_id) &&
        isBlockArray(value.blocks, true)
      );
    case "replace_blocks":
      return (
        hasOnlyKeys(value, ["kind", "stable_block_ids", "blocks"]) &&
        isIDArray(value.stable_block_ids, 2048, false) &&
        value.stable_block_ids.length > 0 &&
        isBlockArray(value.blocks, false)
      );
    case "update_block":
      return (
        hasOnlyKeys(value, ["kind", "stable_block_id", "block"]) &&
        isID(value.stable_block_id) &&
        isRecord(value.block)
      );
    case "delete_blocks":
      return (
        hasOnlyKeys(value, ["kind", "stable_block_ids"]) &&
        isIDArray(value.stable_block_ids, 2048, false) &&
        value.stable_block_ids.length > 0
      );
    case "replace_comment_text":
      return (
        hasOnlyKeys(value, ["kind", "thread_id", "replacement"]) &&
        isID(value.thread_id) &&
        typeof value.replacement === "string" &&
        value.replacement.length >= 1 &&
        value.replacement.length <= 50_000
      );
    default:
      return false;
  }
}

function semanticModelOperations(
  operations: SemanticChange["operations"],
): RoomDocumentSemanticOperation[] {
  return operations.map((operation) => {
    const value = operation as unknown as Record<string, unknown>;
    switch (value.kind) {
      case "edit_document":
        return value as unknown as RoomDocumentSemanticOperation;
      case "replace_body_blocks":
        return {
          kind: "replace_body_blocks",
          blocks: value.blocks as RoomDocumentSemanticBlock[],
        };
      case "replace_body_html":
        return { kind: "replace_body_html", html: value.html as string };
      case "set_title":
        return { kind: "set_title", title: value.title as string };
      case "append_blocks":
        return {
          kind: "append_blocks",
          blocks: value.blocks as RoomDocumentSemanticBlock[],
        };
      case "insert_blocks":
        return {
          kind: "insert_blocks",
          position: value.position as "before" | "after",
          stableBlockId: value.stable_block_id as string,
          blocks: value.blocks as RoomDocumentSemanticBlock[],
        };
      case "replace_blocks":
        return {
          kind: "replace_blocks",
          stableBlockIds: value.stable_block_ids as string[],
          blocks: value.blocks as RoomDocumentSemanticBlock[],
        };
      case "update_block":
        return {
          kind: "update_block",
          stableBlockId: value.stable_block_id as string,
          block: value.block as RoomDocumentSemanticBlock,
        };
      case "delete_blocks":
        return {
          kind: "delete_blocks",
          stableBlockIds: value.stable_block_ids as string[],
        };
      case "replace_comment_text":
        return {
          kind: "replace_comment_text",
          threadId: value.thread_id as string,
          replacement: value.replacement as string,
        };
      default:
        throw invalidRequest("Semantic mutation operation is unsupported");
    }
  });
}

function isBlockArray(
  value: unknown,
  requireNonempty: boolean,
): value is Record<string, unknown>[] {
  return (
    Array.isArray(value) &&
    (!requireNonempty || value.length > 0) &&
    value.length <= 2048 &&
    value.every(isRecord)
  );
}

function isIDArray(
  value: unknown,
  maximum: number,
  unique: boolean,
): value is string[] {
  return (
    Array.isArray(value) &&
    value.length <= maximum &&
    value.every(isID) &&
    (!unique || new Set(value).size === value.length)
  );
}

function isID(value: unknown): value is string {
  return typeof value === "string" && internalIDPattern.test(value);
}

function isTitle(value: unknown): value is string {
  return typeof value === "string" && value.length >= 1 && value.length <= 255;
}

function hasOnlyKeys(value: Record<string, unknown>, keys: string[]): boolean {
  const allowed = new Set(keys);
  return Object.keys(value).every((key) => allowed.has(key));
}

function invalidRequest(message: string): RuntimeInputError {
  return new RuntimeInputError("validation_failed", message);
}

function decodeBase64(value: string): Uint8Array {
  const maxDecodedBytes = 32 << 20;
  const maxEncodedBytes = Math.ceil(maxDecodedBytes / 3) * 4;
  if (value.length > maxEncodedBytes || !isCanonicalBase64(value)) {
    throw new RuntimeInputError(
      "validation_failed",
      "Document source bytes must use canonical base64",
    );
  }
  const decoded = Buffer.from(value, "base64");
  if (decoded.byteLength > maxDecodedBytes) {
    throw new RuntimeInputError(
      "payload_too_large",
      "Document source exceeds 32 MiB",
    );
  }
  return decoded;
}

function tokensEqual(received: string, expected: string): boolean {
  const receivedBytes = Buffer.from(received);
  const expectedBytes = Buffer.from(expected);
  return (
    receivedBytes.byteLength === expectedBytes.byteLength &&
    timingSafeEqual(receivedBytes, expectedBytes)
  );
}

function notImplemented(context: RuntimeContext): Response {
  return internalError(
    context,
    501,
    "internal_error",
    "Document Runtime operation is not configured",
    false,
  );
}

function modelErrorResponse(context: RuntimeContext, error: unknown): Response {
  if (isDocumentModelError(error)) {
    const status = error.code === "payload_too_large" ? 413 : 422;
    return internalError(context, status, error.code, error.message, false);
  }
  return internalError(
    context,
    500,
    "internal_error",
    "Document Runtime computation failed",
    false,
  );
}

function isDocumentModelError(error: unknown): error is Error & {
  code: "payload_too_large" | "unsupported_document" | "validation_failed";
} {
  return (
    error instanceof Error &&
    "code" in error &&
    ["payload_too_large", "unsupported_document", "validation_failed"].includes(
      String(error.code),
    )
  );
}

function internalError(
  context: RuntimeContext,
  status: 400 | 404 | 405 | 413 | 422 | 500 | 501 | 503,
  code: InternalErrorCode,
  message: string,
  retryable: boolean,
): Response {
  return context.json({ code, message, retryable }, status);
}