Skip to content

[WIP] Real-time Collaboration: Cache awareness state to reduce postmeta queries #11067

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mindctrl wants to merge 4 commits into
base: trunk
Choose a base branch
from
Open

[WIP] Real-time Collaboration: Cache awareness state to reduce postmeta queries #11067

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
fbc4e44
Prevent calling wp_cache_set_posts_last_changed() when touching post …
westonruter Feb 23, 2026
a9bf03a
Collaborative Editing: Fix race condition and optimize cache invalida…
mindctrl Feb 25, 2026
a850382
Simplify awareness state caching by using the Transients API.
mindctrl Feb 25, 2026
cd89563
Add test to ensure updates inserted during deletes are not also deleted
mindctrl Feb 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
234 changes: 144 additions & 90 deletions src/wp-includes/collaboration/class-wp-sync-post-meta-storage.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,65 +79,32 @@ public function add_update( string $room, $update ): bool {
return false;
}

// Create an envelope and stamp each update to enable cursor-based filtering.
$envelope = array(
'timestamp' => $this->get_time_marker(),
'value' => $update,
$meta_id = $this->with_suspended_posts_last_changed_update(
fn() => add_post_meta( $post_id, self::SYNC_UPDATE_META_KEY, $update, false )
);

return (bool) add_post_meta( $post_id, wp_slash( self::SYNC_UPDATE_META_KEY ), wp_slash( $envelope ), false );
}

/**
* Retrieves all sync updates for a given room.
*
* @since 7.0.0
*
* @param string $room Room identifier.
* @return array<int, array{ timestamp: int, value: mixed }> Sync updates.
*/
private function get_all_updates( string $room ): array {
$this->room_cursors[ $room ] = $this->get_time_marker() - 100; // Small buffer to ensure consistency.

$post_id = $this->get_storage_post_id( $room );
if ( null === $post_id ) {
return array();
if ( $meta_id ) {
wp_cache_delete( "sync_room_state_{$this->get_room_hash( $room )}", 'sync' );
}

$updates = get_post_meta( $post_id, self::SYNC_UPDATE_META_KEY, false );

if ( ! is_array( $updates ) ) {
$updates = array();
}

// Filter out any updates that don't have the expected structure.
$updates = array_filter(
$updates,
static function ( $update ): bool {
return is_array( $update ) && isset( $update['timestamp'], $update['value'] ) && is_int( $update['timestamp'] );
}
);

$this->room_update_counts[ $room ] = count( $updates );

return $updates;
return (bool) $meta_id;
}

/**
* Gets awareness state for a given room.
*
* Awareness data is stored in a transient with a short TTL. Transients may
* be evicted at any time (cache flush, deploy, expiration), in which case
* this method returns an empty array and clients briefly appear offline
* until the next poll repopulates state (typically under one second).
*
* @since 7.0.0
*
* @param string $room Room identifier.
* @return array<int, mixed> Awareness state.
*/
public function get_awareness_state( string $room ): array {
$post_id = $this->get_storage_post_id( $room );
if ( null === $post_id ) {
return array();
}

$awareness = get_post_meta( $post_id, self::AWARENESS_META_KEY, true );
$awareness = get_transient( "sync_awareness_{$this->get_room_hash( $room )}" );

if ( ! is_array( $awareness ) ) {
return array();
Expand All @@ -149,29 +116,26 @@ public function get_awareness_state( string $room ): array {
/**
* Sets awareness state for a given room.
*
* Uses a transient rather than post meta to avoid database write churn,
* since awareness data (cursor positions, selections) is ephemeral and
* repopulated on every client poll. A cache eviction only causes a brief
* flicker rather than data loss.
*
* @since 7.0.0
*
* @param string $room Room identifier.
* @param array<int, mixed> $awareness Serializable awareness state.
* @return bool True on success, false on failure.
*/
public function set_awareness_state( string $room, array $awareness ): bool {
$post_id = $this->get_storage_post_id( $room );
if ( null === $post_id ) {
return false;
}

// update_post_meta returns false if the value is the same as the existing value.
update_post_meta( $post_id, wp_slash( self::AWARENESS_META_KEY ), wp_slash( $awareness ) );
return true;
return set_transient( "sync_awareness_{$this->get_room_hash( $room )}", $awareness, MINUTE_IN_SECONDS );
}

/**
* Gets the current cursor for a given room.
*
* The cursor is set during get_updates_after_cursor() and represents the
* point in time just before the updates were retrieved, with a small buffer
* to ensure consistency.
* highest meta_id seen for the room's sync updates.
*
* @since 7.0.0
*
Expand All @@ -194,7 +158,7 @@ public function get_cursor( string $room ): int {
* @return int|null Post ID.
*/
private function get_storage_post_id( string $room ): ?int {
$room_hash = md5( $room );
$room_hash = $this->get_room_hash( $room );

if ( isset( self::$storage_post_ids[ $room_hash ] ) ) {
return self::$storage_post_ids[ $room_hash ];
Expand Down Expand Up @@ -235,17 +199,6 @@ private function get_storage_post_id( string $room ): ?int {
return null;
}

/**
* Gets the current time in milliseconds as a comparable time marker.
*
* @since 7.0.0
*
* @return int Current time in milliseconds.
*/
private function get_time_marker(): int {
return (int) floor( microtime( true ) * 1000 );
}

/**
* Gets the number of updates stored for a given room.
*
Expand All @@ -259,32 +212,83 @@ public function get_update_count( string $room ): int {
}

/**
* Retrieves sync updates from a room for a given client and cursor. Updates
* from the specified client should be excluded.
* Retrieves sync updates from a room after the given cursor.
*
* @since 7.0.0
*
* @param string $room Room identifier.
* @param int $cursor Return updates after this cursor.
* @param int $cursor Return updates after this cursor (meta_id).
* @return array<int, mixed> Sync updates.
*/
public function get_updates_after_cursor( string $room, int $cursor ): array {
$all_updates = $this->get_all_updates( $room );
$updates = array();
global $wpdb;

foreach ( $all_updates as $update ) {
if ( $update['timestamp'] > $cursor ) {
$updates[] = $update;
}
$room_hash = $this->get_room_hash( $room );
$state_cache_key = "sync_room_state_{$room_hash}";
$cached = wp_cache_get( $state_cache_key, 'sync' );

if ( is_array( $cached ) && $cached['cursor'] <= $cursor ) {
$this->room_cursors[ $room ] = $cached['cursor'];
$this->room_update_counts[ $room ] = $cached['count'];
return array();
}

$post_id = $this->get_storage_post_id( $room );
if ( null === $post_id ) {
$this->room_cursors[ $room ] = 0;
$this->room_update_counts[ $room ] = 0;
return array();
}

// Sort by timestamp to ensure order.
usort(
$updates,
fn ( $a, $b ) => $a['timestamp'] <=> $b['timestamp']
// Capture the current room state first so the returned cursor is race-safe.
$stats = $wpdb->get_row(
$wpdb->prepare(
"SELECT COUNT(*) AS total_updates, COALESCE( MAX(meta_id), 0 ) AS max_meta_id FROM {$wpdb->postmeta} WHERE post_id = %d AND meta_key = %s",
$post_id,
self::SYNC_UPDATE_META_KEY
)
);

$total_updates = $stats ? (int) $stats->total_updates : 0;
$max_meta_id = $stats ? (int) $stats->max_meta_id : 0;

$this->room_update_counts[ $room ] = $total_updates;
$this->room_cursors[ $room ] = $max_meta_id;

wp_cache_set(
$state_cache_key,
array(
'cursor' => $max_meta_id,
'count' => $total_updates,
),
'sync'
);

return wp_list_pluck( $updates, 'value' );
if ( $max_meta_id <= $cursor ) {
return array();
}

$rows = $wpdb->get_results(
$wpdb->prepare(
"SELECT meta_value FROM {$wpdb->postmeta} WHERE post_id = %d AND meta_key = %s AND meta_id > %d AND meta_id <= %d ORDER BY meta_id ASC",
$post_id,
self::SYNC_UPDATE_META_KEY,
$cursor,
$max_meta_id
)
);

if ( ! $rows ) {
return array();
}

$updates = array();
foreach ( $rows as $row ) {
$update = maybe_unserialize( $row->meta_value );
$updates[] = $update;
}

return $updates;
}

/**
Expand All @@ -293,30 +297,80 @@ public function get_updates_after_cursor( string $room, int $cursor ): array {
* @since 7.0.0
*
* @param string $room Room identifier.
* @param int $cursor Remove updates with markers < this cursor.
* @param int $cursor Remove updates with meta_id < this cursor.
* @return bool True on success, false on failure.
*/
public function remove_updates_before_cursor( string $room, int $cursor ): bool {
global $wpdb;

$post_id = $this->get_storage_post_id( $room );
if ( null === $post_id ) {
return false;
}

$all_updates = $this->get_all_updates( $room );
$deleted_rows = $wpdb->query(
$wpdb->prepare(
"DELETE FROM {$wpdb->postmeta} WHERE post_id = %d AND meta_key = %s AND meta_id < %d",
$post_id,
self::SYNC_UPDATE_META_KEY,
$cursor
)
);

// Remove all updates for the room and re-store only those that are newer than the cursor.
if ( ! delete_post_meta( $post_id, wp_slash( self::SYNC_UPDATE_META_KEY ) ) ) {
if ( false === $deleted_rows ) {
return false;
}

// Re-store envelopes directly to avoid double-wrapping by add_update().
$add_result = true;
foreach ( $all_updates as $envelope ) {
if ( $add_result && $envelope['timestamp'] >= $cursor ) {
$add_result = (bool) add_post_meta( $post_id, self::SYNC_UPDATE_META_KEY, $envelope, false );
if ( $deleted_rows > 0 ) {
wp_cache_delete( $post_id, 'post_meta' );
wp_cache_delete( "sync_room_state_{$this->get_room_hash( $room )}", 'sync' );
}

return true;
}

/**
* Invokes the provided callback while the suspending setting the posts last_changed cache key.
*
* @since 7.0.0
* @see wp_cache_set_posts_last_changed()
*
* @template T
* @param Closure(): T $callback Callback.
* @return T Return value from the callback.
*/
private function with_suspended_posts_last_changed_update( Closure $callback ) {
Copy link
Member

@westonruter westonruter Mar 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see this is now only used in the add_update() method. Is it still even needed?

Copy link
Author

@mindctrl mindctrl Mar 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@westonruter I think we still need to unhook wp_cache_set_posts_last_changed to avoid the cache churn. Given this is the only place it's used in this PR, it could be moved inside add_update(). I don't have a strong preference.

$priorities = array(
'added_post_meta' => has_action( 'added_post_meta', 'wp_cache_set_posts_last_changed' ),
'updated_post_meta' => has_action( 'updated_post_meta', 'wp_cache_set_posts_last_changed' ),
'deleted_post_meta' => has_action( 'deleted_post_meta', 'wp_cache_set_posts_last_changed' ),
);
foreach ( $priorities as $action => $priority ) {
if ( false !== $priority ) {
remove_action( $action, 'wp_cache_set_posts_last_changed', $priority );
}
}
$return_value = $callback();
foreach ( $priorities as $action => $priority ) {
if ( false !== $priority ) {
add_action( $action, 'wp_cache_set_posts_last_changed', $priority );
}
}
return $return_value;
}

return $add_result;
/**
* Returns a hash of the room identifier.
*
* Used as the post slug for storage posts, as a segment in cache keys,
* and as part of transient names.
*
* @since 7.0.0
*
* @param string $room Room identifier.
* @return string MD5 hash of the room.
*/
private function get_room_hash( string $room ): string {
return md5( $room );
}
}
Loading
Loading