Add Hocuspocus provider/server wire-protocol integration test

The existing extension specs exercise the server hooks with a mocked API but
never a real client, so nothing proves the @hocuspocus/provider actually speaks
the wire protocol to the server. This boots the server in-process and connects a
real provider, asserting the connect/authenticate/load/sync handshake for both
the current and previous provider majors — making the one-major skew the
version-skew guard tolerates a standing assertion.

Author: akabiru

extensions/op-blocknote-hocuspocus/package-lock.json

@@ -33,13 +33,17 @@
     "@blocknote/core": "^0.51.3",
     "@eslint/js": "^9.35.0",
     "@eslint/json": "^1.2.0",
+    "@hocuspocus/provider": "^4.0.0",
+    "@hocuspocus/provider-prev": "npm:@hocuspocus/provider@^3",
     "@stylistic/eslint-plugin": "^5.3.1",
     "@types/node": "^25.0.2",
+    "@types/ws": "^8.18.1",
     "eslint": "^9.35.0",
     "globals": "^17.3.0",
     "msw": "^2.12.7",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.48.1",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.0",
+    "ws": "^8.18.3"
   }
 }

extensions/op-blocknote-hocuspocus/package.json

@@ -0,0 +1,74 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
+import { Server } from "@hocuspocus/server";
+import { HocuspocusProvider } from "@hocuspocus/provider";
+import { HocuspocusProvider as HocuspocusProviderPrev } from "@hocuspocus/provider-prev";
+import * as Y from "yjs";
+import { http, passthrough } from "msw";
+import { WebSocket } from "ws";
+import { OpenProjectApi } from "../../src/extensions/openProjectApi";
+import { createTestToken } from "../helpers/tokenHelper";
+import { server as apiMock } from "../mocks/node";
+
+// Proves a real @hocuspocus/provider completes the connect -> authenticate -> load ->
+// sync handshake against our server, exercising the actual wire protocol. The previous
+// provider major runs too, so the one-major skew the version-skew guard tolerates is a
+// standing assertion rather than a claim. The server boots in-process so the existing
+// msw mocks intercept its outbound Rails calls.
+const PORT = 9678;
+// Must equal the token's resource_url: onAuthenticate sets resourceUrl = documentName
+// and validates they match. createTestToken() defaults to this URL.
+const DOC_NAME = "https://test.api/api/v3/documents/1";
+
+let hocuspocus: Server;
+
+beforeAll(async () => {
+  hocuspocus = new Server({ port: PORT, quiet: true, extensions: [new OpenProjectApi()] });
+  await hocuspocus.listen();
+});
+
+afterAll(async () => {
+  await hocuspocus?.destroy();
+});
+
+beforeEach(() => {
+  // setup.ts runs msw with onUnhandledRequest:'error', which also intercepts the ws
+  // client's HTTP upgrade. Let the upgrade reach the in-process server; Rails calls to
+  // test.api stay mocked by the default handlers.
+  apiMock.use(http.all(/127\.0\.0\.1:9678/, () => passthrough()));
+});
+
+interface ProviderConfig {
+  url: string;
+  name: string;
+  token: string;
+  document: Y.Doc;
+  // The `ws` client, not the global WebSocket: msw patches the global and would drop
+  // the connection to our in-process server.
+  WebSocketPolyfill: typeof WebSocket;
+}
+interface ProviderInstance {
+  synced: boolean;
+  destroy(): void;
+}
+type ProviderConstructor = new (config: ProviderConfig) => ProviderInstance;
+
+const providerMajors: ReadonlyArray<readonly [string, ProviderConstructor]> = [
+  ["current", HocuspocusProvider as unknown as ProviderConstructor],
+  ["previous major", HocuspocusProviderPrev as unknown as ProviderConstructor],
+];
+
+describe.each(providerMajors)("@hocuspocus/provider (%s) <-> server", (_label, Provider) => {
+  it("connects, authenticates, and syncs", async () => {
+    const provider = new Provider({
+      url: `ws://127.0.0.1:${PORT}`,
+      name: DOC_NAME,
+      token: createTestToken(),
+      document: new Y.Doc(),
+      WebSocketPolyfill: WebSocket,
+    });
+
+    await expect.poll(() => provider.synced, { timeout: 10000 }).toBe(true);
+
+    provider.destroy();
+  });
+});