WordPress 7.0 will introduce real-time collaboration in the blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. editor. Out of the box, the editor syncs changes between peers using an HTTPHTTP HTTP is an acronym for Hyper Text Transfer Protocol. HTTP is the underlying protocol used by the World Wide Web and this protocol defines how messages are formatted and transmitted, and what actions Web servers and browsers should take in response to various commands. polling provider. However, an HTTP polling transport isn’t the only option and it may not be the best fit for your infrastructure, especially if you are a WordPress hosting provider.

The sync.providers client-side filterFilter Filters are one of the two types of Hooks https://codex.wordpress.org/Plugin_API/Hooks. They provide a way for functions to modify data of other functions. They are the counterpart to Actions. Unlike Actions, filters are meant to work in an isolated manner, and should never have side effects such as affecting global variables and output. proposed for WordPress 7.0 lets you replace the default transport with your own. This post walks through why you’d want to use one, what a provider does, and how to build one.

Why build a custom provider?

The default HTTP polling provider is designed to work on any WordPress installation. It batches document and awareness updates into periodic HTTP requests: every four seconds when editing alone, every second when collaborators are present. (These values are filterable.)

It works reliably, but there can be good reasons to swap it out:

• Lower latency. Transports such as WebSockets deliver updates as they happen, not on a polling interval. For sites doing heavy collaborative editing, the difference can be noticeable.
• Reduced server load. Polling generates requests even when nothing has changed. A push-based transport only sends data when needed.
• Infrastructure alignment. If you already run WebSocket servers or other real-time transport, you can benefit from using familiar infrastructure with WordPress.

These benefits come with a substantial overhead. Building a custom provider is not trivial. It will require custom code. Most likely, it will also involve deployingDeploy Launching code from a local development environment to the production web server, so that it's available to visitors. and maintaining server resources.

What a sync provider does

Real-time collaboration in WordPress is powered by Yjs, a Conflictconflict A conflict occurs when a patch changes code that was modified after the patch was created. These patches are considered stale, and will require a refresh of the changes before it can be applied, or the conflicts will need to be resolved.-free Replicated Data Type (CRDT) library. WordPress content is represented by Yjs documents; syncing happens by exchanging updates to those documents.

The sync provider is the transport layer. It facilitates the exchange of Yjs document updates between peers.

Concretely, a provider needs to:

1. Receive local Yjs document updates and send them to remote peers.
2. Receive remote updates and apply them to the local Yjs document.
3. Report connection status so the editor UIUI User interface can show whether the user is connected.

GutenbergGutenberg The Gutenberg project is the new Editor Interface for WordPress. The editor improves the process and experience of creating new content, making writing rich content much simpler. It uses ‘blocks’ to add richness rather than shortcodes, custom HTML etc. https://wordpress.org/gutenberg/’s sync manager orchestrates the syncing process. It creates a sync provider for each Yjs document that will be synced. Therefore, supplying a custom sync provider means supplying a provider creator function. A provider creator is an async function following this example:

async function myProviderCreator( options ) {
    const objectType = options.objectType; // e.g., "postType/post"
    const objectId   = options.objectId;   // e.g., "123"
    const ydoc       = options.ydoc;       // Yjs document
    const awareness  = options.awareness;  // Yjs awareness

    // Create provider.
    const room     = `${ objectType }:${ objectId }`;
    const provider = new MyYjsProvider( ydoc, awareness, room );

    // Connect.
    provider.connect();

    return {
        destroy: () => provider.destroy(),
        on: ( event, callback ) => provider.on( event, callback ),
     };
}

Note that the returned object has two function properties that the provider must implement:

• destroy(): The sync manager will call this function when it is time to close connections, remove listeners, and free resources.
• on(): This function allows the sync manager to subscribe to connection state changes. Emit { status: 'connecting' }, { status: 'connected' }, or { status: 'disconnected', error?: ConnectionError } as appropriate.
  • A disconnected event can be accompanied by an error. Using specific error codes allows the editor to give specific feedback to the user. See the list of error codes and resulting messaging.

Existing Yjs providers

You don’t have to build a sync provider from scratch. Yjs has a provider ecosystem and several existing libraries can handle the heavy lifting. 

y-websocket is the most widely used Yjs provider and has been deployedDeploy Launching code from a local development environment to the production web server, so that it's available to visitors. by WordPress VIP and other WordPress hosts. It includes both a client and a simple Node.js server.

Note: y-webrtc is nominally a peer-to-peer provider that syncs via WebRTC, but in practice it requires centralized servers to reliably connect peers with each other. It is not recommended unless you are willing to invest in those servers. 

Minimal client example with y-websocket

Wrapping a Yjs provider in a ProviderCreator function is straightforward, as seen in the following example. However, note that this example is missing essential authorization checks (discussed in the next section):

import { addFilter } from '@wordpress/hooks';
import { WebsocketProvider } from 'y-websocket';

addFilter( 'sync.providers', 'my-plugin/websocket', () => {
    return [
        async ( { objectType, objectId, ydoc, awareness } ) => {
            const roomName = `${ objectType }-${ objectId ?? 'collection' }`;
            const provider = new WebsocketProvider(
                'wss://my-sync-server.example.com',
                roomName,
                ydoc,
                { awareness }
            );

            return {
                destroy: () => provider.destroy(),
                on: ( event, callback ) => provider.on( event, callback ),
            };
        },
    ];
} );

This code replaces the default HTTP polling provider entirely. The filter callback ignores the incoming providerCreators array and returns a new array containing a single WebSocket-based provider creator.

The WebSocket server (wss://my-sync-server.example.com in the example above) must be configured and deployed separately. The y-websocket-server library is the server companion to y-websocket.

Authorization and security

A custom sync provider connects to infrastructure that you own and operate, e.g., a WebSocket server. Because that infrastructure lives outside of WordPress, WordPress can’t authorize requests to it on your behalf.

Securing the connection between the editor and your sync server is your responsibility—a critical one. Without authorization checks, any user could connect to your WebSocket server and participate in a collaborative session with your WordPress users. 

Token-based auth

A common pattern is to issue short-lived tokens via a WordPress REST APIREST API The REST API is an acronym for the RESTful Application Program Interface (API) that uses HTTP requests to GET, PUT, POST and DELETE data. It is how the front end of an application (think “phone app” or “website”) can communicate with the data store (think “database” or “file system”) https://developer.wordpress.org/rest-api/ endpoint, then pass the token when opening the WebSocket connection. The tokens assert that the user has permission to collaborate on a specific entity.

Here’s a simplified example of how the WPVIP Real-Time Collaboration plugin handles it:

// Fetch a short-lived token from a WordPress REST endpoint.
// This endpoint is provided by your plugin. Tokens encode the
// type and ID of the entity being edited, as well as the current
// WordPress user ID.
const data = await apiFetch( {
    path: '/my-plugin/v1/sync/auth',
    method: 'GET',
    data: { objectType, objectId },
} );

// Pass the token as a query parameter when connecting.
provider.params = { auth: data.token };
provider.connect();

Key considerations

• Validate on the server. Never trust the client. The sync server should verify the token on every connection request. The token should encode information about the user, the entity being edited, and which actions are authorized. The sync server should validate each assertion and reject unauthorized connections before applying any document updates.
• Authorize per-document. It’s worth restating: Don’t just authenticate the user, additionally verify they have permission to edit the specific post or entity being synced. Your WebSocket server should validate this on every connection.
• Rotate tokens. WebSocket connections are long-lived. Use short-lived tokens and re-authenticate on reconnect so that revoked permissions take effect promptly.
• Handle disconnects gracefully. When authorization fails or a token is invalidinvalid A resolution on the bug tracker (and generally common in software development, sometimes also notabug) that indicates the ticket is not a bug, is a support request, or is generally invalid., emit a { status: 'disconnected', error } event so the editor can inform the user. The WPVIP pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party. maps WebSocket close codes to specific error types to give users actionable feedback.

The WPVIP Real-Time Collaboration plugin is a functional and secure example using WebSockets. It’s open sourceOpen Source Open Source denotes software for which the original source code is made freely available and may be redistributed and modified. Open Source **must be** delivered via a licensing model, see GPL. and contributions are welcome.

Feedback

If you have questions or feedback about building a custom sync provider, please share them in a comment on this post or in the #hosting channel of Make WordPress Slack.

Props to @jorbin and @westonruter for feedback and contributions.

#7-0, #dev-notes, #dev-notes-7-0, #feature-real-time-collaboration