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.

11.3 KB
Raw Blame
import { describe, expect, it, vi } from "vitest";
import * as Y from "yjs";

import {
  addCommentMarkToFirstText,
  appendToFirstText,
  connectRealtimeClient,
  memoryBodies,
  startRealtimeServer,
  wsUrl,
} from "./realtime-test-support.js";

type RealtimeClient = Awaited<ReturnType<typeof connectRealtimeClient>>;
interface CloseEvent {
  code: number;
  reason: string;
}

// The deadline tests wait for a held validation to time out; a short deadline
// proves the same close without waiting for the production default. The
// queue-full head's deadline starts before the test's window to queue 129
// frames (which takes about 10 ms), so it keeps a margin over that window.
const authorizationDeadlineMs = 1_000;
const queueFullWindowMs = 1_000;
const queueFullAuthorizationDeadlineMs = 1_500;

describe("Document Runtime mutation queue", () => {
  it("keeps one rapidly editing client connected across a transient autosave lock", async () => {
    const fixture = await createDelayedValidationFixture(1_250);
    let closeEvent: CloseEvent | undefined;
    let client: RealtimeClient | undefined;
    let expectedStateVector: string | undefined;
    let resolveCommitted!: () => void;
    const committed = new Promise<void>((resolve) => {
      resolveCommitted = resolve;
    });

    try {
      client = await connectRealtimeClient({
        token: "rapid_editor",
        url: wsUrl(fixture.realtime.address),
        onClose: (event) => {
          closeEvent = event;
        },
        onStateless: (payload) => {
          const envelope = JSON.parse(payload) as {
            head?: { persisted_seq?: number; state_vector?: string };
          };
          if (
            expectedStateVector !== undefined &&
            envelope.head?.state_vector === expectedStateVector
          )
            resolveCommitted();
        },
      });
      addCommentMarkToFirstText(client.document, "document_thread_rapid");
      for (let index = 1; index < 4; index += 1) {
        appendToFirstText(client.document, String(index % 10));
      }
      expectedStateVector = Buffer.from(
        Y.encodeStateVector(client.document),
      ).toString("base64");

      await Promise.race([
        committed,
        rejectAfter(8_000, "rapid mutation commit"),
      ]);
      expect(fixture.validateRequests).toHaveLength(1);
      expect(closeEvent).toBeUndefined();
    } finally {
      client?.provider.destroy();
      await fixture.realtime.destroy();
    }
  }, 10_000);

  it("keeps a healthy mutation connected when reference validation exceeds 250ms", async () => {
    const fixture = await createBlockedValidationFixture();
    let closeEvent: CloseEvent | undefined;
    let client: RealtimeClient | undefined;
    let resolveCommitted!: () => void;
    const committed = new Promise<void>((resolve) => {
      resolveCommitted = resolve;
    });

    try {
      client = await connectRealtimeClient({
        token: "healthy_delayed_permit",
        url: wsUrl(fixture.realtime.address),
        onClose: (event) => {
          closeEvent = event;
        },
        onStateless: (payload) => {
          const envelope = JSON.parse(payload) as {
            head?: { persisted_seq?: number };
          };
          if (envelope.head?.persisted_seq === 1) {
            resolveCommitted();
          }
        },
      });
      addCommentMarkToFirstText(client.document, "document_thread_delayed");
      await Promise.race([
        fixture.firstValidationObserved,
        rejectAfter(2_000, "delayed reference validation"),
      ]);

      await new Promise((resolve) => setTimeout(resolve, 350));
      expect(closeEvent).toBeUndefined();
      fixture.releaseFirstValidation();
      await Promise.race([
        committed,
        rejectAfter(2_000, "delayed mutation commit"),
      ]);
    } finally {
      fixture.releaseFirstValidation();
      client?.provider.destroy();
      await fixture.realtime.destroy();
    }
  });

  it("fails a queued mutation closed after its authorization deadline", async () => {
    const fixture = await createBlockedValidationFixture(
      authorizationDeadlineMs,
    );
    const clients: RealtimeClient[] = [];
    let activeClient: RealtimeClient | undefined;
    let queuedClient: RealtimeClient | undefined;
    let resolveActiveClose!: (event: CloseEvent) => void;
    const activeClose = new Promise<CloseEvent>((resolve) => {
      resolveActiveClose = resolve;
    });
    let resolveQueuedClose!: (event: CloseEvent) => void;
    const queuedClose = new Promise<CloseEvent>((resolve) => {
      resolveQueuedClose = resolve;
    });

    try {
      const realtimeUrl = wsUrl(fixture.realtime.address);
      activeClient = await connectRealtimeClient({
        token: "active",
        url: realtimeUrl,
        onClose: (event) => {
          resolveActiveClose(event);
          activeClient?.provider.destroy();
        },
      });
      clients.push(activeClient);
      queuedClient = await connectRealtimeClient({
        token: "queued",
        url: realtimeUrl,
        onClose: (event) => {
          resolveQueuedClose(event);
          queuedClient?.provider.destroy();
        },
      });
      clients.push(queuedClient);
      clients.push(
        await connectRealtimeClient({ token: "observer", url: realtimeUrl }),
      );
      const observerBefore = Y.encodeStateAsUpdate(clients[2]!.document);

      addCommentMarkToFirstText(clients[0]!.document, "document_thread_active");
      await Promise.race([
        fixture.firstValidationObserved,
        rejectAfter(2_000, "first reference validation"),
      ]);
      // A queued frame that adds a reference waits on the check too, so it
      // times out whether or not it reaches the head of the queue in time.
      addCommentMarkToFirstText(clients[1]!.document, "document_thread_queued");

      await expect(
        Promise.all([
          Promise.race([
            activeClose,
            rejectAfter(7_000, "active mutation close"),
          ]),
          Promise.race([
            queuedClose,
            rejectAfter(7_000, "queued mutation close"),
          ]),
        ]),
      ).resolves.toEqual([
        { code: 1000, reason: "Document mutation authorization timed out" },
        { code: 1000, reason: "Document mutation authorization timed out" },
      ]);
      expect(fixture.validateRequests.length).toBeGreaterThanOrEqual(1);
      expect(fixture.validateRequests.length).toBeLessThanOrEqual(2);
      expect(Y.encodeStateAsUpdate(clients[2]!.document)).toEqual(
        observerBefore,
      );
    } finally {
      fixture.releaseFirstValidation();
      for (const client of clients) {
        client.provider.destroy();
      }
      await fixture.realtime.destroy();
    }
  }, 9_000);

  it("fails closed when a Document already has 128 waiting mutations", async () => {
    const consoleError = vi
      .spyOn(console, "error")
      .mockImplementation(() => {});
    const fixture = await createBlockedValidationFixture(
      queueFullAuthorizationDeadlineMs,
    );
    const clients: RealtimeClient[] = [];
    const closeEvents: Array<CloseEvent | undefined> = [];
    let resolveQueueFull!: (result: {
      event: CloseEvent;
      index: number;
    }) => void;
    const queueFull = new Promise<{ event: CloseEvent; index: number }>(
      (resolve) => {
        resolveQueueFull = resolve;
      },
    );

    try {
      const realtimeUrl = wsUrl(fixture.realtime.address);
      const connected = await Promise.all(
        Array.from({ length: 130 }, async (_, index) =>
          connectRealtimeClient({
            token: `queue_${index}`,
            url: realtimeUrl,
            onClose: (event) => {
              closeEvents[index] = event;
              clients[index]?.provider.destroy();
              if (event.reason === "Document mutation queue is full") {
                resolveQueueFull({ event, index });
              }
            },
          }),
        ),
      );
      clients.push(...connected);
      const observer = await connectRealtimeClient({
        token: "queue_observer",
        url: realtimeUrl,
      });
      clients.push(observer);
      const observerBefore = Y.encodeStateAsUpdate(observer.document);

      addCommentMarkToFirstText(clients[0]!.document, "document_thread_active");
      await Promise.race([
        fixture.firstValidationObserved,
        rejectAfter(2_000, "first reference validation"),
      ]);
      for (let index = 1; index < 130; index += 1) {
        appendToFirstText(clients[index]!.document, ` queued_${index}`);
      }

      const rejected = await Promise.race([
        queueFull,
        rejectAfter(queueFullWindowMs, "queue-full close"),
      ]);
      expect(rejected.event).toEqual({
        code: 1000,
        reason: "Document mutation queue is full",
      });
      expect(rejected.index).toBeGreaterThan(0);
      expect(closeEvents.filter(Boolean)).toContainEqual(rejected.event);
      expect(fixture.validateRequests).toHaveLength(1);
      expect(Y.encodeStateAsUpdate(observer.document)).toEqual(observerBefore);
      // The held reference validation times out; a queued typing frame that
      // still has time left when the queue advances is admitted, because it
      // reads nothing from the database.
      await waitFor(
        () =>
          closeEvents[0]?.reason ===
          "Document mutation authorization timed out",
        "the held mutation to time out",
        7_000,
      );
    } finally {
      fixture.releaseFirstValidation();
      for (const client of clients) {
        client.provider.destroy();
      }
      await fixture.realtime.destroy();
      consoleError.mockRestore();
    }
  }, 12_000);
});

async function createBlockedValidationFixture(
  mutationAuthorizationDeadlineMs?: number,
) {
  const { bodies } = await memoryBodies();
  let observeFirstValidation!: () => void;
  const firstValidationObserved = new Promise<void>((resolve) => {
    observeFirstValidation = resolve;
  });
  let releaseFirstValidation!: () => void;
  const firstValidationRelease = new Promise<void>((resolve) => {
    releaseFirstValidation = resolve;
  });
  bodies.beforeCheckReferences = async () => {
    if (bodies.referenceChecks.length === 1) {
      observeFirstValidation();
    }
    await firstValidationRelease;
    return "available" as const;
  };
  const realtime = await startRealtimeServer(bodies, {
    mutationAuthorizationDeadlineMs,
  });
  return {
    firstValidationObserved,
    validateRequests: bodies.referenceChecks,
    realtime,
    releaseFirstValidation,
  };
}

async function createDelayedValidationFixture(delayMs: number) {
  const { bodies } = await memoryBodies();
  bodies.beforeCheckReferences = async () => {
    await new Promise((resolve) => setTimeout(resolve, delayMs));
    return "available" as const;
  };
  const realtime = await startRealtimeServer(bodies);
  return { validateRequests: bodies.referenceChecks, realtime };
}

function rejectAfter(milliseconds: number, operation: string): Promise<never> {
  return new Promise((_, reject) => {
    setTimeout(
      () => reject(new Error(`Timed out waiting for ${operation}`)),
      milliseconds,
    );
  });
}

async function waitFor(
  predicate: () => boolean,
  operation: string,
  timeoutMs = 2_000,
): Promise<void> {
  const deadline = Date.now() + timeoutMs;
  while (!predicate()) {
    if (Date.now() >= deadline) {
      throw new Error(`Timed out waiting for ${operation}`);
    }
    await new Promise((resolve) => setTimeout(resolve, 10));
  }
}