Code maintenance/STC-834: Bump Hocuspocus client & server to v4.2.0 (lockstep)

[akabiru]

Ticket

https://community.openproject.org/wp/STC-834

Server-side follow-up to the @hocuspocus/provider v4 client bump in #23570.

What are you trying to accomplish?

#23570 moves the frontend client @hocuspocus/provider to v4. The collaboration server in op-blocknote-hocuspocus was still on v3. The two talk over a versioned wire protocol and ship as independent artifacts — the server is the separately built openproject/hocuspocus image — so a one-major skew is tolerated, but the goal is to bring the server up to v4 as well so both halves run the current major.

This PR bumps @hocuspocus/server and @hocuspocus/extension-logger to v4 and applies the API changes the major introduces.

What v4 changes, and how it's applied here

v4 is a cross-runtime release that standardizes the server hook payloads on web-standard primitives and restructures a couple of hook shapes (v4.0.0 release notes, full diff). Three of those touch our OpenProjectApi extension:

• Request headers are now a web-standard Headers object — upgrade guide §2 Request and Headers (Breaking). onAuthenticate previously read the request origin off a plain object (data.request.headers.origin). v4 exposes it as Headers, accessed with .get():

  // before (v3)
  const requestOrigin = data.request?.headers?.origin;
  // after (v4)
  const requestOrigin = data.requestHeaders?.get("origin") ?? undefined;

  This matters beyond a rename: against v4 the old plain-object access would silently return undefined, quietly weakening the origin check passed to decryptAndValidateToken.

• The store hook's context is renamed context → lastContext — upgrade guide §3 onStoreDocument Payload (Breaking). onStoreDocument reads the resource URL, readonly flag, and token from the snapshot of the last connection context:

  // before (v3): data.context
  // after (v4):  data.lastContext
  const { resourceUrl, readonly } = data.lastContext;

• Broadcasting to connected clients goes through Document#broadcastStateless. In v4 Document.connections is a Map<Connection, { clients }>, so the old connections.forEach(({ connection }) => connection.sendStateless(...)) no longer typechecks. broadcastStateless is the supported helper for this (CHANGELOG, client-initiated broadcastStateless #1103):

  // before (v3)
  data.document.connections.forEach(({ connection }) => connection.sendStateless("storeEvent"));
  // after (v4)
  data.document.broadcastStateless("storeEvent");

The rest of the extension is unchanged: onTokenSync, connection.close({ code, reason }), connectionConfig.readOnly, and the ad-hoc context writes all compile and behave the same under v4. @hocuspocus/common resolves to v4 transitively; closeEvents.ts already uses the v4-narrowed { code, reason } CloseEvent shape (upgrade guide §11 CloseEvent Shape), so no change was needed there.

References

• v4.0.0 release notes & v3→v4 upgrade guide: https://github.com/ueberdosis/hocuspocus/releases/tag/v4.0.0
• Full changelog: https://github.com/ueberdosis/hocuspocus/blob/main/CHANGELOG.md
• v3.4.4 → v4.0.0 diff: ueberdosis/hocuspocus@v3.4.4...v4.0.0

A standing assertion of the client/server compatibility, plus a CI guard against future major drift, lands in the follow-up #23755.

Merge checklist

• Added/updated tests
• Added/updated documentation in Lookbook (n/a)
• Tested major browsers (live smoke test in Chrome)

[github-actions]

Warning

Flaky specs

• rspec ./modules/my_page/spec/features/my/work_package_table_spec.rb[1:1:1]

[github-actions]

Warning

Flaky specs

• rspec ./modules/wikis/spec/features/admin/internal_provider_spec.rb[1:1]
• rspec ./spec/features/projects/lists/filters_spec.rb[1:6:1]

[thykel]

@akabiru Looks like upstream is already on 4.2.0, do we want to follow that? (It contains some important-looking fixes.)

[akabiru]

@akabiru Looks like upstream is already on 4.2.0, do we want to follow that? (It contains some important-looking fixes.)

Yes, good catch @thykel 👍🏾

[Copilot]

Pull request overview

Aligns OpenProject’s collaborative editing stack by bumping both the frontend @hocuspocus/provider and the op-blocknote-hocuspocus server-side packages to Hocuspocus v4.2.0, and adapting the server extension hook payload changes introduced in v4.

Changes:

• Bump @hocuspocus/provider in the frontend to ^4.2.0 (with updated lockfile).
• Bump @hocuspocus/server and @hocuspocus/extension-logger in op-blocknote-hocuspocus to ^4.2.0 (with updated lockfile).
• Update OpenProjectApi extension to v4 hook payload shapes (requestHeaders, lastContext, broadcastStateless) and adjust unit tests accordingly.

Reviewed changes

Copilot reviewed 4 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
frontend/package.json	Bumps @hocuspocus/provider to v4.2.0.
frontend/package-lock.json	Updates resolved v4.2.0 provider/common dependencies and lock metadata.
extensions/op-blocknote-hocuspocus/src/extensions/openProjectApi.ts	Adapts server extension to Hocuspocus v4 hook payload API changes.
extensions/op-blocknote-hocuspocus/test/extensions/openProjectApi.test.ts	Updates unit tests to reflect v4 hook payload changes.
extensions/op-blocknote-hocuspocus/package.json	Bumps server-side Hocuspocus dependencies to v4.2.0.
extensions/op-blocknote-hocuspocus/package-lock.json	Updates resolved v4.2.0 server/common/logger dependencies and transitive graph.

Files not reviewed (2)

• extensions/op-blocknote-hocuspocus/package-lock.json: Generated file
• frontend/package-lock.json: Generated file

Comments suppressed due to low confidence (1)

extensions/op-blocknote-hocuspocus/src/extensions/openProjectApi.ts:110

• The warning message still refers to "context", but the hook payload was migrated to lastContext. This can be confusing when debugging stores (it will look like the old payload shape is still in use).

    const { resourceUrl, readonly } = data.lastContext;

    if (!resourceUrl) {
      console.warn("Missing parameters in context. Skipping store.");
      return;

[github-actions]

Warning

Flaky specs

• rspec ./modules/my_page/spec/features/my/work_package_table_spec.rb[1:1:1]