Collaboration: Replace post meta storage with dedicated database table by josephfusco · Pull Request #11256 · WordPress/wordpress-develop

josephfusco · 2026-03-14T21:06:01Z

The real-time collaboration sync layer currently stores messages as post meta, which creates side effects at scale. This moves it to a single dedicated wp_collaboration table purpose-built for the workload.

Table Definition

CREATE TABLE wp_collaboration (
  id bigint(20) unsigned NOT NULL auto_increment,
  room varchar(191) NOT NULL default '',
  type varchar(32) NOT NULL default '',
  client_id varchar(32) NOT NULL default '',
  user_id bigint(20) unsigned NOT NULL default '0',
  data longtext NOT NULL,
  date_gmt datetime NOT NULL default '0000-00-00 00:00:00',
  PRIMARY KEY  (id),
  KEY type_client_id (type, client_id),
  KEY room (room, id),
  KEY date_gmt (date_gmt)
);

Testing

npm run env:cli -- core update-db
npm run test:php -- --filter WP_Test_REST_Collaboration_Server
npm run test:e2e -- tests/e2e/specs/collaboration/

References

Trac ticket: https://core.trac.wordpress.org/ticket/64696
PR with prior work and feedback (2 table approach): #11068

Use of AI Tools

Co-authored with Claude Code (Opus 4.6), used to synthesize discussion across related tickets and PRs into a single implementation. All code was reviewed and tested before submission.

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

github-actions · 2026-03-14T21:13:18Z

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

All changes will be lost when closing a tab with a Playground instance.
All changes will be lost when refreshing the page.
A fresh instance is created each time the link below is clicked.
Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

Introduces the wp_collaboration table for storing real-time editing data (document states, awareness info, undo history) and the WP_Collaboration_Table_Storage class that implements all CRUD operations against it. Bumps the database schema version to 61840.

Replaces WP_HTTP_Polling_Sync_Server with WP_HTTP_Polling_Collaboration_Server using the wp-collaboration/v1 REST namespace. Switches to string-based client IDs, fixes the compaction race condition, adds a backward-compatible wp-sync/v1 route alias, and uses UPDATE-then-INSERT for awareness data.

Deletes WP_Sync_Post_Meta_Storage and WP_Sync_Storage interface, and removes the wp_sync_storage post type registration from post.php. These are superseded by the dedicated collaboration table.

Adds wp_is_collaboration_enabled() gate, injects the collaboration setting into the block editor, registers cron event for cleaning up stale collaboration data, and updates require/include paths for the new storage and server classes.

Adds 67 PHPUnit tests for WP_HTTP_Polling_Collaboration_Server covering document sync, awareness, undo/redo, compaction, permissions, cursor mechanics, race conditions, cron cleanup, and the backward-compatible wp-sync/v1 route. Adds E2E tests for 3-user presence, sync, and undo/redo. Removes the old sync server tests. Updates REST schema setup and fixtures for the new collaboration endpoints.

Adds a cache-first read path to get_awareness_state() following the transient pattern: check the persistent object cache, fall back to the database on miss, and prime the cache with the result. set_awareness_state() updates the cached entries in-place after the DB write rather than invalidating, so the cache stays warm for the next reader in the room. This is application-level deduplication: the shared collaboration table cannot carry a UNIQUE KEY on (room, client_id) because sync rows need multiple entries per room+client pair. Sites without a persistent cache see no behavior change — the in-memory WP_Object_Cache provides no cross-request benefit but keeps the code path identical.

Restore the `wp_client_side_media_processing_enabled` filter and the `finalize` route that were accidentally removed from the REST schema test. Add the `collaboration` table to the list of tables expected to be empty after multisite site creation.

The connectors API key entries in wp-api-generated.js were incorrectly carried over during the trunk merge. Trunk does not include them in the generated fixtures since the settings are dynamically registered and not present in the CI test context.

github-actions · 2026-03-16T20:12:01Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Core Committers: Use this line as a base for the props when committing in SVN:

Props joefusco, peterwilsoncc, czarate, paulkevan.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Rename the `update_value` column to `data` in the collaboration table storage class and tests, and fix array arrow alignment to satisfy PHPCS. The shorter name is consistent with WordPress meta tables and avoids confusion with the `update_value()` method in `WP_REST_Meta_Fields`.

Add a composite index on (type, client_id) to the collaboration table to speed up awareness upserts, which filter on both columns. Bump $wp_db_version from 61840 to 61841 so existing installations pick up the schema change via dbDelta on upgrade.

josephfusco · 2026-03-17T03:10:20Z

Carrying over props from original PR:

Props joefusco, peterwilsoncc, mindctrl, westonruter, paulkevan, dd32, czarate.

Introduce MAX_BODY_SIZE (16 MB), MAX_ROOMS_PER_REQUEST (50), and MAX_UPDATE_DATA_SIZE (1 MB) constants to cap request payloads. Wire a validate_callback on the route to reject oversized request bodies with a 413, add maxItems to the rooms schema, and replace the hardcoded maxLength with the new constant.

Reject non-numeric object IDs early in can_user_collaborate_on_entity_type(). Verify that a post's actual type matches the room's claimed entity name before granting access. For taxonomy rooms, confirm the term exists in the specified taxonomy and simplify the capability check to use assign_term with the term's object ID.

Cover oversized request body (413), exceeding max rooms (400), non-numeric object ID, post type mismatch, nonexistent taxonomy term, and term in the wrong taxonomy.

peterwilsoncc

A few notes from my first pass are inline. There will probably be more passes as I continuing reviewing the code and testing the functionality.

/* 
 * For multi-line comments the WordPress Coding Standard
 * is to write them like this rather than with consecutive lines
 * beginning with a `//`.
 *
 * This applies in a few places so I haven't dropped an inline comment.
 */

src/wp-includes/collaboration/class-wp-collaboration-table-storage.php

src/wp-includes/collaboration.php

src/wp-includes/collaboration/class-wp-collaboration-table-storage.php

src/wp-includes/collaboration/class-wp-http-polling-collaboration-server.php

src/wp-includes/collaboration.php

src/wp-admin/includes/schema.php

…rage Convert consecutive single-line comments to block comment style per WordPress coding standards, replace forward slashes with colons in cache keys to avoid ambiguity, hoist `global $wpdb` above the cache check in `get_awareness_state()`, and clarify the `$cursor` param docblock in `remove_updates_before_cursor()`.

When collaboration is disabled, run both DELETE queries (sync and awareness rows) before unscheduling the cron hook so leftover data is removed. Hoist `global $wpdb` to the top of the function so the disabled branch can use it. Add a comment noting future persistent types may also need exclusion from the sync cleanup query.

…d expand test coverage

The rooms array schema includes a maxItems constraint of 50, but the committed wp-api-generated.js fixture was missing it, causing git diff --exit-code to fail on every PHPUnit CI job.

…hrough_cursor The previous name was ambiguous — it suggested exclusive semantics, but the query uses inclusive deletion (id <= %d). "through" clearly communicates the inclusive behavior without needing to read the docblock.

peterwilsoncc

Added in a few more notes.

src/wp-includes/collaboration/class-wp-collaboration-table-storage.php

src/wp-includes/collaboration.php

src/wp-includes/collaboration/class-wp-collaboration-table-storage.php

Co-authored-by: Peter Wilson <519727+peterwilsoncc@users.noreply.github.com>

…rage.php Co-authored-by: Peter Wilson <519727+peterwilsoncc@users.noreply.github.com>

Co-authored-by: Peter Wilson <519727+peterwilsoncc@users.noreply.github.com>

…d option name

…e extensibility

…nario methods

…n fix

…ss cache

…ordpress-develop into collaboration/single-table

josephfusco changed the title ~~Collaboration: Replace post meta storage with dedicated database table - wp_collaboration~~ Collaboration: Replace post meta storage with dedicated database table Mar 14, 2026

josephfusco changed the title ~~Collaboration: Replace post meta storage with dedicated database table~~ Collaboration: Replace post meta storage with dedicated database table Mar 14, 2026

josephfusco force-pushed the collaboration/single-table branch from c08b703 to 693c813 Compare March 16, 2026 16:10

josephfusco added 5 commits March 16, 2026 13:02

Collaboration: Remove legacy post meta storage and post type

da8317c

Deletes WP_Sync_Post_Meta_Storage and WP_Sync_Storage interface, and removes the wp_sync_storage post type registration from post.php. These are superseded by the dedicated collaboration table.

josephfusco force-pushed the collaboration/single-table branch from 87fc57a to 886f0b1 Compare March 16, 2026 17:03

josephfusco added 3 commits March 16, 2026 13:25

josephfusco force-pushed the collaboration/single-table branch from 5140e44 to 09d0b86 Compare March 16, 2026 19:52

josephfusco marked this pull request as ready for review March 16, 2026 20:11

josephfusco mentioned this pull request Mar 16, 2026

Collaboration: Add dedicated database tables for real-time editing #11068

Closed

josephfusco added 2 commits March 16, 2026 22:09

josephfusco force-pushed the collaboration/single-table branch from 1a44948 to d4e27d4 Compare March 17, 2026 02:10

Merge branch 'trunk' into collaboration/single-table

ef00730

josephfusco added 3 commits March 16, 2026 23:11

Collaboration: Add tests for payload limits and permission hardening

cd4a69f

Cover oversized request body (413), exceeding max rooms (400), non-numeric object ID, post type mismatch, nonexistent taxonomy term, and term in the wrong taxonomy.

peterwilsoncc reviewed Mar 17, 2026

View reviewed changes

chriszarate reviewed Mar 17, 2026

View reviewed changes

src/wp-includes/collaboration.php Outdated Show resolved Hide resolved

chriszarate reviewed Mar 17, 2026

View reviewed changes

src/wp-admin/includes/schema.php Show resolved Hide resolved

josephfusco added 2 commits March 17, 2026 13:42

josephfusco and others added 7 commits March 17, 2026 23:41

Collaboration: Harden storage layer, fix duplicate awareness rows, an…

030bbce

…d expand test coverage

Collaboration: Add missing maxItems to REST schema fixture

a5d543d

The rooms array schema includes a maxItems constraint of 50, but the committed wp-api-generated.js fixture was missing it, causing git diff --exit-code to fail on every PHPUnit CI job.

Collaboration: Fix PHPCS alignment warnings in tests

45c639a

Collaboration: Fix REST schema fixture property order

0d3d425

Merge branch 'trunk' into collaboration/single-table

d812496

Merge branch 'trunk' into collaboration/single-table

20131ec

chriszarate mentioned this pull request Mar 18, 2026

Fix race condition in RTC default polling provider #11292

Closed

peterwilsoncc reviewed Mar 19, 2026

View reviewed changes

chriszarate mentioned this pull request Mar 19, 2026

Backport wp_collaboration table WordPress/gutenberg#76664

Open

josephfusco and others added 4 commits March 19, 2026 07:33

Apply suggestion from @peterwilsoncc

52fc395

Co-authored-by: Peter Wilson <519727+peterwilsoncc@users.noreply.github.com>

Update src/wp-includes/collaboration/class-wp-collaboration-table-sto…

1ef60f8

…rage.php Co-authored-by: Peter Wilson <519727+peterwilsoncc@users.noreply.github.com>

Update src/wp-includes/collaboration.php

a988544

Co-authored-by: Peter Wilson <519727+peterwilsoncc@users.noreply.github.com>

Collaboration: Merge upstream trunk and adopt wp_collaboration_enable…

1a61f33

…d option name

josephfusco requested a review from peterwilsoncc March 19, 2026 12:05

josephfusco and others added 9 commits March 19, 2026 08:10

Collaboration: Fix test setup for opt-in default

92fdc53

Collaboration: Add tests for cursor uniqueness, LIKE queries, and typ…

e7ac605

…e extensibility

Collaboration: Add HTTP method rejection and request validation tests

a53685f

Collaboration: Harden tests with exact assertions and split multi-sce…

b55f3ce

…nario methods

Collaboration: Fix PHPCS errors in tests

d4ea091

Collaboration: Merge upstream trunk including post meta race conditio…

6332302

…n fix

Merge branch 'trunk' into collaboration/single-table

cc24661

Merge branch 'trunk' into collaboration/single-table

0be5c73

Merge branch 'trunk' into collaboration/single-table

5f320b6

josephfusco added this to Headless OSS Mar 19, 2026

github-project-automation bot moved this to 🆕 Backlog in Headless OSS Mar 19, 2026

josephfusco and others added 4 commits March 19, 2026 19:56

Collaboration: Add test proving sync writes do not invalidate awarene…

7bd3079

…ss cache

Merge branch 'trunk' into collaboration/single-table

68f2a62

Collaboration: Bucket awareness timestamps to 5-second intervals

4ccf903

Merge branch 'collaboration/single-table' of github.com:josephfusco/w…

78ffe6f

…ordpress-develop into collaboration/single-table

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Collaboration: Replace post meta storage with dedicated database table#11256

Collaboration: Replace post meta storage with dedicated database table#11256
josephfusco wants to merge 46 commits intoWordPress:trunkfrom
josephfusco:collaboration/single-table

josephfusco commented Mar 14, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 14, 2026

Uh oh!

github-actions bot commented Mar 16, 2026 •

edited

Loading

Uh oh!

josephfusco commented Mar 17, 2026 •

edited

Loading

Uh oh!

peterwilsoncc left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

peterwilsoncc left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

josephfusco commented Mar 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Table Definition

Testing

References

Use of AI Tools

Uh oh!

github-actions bot commented Mar 14, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

github-actions bot commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

josephfusco commented Mar 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

peterwilsoncc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

peterwilsoncc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

josephfusco commented Mar 14, 2026 •

edited

Loading

github-actions bot commented Mar 16, 2026 •

edited

Loading

josephfusco commented Mar 17, 2026 •

edited

Loading