General: Add speculative loading support via the Speculation Rules API.

This changeset adds support for the Speculation Rules API and configures it by default to `prefetch` certain links with an eagerness of `conservative`, leading to improved performance by starting to load URLs before the user lands on them.

The new `WP_Speculation_Rules` class is a container class representing the set of used speculation rules. By default, WordPress Core will only add a single speculation rule, which results in most links being prefetched conservatively.

The behavior of that main speculation rule can be altered by using the new `wp_speculation_rules_configuration` filter, which receives an associative array with `mode` and `eagerness` keys, or `null`. Both `mode` and `eagerness` have a default value of `auto`, which for now will result in the aforementioned behavior. The value `null` is used by default in certain scenarios such as when the current user is logged in. Developers can explicitly provide supported mode values (`prefetch` or `prerender`) and other supported eagerness values (`conservative`, `moderate`, or `eager`) to override and enforce the respective behaviors, or return `null` to disable speculative loading feature (either unconditionally or for certain situations). The Speculative Loading feature plugin for example, which this feature is based on, will make use of this filter to continue to use mode `prerender` and eagerness `moderate` by default. Developers can call the `wp_get_speculation_rules_configuration()` function to check how speculative loading is configured on the WordPress site.

Another important filter introduced is `wp_speculation_rules_href_exclude_paths`, which allows to expand the list of URL patterns that are excluded from being prefetched or prerendered per WordPress Core's main speculation rule configuration. Several URL patterns such `/wp-admin/*` (any URL within WP Admin) or `/*\\?(.+)` (any URL that includes query parameters) are already excluded by default. Plugins that use content that would be preferable not to prefetch or prerender can use the filter to provide corresponding URL patterns.

More advanced customization is possible by adding further speculation rules that will be loaded in addition to WordPress Core's main speculation rule. This can be achieved via the new `wp_load_speculation_rules` action, which receives the `WP_Speculation_Rules` class instance and can amend it as needed.

Props flixos90, westonruter, joemcgill, desrosj, mukesh27, tunetheweb, thelovekesh, adamsilverstein, swissspidy, domenicdenicola, jeremyroman.
Fixes #62503.


git-svn-id: https://develop.svn.wordpress.org/trunk@59837 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-includes/class-wp-speculation-rules.php

@@ -0,0 +1,293 @@
+<?php
+/**
+ * Class 'WP_Speculation_Rules'.
+ *
+ * @package WordPress
+ * @subpackage Speculative Loading
+ * @since 6.8.0
+ */
+
+/**
+ * Class representing a set of speculation rules.
+ *
+ * @since 6.8.0
+ * @access private
+ */
+final class WP_Speculation_Rules implements JsonSerializable {
+
+	/**
+	 * Stored rules, as a map of `$mode => $rules` pairs.
+	 *
+	 * Every `$rules` value is a map of `$id => $rule` pairs.
+	 *
+	 * @since 6.8.0
+	 * @var array<string, array<string, mixed>>
+	 */
+	private $rules_by_mode = array();
+
+	/**
+	 * The allowed speculation rules modes as a map, used for validation.
+	 *
+	 * @since 6.8.0
+	 * @var array<string, bool>
+	 */
+	private static $mode_allowlist = array(
+		'prefetch'  => true,
+		'prerender' => true,
+	);
+
+	/**
+	 * The allowed speculation rules eagerness levels as a map, used for validation.
+	 *
+	 * @since 6.8.0
+	 * @var array<string, bool>
+	 */
+	private static $eagerness_allowlist = array(
+		'immediate'    => true,
+		'eager'        => true,
+		'moderate'     => true,
+		'conservative' => true,
+	);
+
+	/**
+	 * The allowed speculation rules sources as a map, used for validation.
+	 *
+	 * @since 6.8.0
+	 * @var array<string, bool>
+	 */
+	private static $source_allowlist = array(
+		'list'     => true,
+		'document' => true,
+	);
+
+	/**
+	 * Adds a speculation rule to the speculation rules to consider.
+	 *
+	 * @since 6.8.0
+	 *
+	 * @param string               $mode Speculative loading mode. Either 'prefetch' or 'prerender'.
+	 * @param string               $id   Unique string identifier for the speculation rule.
+	 * @param array<string, mixed> $rule Associative array of rule arguments.
+	 * @return bool True on success, false if invalid parameters are provided.
+	 */
+	public function add_rule( string $mode, string $id, array $rule ): bool {
+		if ( ! self::is_valid_mode( $mode ) ) {
+			_doing_it_wrong(
+				__METHOD__,
+				sprintf(
+					/* translators: %s: invalid mode value */
+					__( 'The value "%s" is not a valid speculation rules mode.' ),
+					esc_html( $mode )
+				),
+				'6.8.0'
+			);
+			return false;
+		}
+
+		if ( ! $this->is_valid_id( $id ) ) {
+			_doing_it_wrong(
+				__METHOD__,
+				sprintf(
+					/* translators: %s: invalid ID value */
+					__( 'The value "%s" is not a valid ID for a speculation rule.' ),
+					esc_html( $id )
+				),
+				'6.8.0'
+			);
+			return false;
+		}
+
+		if ( $this->has_rule( $mode, $id ) ) {
+			_doing_it_wrong(
+				__METHOD__,
+				sprintf(
+					/* translators: %s: invalid ID value */
+					__( 'A speculation rule with ID "%s" already exists.' ),
+					esc_html( $id )
+				),
+				'6.8.0'
+			);
+			return false;
+		}
+
+		/*
+		 * Perform some basic speculation rule validation.
+		 * Every rule must have either a 'where' key or a 'urls' key, but not both.
+		 * The presence of a 'where' key implies a 'source' of 'document', while the presence of a 'urls' key implies
+		 * a 'source' of 'list'.
+		 */
+		if (
+			( ! isset( $rule['where'] ) && ! isset( $rule['urls'] ) ) ||
+			( isset( $rule['where'] ) && isset( $rule['urls'] ) )
+		) {
+			_doing_it_wrong(
+				__METHOD__,
+				sprintf(
+					/* translators: 1: allowed key, 2: alternative allowed key */
+					__( 'A speculation rule must include either a "%1$s" key or a "%2$s" key, but not both.' ),
+					'where',
+					'urls'
+				),
+				'6.8.0'
+			);
+			return false;
+		}
+		if ( isset( $rule['source'] ) ) {
+			if ( ! self::is_valid_source( $rule['source'] ) ) {
+				_doing_it_wrong(
+					__METHOD__,
+					sprintf(
+						/* translators: %s: invalid source value */
+						__( 'The value "%s" is not a valid source for a speculation rule.' ),
+						esc_html( $rule['source'] )
+					),
+					'6.8.0'
+				);
+				return false;
+			}
+
+			if ( 'list' === $rule['source'] && isset( $rule['where'] ) ) {
+				_doing_it_wrong(
+					__METHOD__,
+					sprintf(
+						/* translators: 1: source value, 2: forbidden key */
+						__( 'A speculation rule of source "%1$s" must not include a "%2$s" key.' ),
+						'list',
+						'where'
+					),
+					'6.8.0'
+				);
+				return false;
+			}
+
+			if ( 'document' === $rule['source'] && isset( $rule['urls'] ) ) {
+				_doing_it_wrong(
+					__METHOD__,
+					sprintf(
+						/* translators: 1: source value, 2: forbidden key */
+						__( 'A speculation rule of source "%1$s" must not include a "%2$s" key.' ),
+						'document',
+						'urls'
+					),
+					'6.8.0'
+				);
+				return false;
+			}
+		}
+
+		// If there is an 'eagerness' key specified, make sure it's valid.
+		if ( isset( $rule['eagerness'] ) ) {
+			if ( ! self::is_valid_eagerness( $rule['eagerness'] ) ) {
+				_doing_it_wrong(
+					__METHOD__,
+					sprintf(
+						/* translators: %s: invalid eagerness value */
+						__( 'The value "%s" is not a valid eagerness for a speculation rule.' ),
+						esc_html( $rule['eagerness'] )
+					),
+					'6.8.0'
+				);
+				return false;
+			}
+
+			if ( isset( $rule['where'] ) && 'immediate' === $rule['eagerness'] ) {
+				_doing_it_wrong(
+					__METHOD__,
+					sprintf(
+						/* translators: %s: forbidden eagerness value */
+						__( 'The eagerness value "%s" is forbidden for document-level speculation rules.' ),
+						'immediate'
+					),
+					'6.8.0'
+				);
+				return false;
+			}
+		}
+
+		if ( ! isset( $this->rules_by_mode[ $mode ] ) ) {
+			$this->rules_by_mode[ $mode ] = array();
+		}
+
+		$this->rules_by_mode[ $mode ][ $id ] = $rule;
+		return true;
+	}
+
+	/**
+	 * Checks whether a speculation rule for the given mode and ID already exists.
+	 *
+	 * @since 6.8.0
+	 *
+	 * @param string $mode Speculative loading mode. Either 'prefetch' or 'prerender'.
+	 * @param string $id   Unique string identifier for the speculation rule.
+	 * @return bool True if the rule already exists, false otherwise.
+	 */
+	public function has_rule( string $mode, string $id ): bool {
+		return isset( $this->rules_by_mode[ $mode ][ $id ] );
+	}
+
+	/**
+	 * Returns the speculation rules data ready to be JSON-encoded.
+	 *
+	 * @since 6.8.0
+	 *
+	 * @return array<string, array<string, mixed>> Speculation rules data.
+	 */
+	#[ReturnTypeWillChange]
+	public function jsonSerialize() {
+		// Strip the IDs for JSON output, since they are not relevant for the Speculation Rules API.
+		return array_map(
+			static function ( array $rules ) {
+				return array_values( $rules );
+			},
+			array_filter( $this->rules_by_mode )
+		);
+	}
+
+	/**
+	 * Checks whether the given ID is valid.
+	 *
+	 * @since 6.8.0
+	 *
+	 * @param string $id Unique string identifier for the speculation rule.
+	 * @return bool True if the ID is valid, false otherwise.
+	 */
+	private function is_valid_id( string $id ): bool {
+		return (bool) preg_match( '/^[a-z][a-z0-9_-]+$/', $id );
+	}
+
+	/**
+	 * Checks whether the given speculation rules mode is valid.
+	 *
+	 * @since 6.8.0
+	 *
+	 * @param string $mode Speculation rules mode.
+	 * @return bool True if valid, false otherwise.
+	 */
+	public static function is_valid_mode( string $mode ): bool {
+		return isset( self::$mode_allowlist[ $mode ] );
+	}
+
+	/**
+	 * Checks whether the given speculation rules eagerness is valid.
+	 *
+	 * @since 6.8.0
+	 *
+	 * @param string $eagerness Speculation rules eagerness.
+	 * @return bool True if valid, false otherwise.
+	 */
+	public static function is_valid_eagerness( string $eagerness ): bool {
+		return isset( self::$eagerness_allowlist[ $eagerness ] );
+	}
+
+	/**
+	 * Checks whether the given speculation rules source is valid.
+	 *
+	 * @since 6.8.0
+	 *
+	 * @param string $source Speculation rules source.
+	 * @return bool True if valid, false otherwise.
+	 */
+	public static function is_valid_source( string $source ): bool {
+		return isset( self::$source_allowlist[ $source ] );
+	}
+}