Mark existing URL Metrics as stale when a new tag visitor is registered

plugins/embed-optimizer/tests/test-cases/single-twitter-embed-inside-viewport-without-resized-data.php

@@ -9,7 +9,8 @@
 					'intersectionRatio' => 1,
 					// Intentionally omitting resizedBoundingClientRect here to test behavior when data isn't supplied.
 				),
-			)
+			),
+			'embeds'
 		);
 	},
 	'buffer'   => '

plugins/embed-optimizer/tests/test-cases/single-twitter-embed-inside-viewport.php

@@ -9,7 +9,8 @@
 					'intersectionRatio'         => 1,
 					'resizedBoundingClientRect' => array_merge( $test_case->get_sample_dom_rect(), array( 'height' => 500 ) ),
 				),
-			)
+			),
+			'embeds'
 		);
 	},
 	'buffer'   => '

plugins/embed-optimizer/tests/test-cases/single-twitter-embed-outside-viewport-on-mobile.php

@@ -22,6 +22,7 @@
 					od_get_url_metrics_slug( od_get_normalized_query_vars() ),
 					$test_case->get_sample_url_metric(
 						array(
+							'eTag'           => 'embeds',
 							'viewport_width' => $viewport_width,
 							'elements'       => $elements,
 						)

plugins/embed-optimizer/tests/test-cases/single-twitter-embed-outside-viewport.php

@@ -9,7 +9,8 @@
 					'intersectionRatio'         => 0,
 					'resizedBoundingClientRect' => array_merge( $test_case->get_sample_dom_rect(), array( 'height' => 500 ) ),
 				),
-			)
+			),
+			'embeds'
 		);
 	},
 	'buffer'   => '

plugins/embed-optimizer/tests/test-cases/single-youtube-embed-inside-viewport.php

@@ -9,7 +9,8 @@
 					'intersectionRatio'         => 1,
 					'resizedBoundingClientRect' => array_merge( $test_case->get_sample_dom_rect(), array( 'height' => 500 ) ),
 				),
-			)
+			),
+			'embeds'
 		);
 	},
 	'buffer'   => '

plugins/embed-optimizer/tests/test-cases/single-youtube-embed-outside-viewport-on-mobile.php

@@ -22,6 +22,7 @@
 					od_get_url_metrics_slug( od_get_normalized_query_vars() ),
 					$test_case->get_sample_url_metric(
 						array(
+							'eTag'           => 'embeds',
 							'viewport_width' => $viewport_width,
 							'elements'       => $elements,
 						)

plugins/embed-optimizer/tests/test-cases/single-youtube-embed-outside-viewport.php

@@ -9,7 +9,8 @@
 					'intersectionRatio'         => 0,
 					'resizedBoundingClientRect' => array_merge( $test_case->get_sample_dom_rect(), array( 'height' => 500 ) ),
 				),
-			)
+			),
+			'embeds'
 		);
 	},
 	'buffer'   => '

plugins/image-prioritizer/tests/test-cases/common-lcp-background-image-with-fully-populated-sample-data.php

@@ -7,7 +7,8 @@
 					'xpath' => '/*[1][self::HTML]/*[2][self::BODY]/*[1][self::DIV]',
 					'isLCP' => true,
 				),
-			)
+			),
+			'image-prioritizer/img,image-prioritizer/background-image,image-prioritizer/video'
 		);
 	},
 	'buffer'   => '

plugins/image-prioritizer/tests/test-cases/common-lcp-image-and-lazy-loaded-image-outside-viewport-with-fully-populated-sample-data.php

@@ -15,6 +15,7 @@
 					$slug,
 					$test_case->get_sample_url_metric(
 						array(
+							'eTag'           => 'image-prioritizer/img,image-prioritizer/background-image,image-prioritizer/video',
 							'viewport_width' => $viewport_width,
 							'elements'       => array(
 								array(

plugins/image-prioritizer/tests/test-cases/common-lcp-image-with-stale-sample-data.php

@@ -7,7 +7,8 @@
 					'xpath' => '/*[1][self::HTML]/*[2][self::BODY]/*[1][self::IMG]', // Note: This is intentionally not reflecting the IMG in the HTML below.
 					'isLCP' => true,
 				),
-			)
+			),
+			'image-prioritizer/img,image-prioritizer/background-image,image-prioritizer/video'
 		);
 	},
 	'buffer'   => '

plugins/image-prioritizer/tests/test-cases/fetch-priority-high-already-on-common-lcp-image-with-fully-populated-sample-data.php

@@ -7,7 +7,8 @@
 					'isLCP' => true,
 					'xpath' => '/*[1][self::HTML]/*[2][self::BODY]/*[1][self::IMG]',
 				),
-			)
+			),
+			'image-prioritizer/img,image-prioritizer/background-image,image-prioritizer/video'
 		);
 	},
 	'buffer'   => '

plugins/image-prioritizer/tests/test-cases/images-located-above-or-along-initial-viewport.php

@@ -37,6 +37,7 @@
 					$slug,
 					$test_case->get_sample_url_metric(
 						array(
+							'eTag'           => 'image-prioritizer/img,image-prioritizer/background-image,image-prioritizer/video',
 							'viewport_width' => $viewport_width,
 							'elements'       => array(
 								array(

plugins/image-prioritizer/tests/test-cases/no-lcp-image-with-populated-url-metrics.php

@@ -7,7 +7,8 @@
 					'xpath' => '/*[1][self::HTML]/*[2][self::BODY]/*[1][self::H1]',
 					'isLCP' => true,
 				),
-			)
+			),
+			'image-prioritizer/img,image-prioritizer/background-image,image-prioritizer/video'
 		);
 	},
 	'buffer'   => '

plugins/image-prioritizer/tests/test-cases/responsive-background-images.php

@@ -25,6 +25,7 @@ static function () use ( $mobile_breakpoint, $tablet_breakpoint ): array {
 					$slug,
 					$test_case->get_sample_url_metric(
 						array(
+							'eTag'           => 'image-prioritizer/img,image-prioritizer/background-image,image-prioritizer/video',
 							'viewport_width' => $viewport_width,
 							'element'        => array(
 								'xpath' => sprintf( '/*[1][self::HTML]/*[2][self::BODY]/*[%d][self::DIV]', $div_index + 1 ),

plugins/image-prioritizer/tests/test-helper.php

@@ -205,7 +205,7 @@ public function data_provider_test_auto_sizes(): array {
 	 * @phpstan-param array{ xpath: string, isLCP: bool, intersectionRatio: int } $element_metrics
 	 */
 	public function test_auto_sizes( array $element_metrics, string $buffer, string $expected ): void {
-		$this->populate_url_metrics( array( $element_metrics ) );
+		$this->populate_url_metrics( array( $element_metrics ), 'image-prioritizer/img,image-prioritizer/background-image,image-prioritizer/video' );
 
 		$html_start_doc = '<html lang="en"><head><meta charset="utf-8"><title>...</title></head><body>';
 		$html_end_doc   = '</body></html>';

plugins/optimization-detective/class-od-url-metric-group-collection.php

@@ -35,6 +35,14 @@ final class OD_URL_Metric_Group_Collection implements Countable, IteratorAggrega
 	 */
 	private $groups;
 
+	/**
+	 * The current Etag.
+	 *
+	 * @since n.e.x.t
+	 * @var string
+	 */
+	private $current_etag;
+
 	/**
 	 * Breakpoints in max widths.
 	 *
@@ -94,11 +102,14 @@ final class OD_URL_Metric_Group_Collection implements Countable, IteratorAggrega
 	 * @throws InvalidArgumentException When an invalid argument is supplied.
 	 *
 	 * @param OD_URL_Metric[] $url_metrics   URL Metrics.
+	 * @param string          $current_etag  The current ETag.
 	 * @param int[]           $breakpoints   Breakpoints in max widths.
 	 * @param int             $sample_size   Sample size for the maximum number of viewports in a group between breakpoints.
 	 * @param int             $freshness_ttl Freshness age (TTL) for a given URL Metric.
 	 */
-	public function __construct( array $url_metrics, array $breakpoints, int $sample_size, int $freshness_ttl ) {
+	public function __construct( array $url_metrics, string $current_etag, array $breakpoints, int $sample_size, int $freshness_ttl ) {
+		$this->current_etag = $current_etag;
+
 		// Set breakpoints.
 		sort( $breakpoints );
 		$breakpoints = array_values( array_unique( $breakpoints, SORT_NUMERIC ) );
@@ -160,6 +171,17 @@ public function __construct( array $url_metrics, array $breakpoints, int $sample
 		}
 	}
 
+	/**
+	 * Gets the current ETag.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @return string Current ETag.
+	 */
+	public function get_current_etag(): string {
+		return $this->current_etag;
+	}
+
 	/**
 	 * Gets the first URL Metric group.
 	 *
@@ -613,6 +635,7 @@ public function count(): int {
 	 * @since 0.3.1
 	 *
 	 * @return array{
+	 *             current_etag: string,
 	 *             breakpoints: positive-int[],
 	 *             freshness_ttl: 0|positive-int,
 	 *             sample_size: positive-int,
@@ -631,6 +654,7 @@ public function count(): int {
 	 */
 	public function jsonSerialize(): array {
 		return array(
+			'current_etag'                        => $this->current_etag,
 			'breakpoints'                         => $this->breakpoints,
 			'freshness_ttl'                       => $this->freshness_ttl,
 			'sample_size'                         => $this->sample_size,

plugins/optimization-detective/class-od-url-metric-group.php

@@ -220,6 +220,8 @@ static function ( OD_URL_Metric $a, OD_URL_Metric $b ): int {
 	 * A group is complete if it has the full sample size of URL Metrics
 	 * and all of these URL Metrics are fresh.
 	 *
+	 * @since n.e.x.t If the current environment's generated ETag does not match the URL Metric's ETag, the URL Metric is considered stale.
+	 *
 	 * @return bool Whether complete.
 	 */
 	public function is_complete(): bool {
@@ -233,7 +235,12 @@ public function is_complete(): bool {
 			}
 			$current_time = microtime( true );
 			foreach ( $this->url_metrics as $url_metric ) {
-				if ( $current_time > $url_metric->get_timestamp() + $this->freshness_ttl ) {
+				if (
+					$current_time > $url_metric->get_timestamp() + $this->freshness_ttl
+					||
+					// If the URL Metric's ETag doesn't match the current ETag, consider the URL metric as stale.
+					( null !== $this->collection && $url_metric->get_etag() !== $this->collection->get_current_etag() )
+				) {
 					return false;
 				}
 			}

plugins/optimization-detective/class-od-url-metric.php

@@ -38,6 +38,7 @@
  *                            }
  * @phpstan-type Data         array{
  *                                uuid: non-empty-string,
+ *                                eTag?: string,
  *                                url: non-empty-string,
  *                                timestamp: float,
  *                                viewport: ViewportRect,
@@ -155,6 +156,7 @@ public function set_group( OD_URL_Metric_Group $group ): void {
 	 * Gets JSON schema for URL Metric.
 	 *
 	 * @since 0.1.0
+	 * @since n.e.x.t Added the 'eTag' property to the schema.
 	 *
 	 * @todo Cache the return value?
 	 *
@@ -208,6 +210,12 @@ public static function get_json_schema(): array {
 					'required'    => true,
 					'readonly'    => true, // Omit from REST API.
 				),
+				'eTag'      => array(
+					'description' => __( 'The ETag for the URL Metric.', 'optimization-detective' ),
+					'type'        => 'string',
+					'required'    => false,
+					'readonly'    => true, // Omit from REST API.
+				),
 				'url'       => array(
 					'description' => __( 'The URL for which the metric was obtained.', 'optimization-detective' ),
 					'type'        => 'string',
@@ -309,7 +317,7 @@ public static function get_json_schema(): array {
 			$schema['properties']['elements']['items']['properties'] = self::extend_schema_with_optional_properties(
 				$schema['properties']['elements']['items']['properties'],
 				$additional_properties,
-				'od_url_metric_schema_root_additional_properties'
+				'od_url_metric_schema_element_item_additional_properties'
 			);
 		}
 
@@ -417,6 +425,18 @@ public function get_uuid(): string {
 		return $this->data['uuid'];
 	}
 
+	/**
+	 * Gets ETag.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @return string ETag.
+	 */
+	public function get_etag(): string {
+		// Since the ETag is optional for now, return an empty string for old URL metrics that do not have one.
+		return $this->data['eTag'] ?? '';
+	}
+
 	/**
 	 * Gets URL.
 	 *

plugins/optimization-detective/detect.js

@@ -237,6 +237,7 @@ function extendElementData( xpath, properties ) {
  * @param {number}                 args.maxViewportAspectRatio     Maximum aspect ratio allowed for the viewport.
  * @param {boolean}                args.isDebug                    Whether to show debug messages.
  * @param {string}                 args.restApiEndpoint            URL for where to send the detection data.
+ * @param {string}                 args.currentETag                ETag for URL Metric.
  * @param {string}                 args.currentUrl                 Current URL.
  * @param {string}                 args.urlMetricSlug              Slug for URL Metric.
  * @param {number|null}            args.cachePurgePostId           Cache purge post ID.
@@ -252,6 +253,7 @@ export default async function detect( {
 	isDebug,
 	extensionModuleUrls,
 	restApiEndpoint,
+	currentETag,
 	currentUrl,
 	urlMetricSlug,
 	cachePurgePostId,
@@ -539,6 +541,7 @@ export default async function detect( {
 
 	const url = new URL( restApiEndpoint );
 	url.searchParams.set( 'slug', urlMetricSlug );
+	url.searchParams.set( 'eTag', currentETag );
 	if ( typeof cachePurgePostId === 'number' ) {
 		url.searchParams.set(
 			'cache_purge_post_id',

plugins/optimization-detective/detection.php

@@ -85,16 +85,18 @@ function od_get_detection_script( string $slug, OD_URL_Metric_Group_Collection $
 	$cache_purge_post_id = od_get_cache_purge_post_id();
 
 	$current_url = od_get_current_url();
+
 	$detect_args = array(
 		'minViewportAspectRatio' => od_get_minimum_viewport_aspect_ratio(),
 		'maxViewportAspectRatio' => od_get_maximum_viewport_aspect_ratio(),
 		'isDebug'                => WP_DEBUG,
 		'extensionModuleUrls'    => $extension_module_urls,
 		'restApiEndpoint'        => rest_url( OD_REST_API_NAMESPACE . OD_URL_METRICS_ROUTE ),
+		'currentETag'            => $group_collection->get_current_etag(),
 		'currentUrl'             => $current_url,
 		'urlMetricSlug'          => $slug,
 		'cachePurgePostId'       => od_get_cache_purge_post_id(),
-		'urlMetricHMAC'          => od_get_url_metrics_storage_hmac( $slug, $current_url, $cache_purge_post_id ),
+		'urlMetricHMAC'          => od_get_url_metrics_storage_hmac( $slug, $group_collection->get_current_etag(), $current_url, $cache_purge_post_id ),
 		'urlMetricGroupStatuses' => array_map(
 			static function ( OD_URL_Metric_Group $group ): array {
 				return array(

plugins/optimization-detective/optimization.php

@@ -195,16 +195,6 @@ function od_optimize_template_output_buffer( string $buffer ): string {
 	$slug = od_get_url_metrics_slug( od_get_normalized_query_vars() );
 	$post = OD_URL_Metrics_Post_Type::get_post( $slug );
 
-	$group_collection = new OD_URL_Metric_Group_Collection(
-		$post instanceof WP_Post ? OD_URL_Metrics_Post_Type::get_url_metrics_from_post( $post ) : array(),
-		od_get_breakpoint_max_widths(),
-		od_get_url_metrics_breakpoint_sample_size(),
-		od_get_url_metric_freshness_ttl()
-	);
-
-	// Whether we need to add the data-od-xpath attribute to elements and whether the detection script should be injected.
-	$needs_detection = ! $group_collection->is_every_group_complete();
-
 	$tag_visitor_registry = new OD_Tag_Visitor_Registry();
 
 	/**
@@ -216,10 +206,23 @@ function od_optimize_template_output_buffer( string $buffer ): string {
 	 */
 	do_action( 'od_register_tag_visitors', $tag_visitor_registry );
 
+	$visitors     = iterator_to_array( $tag_visitor_registry );
+	$current_etag = implode( ',', array_keys( $visitors ) );
+
+	$group_collection     = new OD_URL_Metric_Group_Collection(
+		$post instanceof WP_Post ? OD_URL_Metrics_Post_Type::get_url_metrics_from_post( $post ) : array(),
+		$current_etag,
+		od_get_breakpoint_max_widths(),
+		od_get_url_metrics_breakpoint_sample_size(),
+		od_get_url_metric_freshness_ttl()
+	);
 	$link_collection      = new OD_Link_Collection();
 	$tag_visitor_context  = new OD_Tag_Visitor_Context( $processor, $group_collection, $link_collection );
 	$current_tag_bookmark = 'optimization_detective_current_tag';
-	$visitors             = iterator_to_array( $tag_visitor_registry );
+
+	// Whether we need to add the data-od-xpath attribute to elements and whether the detection script should be injected.
+	$needs_detection = ! $group_collection->is_every_group_complete();
+
 	do {
 		$tracked_in_url_metrics = false;
 		$processor->set_bookmark( $current_tag_bookmark ); // TODO: Should we break if this returns false?

plugins/optimization-detective/storage/class-od-url-metrics-post-type.php

@@ -219,6 +219,7 @@ public static function store_url_metric( string $slug, OD_URL_Metric $new_url_me
 
 		$group_collection = new OD_URL_Metric_Group_Collection(
 			$url_metrics,
+			$new_url_metric->get_etag(),
 			od_get_breakpoint_max_widths(),
 			od_get_url_metrics_breakpoint_sample_size(),
 			od_get_url_metric_freshness_ttl()