Real-time collaboration: Add new REST endpoints, setting, and registered post meta #10894

chriszarate · 2026-02-10T06:31:41Z

Description

Trac ticket: https://core.trac.wordpress.org/ticket/64622

In Gutenberg, we have added support for real-time collaboration using CRDT documents (via the [https://yjs.dev/ Yjs library]). This work has suggested the following additions to WordPress:

A default "sync provider" based on HTTP polling that allows collaborators to share updates with each other. Previously, we relied on WebRTC connections between collaborators for this purpose, but it proved unreliable under many network conditions.
- Our solution is designed to work on any WordPress installation.
- HTTP polling is the transport we identified as most likely to work universally.
- Given the isolation and lifecycle of PHP processes, updates must be stored centrally in order to be shared among peers. We have chosen to store updates in post meta against a special post type, but alternate storage mechanisms are possible.
- Collaborative editing can involve syncing multiple CRDT documents. To limit the number of connections consumed by this provider, requests are batched.
- To prevent unbounded linear growth, updates are periodically compacted.
- To avoid excessive load on lower-resourced hosts, this provider will benefit from usage limits (e.g., a maximum of three connected collaborators) enforced by the client (Gutenberg).
A new registered post meta that allows Gutenberg to persist CRDT documents alongside posts.
- This provides all collaborators with a "shared starting point" for the collaborative session, which avoids duplicate updates.
- Content stored in the WordPress database always remains the source of truth. If the content differs from the persisted CRDT document, the CRDT document is updated to match the database.
A new Writing setting that allows users to opt-in to real-time collaboration.
- Enabling real-time collaboration disables post lock functionality and connects users to the sync provider.
A behavior change to autosaves is needed. When the the original author is editing a draft post (post_status == 'draft' OR 'auto-draft') and they hold the post lock, the autosave targets the actual post instead of an autosave revision. This puts the post data and the persisted CRDT document out of sync and leads to duplicate updates. When real-time collaboration is enabled, all collaborators must autosave in the same way.

This PR provides a proposed implementation of the changes above. This corresponding Gutenberg PR moves the work from the experimental directory to lib/compat:

WordPress/gutenberg#75366

Cumulative work to add this functionality can be found using this label:

https://github.com/WordPress/gutenberg/issues?q=label%3A%22%5BFeature%5D%20Real-time%20Collaboration%22%20is%3Apr

Testing instructions

Check out this branch and follow the setup instructions in the README.
Settings > Writing > Enable real-time collaboration.
Open a post for editing in two browsers / browser tabs.

github-actions · 2026-02-10T06:31:51Z

Hi @chriszarate! 👋

Thank you for your contribution to WordPress! 💖

It looks like this is your first pull request to wordpress-develop. Here are a few things to be aware of that may help you out!

No one monitors this repository for new pull requests. Pull requests must be attached to a Trac ticket to be considered for inclusion in WordPress Core. To attach a pull request to a Trac ticket, please include the ticket's full URL in your pull request description.

Pull requests are never merged on GitHub. The WordPress codebase continues to be managed through the SVN repository that this GitHub repository mirrors. Please feel free to open pull requests to work on any contribution you are making.

More information about how GitHub pull requests can be used to contribute to WordPress can be found in the Core Handbook.

Please include automated tests. Including tests in your pull request is one way to help your patch be considered faster. To learn about WordPress' test suites, visit the Automated Testing page in the handbook.

If you have not had a chance, please review the Contribute with Code page in the WordPress Core Handbook.

The Developer Hub also documents the various coding standards that are followed:

Thank you,
The WordPress Project

github-actions · 2026-02-10T15:41:13Z

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

The Plugin and Theme Directories cannot be accessed within Playground.
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.

pkevan · 2026-02-10T15:56:48Z

Is there any tests we can add for the default provider and new functionality?

pkevan · 2026-02-10T15:59:09Z

Can we also provide some documentation on how to override the provider given it's known limitation listed above?

pkevan · 2026-02-10T16:00:43Z

src/wp-includes/collaboration.php

+/**
+ * Injects the real-time collaboration setting into a global variable.
+ *
+ * @since 6.8.0


Suggested change

* @since 6.8.0

* @since 7.0.0

TimothyBJacobs

Why isn't each room a post?

TimothyBJacobs · 2026-02-10T15:50:37Z

src/wp-includes/collaboration.php

+ *
+ * @access private
+ */
+function wp_collaboration_register_meta() {


We have wp_create_initial_post_meta() for this instead.

Done in e2da144

TimothyBJacobs · 2026-02-10T15:51:56Z

src/wp-includes/collaboration/class-wp-sync-post-meta-storage.php

+	 *
+	 * @since 6.8.0
+	 */
+	public function init(): void {


Similarly, create_initial_post_types().

Done in 47fa660

TimothyBJacobs · 2026-02-10T15:55:12Z

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

+	 * @since 7.0.0
+	 * @var string
+	 */
+	const REST_NAMESPACE = 'wp/v2/sync';


Suggested change

const REST_NAMESPACE = 'wp/v2/sync';

const REST_NAMESPACE = 'wp-sync/v1';

We don't have namespaces off of wp/v2. A wp prefixed namespace matches what we do elsewhere in Core for more specialized endpoints.

Done in e6b39fb

TimothyBJacobs · 2026-02-10T15:56:05Z

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

+			if ( 2 !== count( $type_parts ) ) {
+				return new WP_Error(
+					'invalid_room_format',
+					'Invalid room format. Expected: entity_kind/entity_name or entity_kind/entity_name:id',


Missing translations.

Done in 0bb0022

TimothyBJacobs · 2026-02-10T15:56:48Z

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

+	 * @return bool|WP_Error True if user has permission, otherwise WP_Error with details.
+	 */
+	public function check_permissions( WP_REST_Request $request ) {
+		$rooms = $request->get_param( 'rooms' );


Suggested change

$rooms = $request->get_param( 'rooms' );

$rooms = $request['rooms'];

Core style is to use the array access notation.

Done in e4666c1

TimothyBJacobs · 2026-02-10T15:58:43Z

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

+	 * @param bool   $is_compactor True if this client is nominated to perform compaction.
+	 * @return array Response data for this room.
+	 */
+	private function get_updates_after( string $room, int $client_id, int $cursor, bool $is_compactor ): array {


This seems like it should be a responsibility of the storage layer. If I want to swap with something that can retrieve results ordered by time, we shouldn't have to load all updates always to do that.

I've updated the storage interface and class to take this approach in 9e5cf96. It was a little trickier than I thought, because compaction is an external concern and shouldn't be implemented by storage.

TimothyBJacobs · 2026-02-10T15:59:58Z

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

+	 * @param int    $cursor Remove updates with markers < this cursor.
+	 * @return bool True if this compaction is the latest, false if a newer compaction update exists.
+	 */
+	private function remove_updates_before_cursor( string $room, int $cursor ): bool {


Similarly here.

chriszarate · 2026-02-10T16:32:03Z

Why isn't each room a post?

No strong reason. Mostly to avoid creating a large number of posts. Each room corresponds to a synced CRDT document (representing a WordPress entity). Currently supported entity types:

posts (any post type)
taxonomy collections

In the future, this could be expanded to include all database entities, including individual taxonomy terms. We might also create rooms to share awareness data at the page or screen level.

We intend to enforce limits on this default provider, but probably applied to simultaneous collaborators and not on the overall number of synced entities. Sharing a single post felt prudent but happy to reconsider! I know wp_postmeta#meta_key is indexed but I don't have a grasp on the performance tradeoff at large scale.

westonruter · 2026-02-10T18:37:25Z

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

+			$object_id   = null;
+
+			if ( isset( $object_parts[1] ) ) {
+				$object_id = $object_parts[1];
+			}


Suggested change

$object_id = null;

if ( isset( $object_parts[1] ) ) {

$object_id = $object_parts[1];

}

$object_id = $object_parts[1] ?? null;

westonruter · 2026-02-10T18:40:30Z

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

+	 * @param int    $client_id    Client identifier.
+	 * @param int    $cursor       Return updates after this cursor.
+	 * @param bool   $is_compactor True if this client is nominated to perform compaction.
+	 * @return array Response data for this room.


Suggested change

* @return array Response data for this room.

* @return array<string, mixed> Response data for this room.

westonruter · 2026-02-10T18:41:42Z

src/wp-includes/collaboration/class-wp-sync-post-meta-storage.php

+	 * @since 6.8.0
+	 * @var int|null
+	 */
+	private static $storage_post_id = null;


Thanks to PHP 7.4:

Suggested change

private static $storage_post_id = null;

private static ?int $storage_post_id = null;

westonruter · 2026-02-10T18:43:10Z

src/wp-includes/collaboration/class-wp-sync-post-meta-storage.php

+ *
+ * Data is stored as post meta on a singleton post of a custom post type.
+ *
+ * @since 6.8.0


The @since versions need to be updated to 7.0.0 in this file.

westonruter · 2026-02-10T18:46:02Z

src/wp-includes/collaboration/class-wp-sync-post-meta-storage.php

+	 * @param string $room   Room identifier.
+	 * @param array  $update Sync update.


Suggested change

* @param string $room Room identifier.

* @param array $update Sync update.

* @param string $room Room identifier.

* @param array<string, mixed> $update Sync update.

westonruter · 2026-02-10T18:54:28Z

src/wp-includes/collaboration/class-wp-sync-post-meta-storage.php

+	 * @param string $room      Room identifier.
+	 * @param array  $awareness Merged awareness state.


Suggested change

* @param string $room Room identifier.

* @param array $awareness Merged awareness state.

* @param string $room Room identifier.

* @param array<int, array<string, mixed>> $awareness Merged awareness state.

westonruter · 2026-02-10T18:56:49Z

src/wp-includes/collaboration/class-wp-sync-post-meta-storage.php

+				'posts_per_page' => 1,
+				'post_status'    => 'publish',
+				'orderby'        => 'ID',
+				'order'          => 'ASC',


Suggested change

'order' => 'ASC',

'order' => 'ASC',

'fields' => 'ids',

westonruter · 2026-02-10T18:56:59Z

src/wp-includes/collaboration/class-wp-sync-post-meta-storage.php

+		if ( ! empty( $posts ) ) {
+			self::$storage_post_id = $posts[0]->ID;


Suggested change

if ( ! empty( $posts ) ) {

self::$storage_post_id = $posts[0]->ID;

$post_id = array_first( $posts );

if ( is_int( $post_id ) ) {

self::$storage_post_id = $post_id;

westonruter · 2026-02-10T18:57:53Z

src/wp-includes/collaboration/class-wp-sync-post-meta-storage.php

+			)
+		);
+
+		if ( ! is_wp_error( $post_id ) ) {


Same result, but PHPStan likes this more.

Suggested change

if ( ! is_wp_error( $post_id ) ) {

if ( is_int( $post_id ) ) {

westonruter · 2026-02-10T18:59:01Z

src/wp-includes/collaboration/class-wp-sync-post-meta-storage.php

+	 * @return int Post ID.
+	 */
+	private function get_storage_post_id(): int {


It could be that the wp_insert_post() fails. In that case, null is returned.

Suggested change

* @return int Post ID.

*/

private function get_storage_post_id(): int {

* @return int|null Post ID.

*/

private function get_storage_post_id(): ?int {

Thanks for all these! I believe I addressed them all in 0c5a7fd and 9e5cf96.

However, I decided to loosen the type for the actual sync update to mixed, because this data should be opaque to the storage mechanism (beyond serializability). Let me know if you have thoughts!

chriszarate added 5 commits February 10, 2026 00:56

Add setting to enable real-time collaboration

1fddb3a

Register collaboration post meta

9df00b1

Add sync provider endpoints

22278bf

Bugfix: When collaboration is enabled, always target autosave revision

0fda516

Update Gutenberg ref for testing

b62fbce

Merge branch 'trunk' into add/collaboration-functionality

928e470

pkevan reviewed Feb 10, 2026

View reviewed changes

TimothyBJacobs requested changes Feb 10, 2026

View reviewed changes

westonruter reviewed Feb 10, 2026

View reviewed changes

chriszarate added 8 commits February 10, 2026 18:01

Move post meta registration to wp_create_initial_post_meta

e2da144

Move post type registration to create_initial_post_types

47fa660

Update REST namespace to match convention

e6b39fb

Add localization

0bb0022

Use array property notation instead of get_param

e4666c1

Miscellaneous type fixes

0c5a7fd

Update Gutenberg ref

147f251

Update storage mechanism

9e5cf96

	const REST_NAMESPACE = 'wp/v2/sync';
	const REST_NAMESPACE = 'wp-sync/v1';

	$rooms = $request->get_param( 'rooms' );
	$rooms = $request['rooms'];

	* @return array Response data for this room.
	* @return array<string, mixed> Response data for this room.

	private static $storage_post_id = null;
	private static ?int $storage_post_id = null;

		* @param string $room Room identifier.
		* @param array $update Sync update.

		* @param string $room Room identifier.
		* @param array $awareness Merged awareness state.

		if ( ! empty( $posts ) ) {
		self::$storage_post_id = $posts[0]->ID;

-		if ( ! empty( $posts ) ) {
-			self::$storage_post_id = $posts[0]->ID;
+		$post_id = array_first( $posts );
+		if ( is_int( $post_id ) ) {
+			self::$storage_post_id = $post_id;

	if ( ! is_wp_error( $post_id ) ) {
	if ( is_int( $post_id ) ) {

Real-time collaboration: Add new REST endpoints, setting, and registered post meta #10894

Are you sure you want to change the base?

Real-time collaboration: Add new REST endpoints, setting, and registered post meta #10894

Uh oh!

Conversation

chriszarate commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Testing instructions

Uh oh!

github-actions bot commented Feb 10, 2026

Uh oh!

github-actions bot commented Feb 10, 2026

Test using WordPress Playground

Some things to be aware of

Uh oh!

pkevan commented Feb 10, 2026

Uh oh!

pkevan commented Feb 10, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

TimothyBJacobs left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chriszarate commented Feb 10, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chriszarate Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

chriszarate commented Feb 10, 2026 •

edited

Loading

chriszarate Feb 10, 2026 •

edited

Loading