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

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

@@ -220,20 +220,32 @@ 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.
+	 *
+	 * @global string $od_etag ETag for the current environment.
+	 *
 	 * @return bool Whether complete.
 	 */
 	public function is_complete(): bool {
+		global $od_etag;
+
 		if ( array_key_exists( __FUNCTION__, $this->result_cache ) ) {
 			return $this->result_cache[ __FUNCTION__ ];
 		}
 
-		$result = ( function () {
+		$result = ( function () use ( $od_etag ) {
 			if ( count( $this->url_metrics ) < $this->sample_size ) {
 				return false;
 			}
 			$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 generated ETag does not match the URL metric's ETag, consider the URL metric as stale.
+					// NOTE: Since the ETag is optional for now, existing ones without it are not considered stale.
+					( $url_metric->get( 'eTag' ) !== null && $url_metric->get( 'eTag' ) !== $od_etag )
+				) {
 					return false;
 				}
 			}

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

@@ -309,7 +309,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'
 			);
 		}
 

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,
@@ -440,6 +442,7 @@ export default async function detect( {
 	}
 
 	urlMetric = {
+		eTag: currentETag,
 		url: currentUrl,
 		viewport: {
 			width: win.innerWidth,

plugins/optimization-detective/detection.php

@@ -66,10 +66,14 @@ function od_get_cache_purge_post_id(): ?int {
  * @since 0.1.0
  * @access private
  *
+ * @global string $od_etag ETag for the current environment.
+ *
  * @param string                         $slug             URL Metrics slug.
  * @param OD_URL_Metric_Group_Collection $group_collection URL Metric group collection.
  */
 function od_get_detection_script( string $slug, OD_URL_Metric_Group_Collection $group_collection ): string {
+	global $od_etag;
+
 	$web_vitals_lib_data = require __DIR__ . '/build/web-vitals.asset.php';
 	$web_vitals_lib_src  = add_query_arg( 'ver', $web_vitals_lib_data['version'], plugin_dir_url( __FILE__ ) . 'build/web-vitals.js' );
 
@@ -85,16 +89,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'            => $od_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, $od_etag, $current_url, $cache_purge_post_id ),
 		'urlMetricGroupStatuses' => array_map(
 			static function ( OD_URL_Metric_Group $group ): array {
 				return array(

plugins/optimization-detective/helper.php

@@ -100,3 +100,21 @@ function od_get_asset_path( string $src_path, ?string $min_path = null ): string
 
 	return $min_path;
 }
+
+/**
+ * Adds optional URL Metric schema root properties.
+ *
+ * @since n.e.x.t
+ *
+ * @param array<string, array{type: string}> $additional_properties Additional properties.
+ * @return array<string, array{type: string}> Additional properties.
+ */
+function od_add_optional_url_metric_schema_root_properties( array $additional_properties ): array {
+	// The ETag is being kept optional for now so as to avoid invalidating all current URL Metrics.
+	$additional_properties['eTag'] = array(
+		'description' => __( 'The ETag for the URL Metric.', 'optimization-detective' ),
+		'type'        => 'string',
+	);
+
+	return $additional_properties;
+}

plugins/optimization-detective/hooks.php

@@ -15,3 +15,4 @@
 OD_URL_Metrics_Post_Type::add_hooks();
 add_action( 'wp', 'od_maybe_add_template_output_buffer_filter' );
 add_action( 'wp_head', 'od_render_generator_meta_tag' );
+add_filter( 'od_url_metric_schema_root_additional_properties', 'od_add_optional_url_metric_schema_root_properties' );

plugins/optimization-detective/optimization.php

@@ -199,9 +199,6 @@ function od_optimize_template_output_buffer( string $buffer ): string {
 		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();
 
 	/**
@@ -217,6 +214,22 @@ function od_optimize_template_output_buffer( string $buffer ): string {
 	$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 );
+
+	/**
+	 * ETag generated for the current environment.
+	 *
+	 * @since n.e.x.t
+	 *
+	 * @global string $od_etag
+	 */
+	global $od_etag;
+
+	// Generate and store an ETag consisting of all the tag visitors' IDs in the current environment.
+	$od_etag = implode( ',', array_keys( $visitors ) );
+
+	// 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/data.php

@@ -150,15 +150,15 @@ function od_get_url_metrics_slug( array $query_vars ): string {
  *
  * @see od_verify_url_metrics_storage_hmac()
  * @see od_get_url_metrics_slug()
- * @todo This should also include an ETag as a parameter. See <https://github.com/WordPress/performance/issues/1466>.
  *
  * @param string   $slug                Slug (hash of normalized query vars).
+ * @param string   $etag                ETag.
  * @param string   $url                 URL.
  * @param int|null $cache_purge_post_id Cache purge post ID.
  * @return string HMAC.
  */
-function od_get_url_metrics_storage_hmac( string $slug, string $url, ?int $cache_purge_post_id = null ): string {
-	$action = "store_url_metric:$slug:$url:$cache_purge_post_id";
+function od_get_url_metrics_storage_hmac( string $slug, string $etag, string $url, ?int $cache_purge_post_id = null ): string {
+	$action = "store_url_metric:$slug:$etag:$url:$cache_purge_post_id";
 	return wp_hash( $action, 'nonce' );
 }
 
@@ -173,12 +173,13 @@ function od_get_url_metrics_storage_hmac( string $slug, string $url, ?int $cache
  *
  * @param string   $hmac                HMAC.
  * @param string   $slug                Slug (hash of normalized query vars).
+ * @param string   $etag                ETag.
  * @param String   $url                 URL.
  * @param int|null $cache_purge_post_id Cache purge post ID.
  * @return bool Whether the HMAC is valid.
  */
-function od_verify_url_metrics_storage_hmac( string $hmac, string $slug, string $url, ?int $cache_purge_post_id = null ): bool {
-	return hash_equals( od_get_url_metrics_storage_hmac( $slug, $url, $cache_purge_post_id ), $hmac );
+function od_verify_url_metrics_storage_hmac( string $hmac, string $slug, string $etag, string $url, ?int $cache_purge_post_id = null ): bool {
+	return hash_equals( od_get_url_metrics_storage_hmac( $slug, $etag, $url, $cache_purge_post_id ), $hmac );
 }
 
 /**

plugins/optimization-detective/storage/rest-api.php

@@ -58,7 +58,7 @@ function od_register_endpoint(): void {
 			'required'          => true,
 			'pattern'           => '^[0-9a-f]+$',
 			'validate_callback' => static function ( string $hmac, WP_REST_Request $request ) {
-				if ( ! od_verify_url_metrics_storage_hmac( $hmac, $request['slug'], $request['url'], $request['cache_purge_post_id'] ?? null ) ) {
+				if ( ! od_verify_url_metrics_storage_hmac( $hmac, $request['slug'], $request['eTag'], $request['url'], $request['cache_purge_post_id'] ?? null ) ) {
 					return new WP_Error( 'invalid_hmac', __( 'URL Metrics HMAC verification failure.', 'optimization-detective' ) );
 				}
 				return true;

plugins/optimization-detective/tests/storage/test-rest-api.php

@@ -156,7 +156,7 @@ function ( $params ) {
 					'hmac' => 'not even a hash',
 				),
 				'invalid_hmac'                             => array(
-					'hmac' => od_get_url_metrics_storage_hmac( od_get_url_metrics_slug( array( 'different' => 'query vars' ) ), home_url( '/' ) ),
+					'hmac' => od_get_url_metrics_storage_hmac( od_get_url_metrics_slug( array( 'different' => 'query vars' ) ), '', home_url( '/' ) ),
 				),
 				'invalid_hmac_with_queried_object'         => array(
 					'hmac' => od_get_url_metrics_storage_hmac( od_get_url_metrics_slug( array() ), home_url( '/' ), 1 ),
@@ -672,7 +672,7 @@ private function get_valid_params( array $extras = array() ): array {
 		$data = array_merge(
 			array(
 				'slug' => $slug,
-				'hmac' => od_get_url_metrics_storage_hmac( $slug, $data['url'] ),
+				'hmac' => od_get_url_metrics_storage_hmac( $slug, '', $data['url'] ),
 			),
 			$data
 		);

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

@@ -626,7 +626,7 @@ static function ( $additional_properties ) {
 				'assert'                   => function ( array $original_schema, $extended_schema ): void {
 					$this->assertSame( $original_schema, $extended_schema );
 				},
-				'expected_incorrect_usage' => 'Filter: 'od_url_metric_schema_root_additional_properties'',
+				'expected_incorrect_usage' => 'Filter: 'od_url_metric_schema_element_item_additional_properties'',
 			),
 
 			'adding_root_string'             => array(
@@ -728,7 +728,11 @@ protected function check_schema_subset( array $schema, string $path, bool $exten
 				$this->assertTrue( $schema['additionalProperties'], "Path: $path" );
 			}
 			foreach ( $schema['properties'] as $key => $property_schema ) {
-				$this->check_schema_subset( $property_schema, "$path/$key", $extended );
+				if ( 'eTag' === $key ) {
+					$this->check_schema_subset( $property_schema, "$path/$key", true );
+				} else {
+					$this->check_schema_subset( $property_schema, "$path/$key", $extended );
+				}
 			}
 		} elseif ( 'array' === $schema['type'] ) {
 			$this->assertArrayHasKey( 'items', $schema, $path );

plugins/optimization-detective/types.ts

@@ -13,6 +13,7 @@ export interface ElementData {
 export type ExtendedElementData = ExcludeProps< ElementData >;
 
 export interface URLMetric {
+	eTag: string;
 	url: string;
 	viewport: {
 		width: number;