class-wp-sync-post-meta-storage.php

<?php
/**
 * WP_Sync_Post_Meta_Storage class
 *
 * @package WordPress
 */

/**
 * Core class that provides an interface for storing and retrieving sync
 * updates and awareness data during a collaborative session.
 *
 * Data is stored as post meta on a dedicated post per room of a custom post type.
 *
 * @since 7.0.0
 *
 * @access private
 */
class WP_Sync_Post_Meta_Storage implements WP_Sync_Storage {
	/**
	 * Post type for sync storage.
	 *
	 * @since 7.0.0
	 * @var string
	 */
	const POST_TYPE = 'wp_sync_storage';

	/**
	 * Meta key for awareness state.
	 *
	 * @since 7.0.0
	 * @var string
	 */
	const AWARENESS_META_KEY = 'wp_sync_awareness';

	/**
	 * Meta key for sync updates.
	 *
	 * @since 7.0.0
	 * @var string
	 */
	const SYNC_UPDATE_META_KEY = 'wp_sync_update';

	/**
	 * Cache of cursors by room.
	 *
	 * @since 7.0.0
	 * @var array<string, int>
	 */
	private array $room_cursors = array();

	/**
	 * Cache of update counts by room.
	 *
	 * @since 7.0.0
	 * @var array<string, int>
	 */
	private array $room_update_counts = array();

	/**
	 * Cache of storage post IDs by room hash.
	 *
	 * @since 7.0.0
	 * @var array<string, int>
	 */
	private static array $storage_post_ids = array();

	/**
	 * Adds a sync update to a given room.
	 *
	 * @since 7.0.0
	 *
	 * @param string $room   Room identifier.
	 * @param mixed  $update Sync update.
	 * @return bool True on success, false on failure.
	 */
	public function add_update( string $room, $update ): bool {
		$post_id = $this->get_storage_post_id( $room );
		if ( null === $post_id ) {
			return false;
		}

		$meta_id = $this->with_suspended_posts_last_changed_update(
			fn() => add_post_meta( $post_id, self::SYNC_UPDATE_META_KEY, $update, false )
		);

		if ( $meta_id ) {
			wp_cache_delete( "sync_room_state_{$this->get_room_hash( $room )}", 'sync' );
		}

		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 {
		$awareness = get_transient( "sync_awareness_{$this->get_room_hash( $room )}" );

		if ( ! is_array( $awareness ) ) {
			return array();
		}

		return array_values( $awareness );
	}

	/**
	 * 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 {
		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
	 * highest meta_id seen for the room's sync updates.
	 *
	 * @since 7.0.0
	 *
	 * @param string $room Room identifier.
	 * @return int Current cursor for the room.
	 */
	public function get_cursor( string $room ): int {
		return $this->room_cursors[ $room ] ?? 0;
	}

	/**
	 * Gets or creates the storage post for a given room.
	 *
	 * Each room gets its own dedicated post so that post meta cache
	 * invalidation is scoped to a single room rather than all of them.
	 *
	 * @since 7.0.0
	 *
	 * @param string $room Room identifier.
	 * @return int|null Post ID.
	 */
	private function get_storage_post_id( string $room ): ?int {
		$room_hash = $this->get_room_hash( $room );

		if ( isset( self::$storage_post_ids[ $room_hash ] ) ) {
			return self::$storage_post_ids[ $room_hash ];
		}

		// Try to find an existing post for this room.
		$posts = get_posts(
			array(
				'post_type'      => self::POST_TYPE,
				'posts_per_page' => 1,
				'post_status'    => 'publish',
				'name'           => $room_hash,
				'fields'         => 'ids',
			)
		);

		$post_id = array_first( $posts );
		if ( is_int( $post_id ) ) {
			self::$storage_post_ids[ $room_hash ] = $post_id;
			return $post_id;
		}

		// Create new post for this room.
		$post_id = wp_insert_post(
			array(
				'post_type'   => self::POST_TYPE,
				'post_status' => 'publish',
				'post_title'  => 'Sync Storage',
				'post_name'   => $room_hash,
			)
		);

		if ( is_int( $post_id ) ) {
			self::$storage_post_ids[ $room_hash ] = $post_id;
			return $post_id;
		}

		return null;
	}

	/**
	 * Gets the number of updates stored for a given room.
	 *
	 * @since 7.0.0
	 *
	 * @param string $room Room identifier.
	 * @return int Number of updates stored for the room.
	 */
	public function get_update_count( string $room ): int {
		return $this->room_update_counts[ $room ] ?? 0;
	}

	/**
	 * 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 (meta_id).
	 * @return array<int, mixed> Sync updates.
	 */
	public function get_updates_after_cursor( string $room, int $cursor ): array {
		global $wpdb;

		$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();
		}

		// 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'
		);

		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;
	}

	/**
	 * Removes updates from a room that are older than the given cursor.
	 *
	 * @since 7.0.0
	 *
	 * @param string $room   Room identifier.
	 * @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;
		}

		$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
			)
		);

		if ( false === $deleted_rows ) {
			return 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 ) {
		$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;
	}

	/**
	 * 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 );
	}
}