Add speculative loading support

src/wp-includes/class-wp-url-pattern-prefixer.php

@@ -0,0 +1,131 @@
+<?php
+/**
+ * Class 'WP_URL_Pattern_Prefixer'.
+ *
+ * @package WordPress
+ * @subpackage Speculative Loading
+ * @since 6.8.0
+ */
+
+/**
+ * Class for prefixing URL patterns.
+ *
+ * This class is intended primarily for use as part of the speculative loading feature.
+ *
+ * @since 6.8.0
+ * @access private
+ */
+class WP_URL_Pattern_Prefixer {
+
+	/**
+	 * Map of `$context_string => $base_path` pairs.
+	 *
+	 * @since 6.8.0
+	 * @var array<string, string>
+	 */
+	private $contexts;
+
+	/**
+	 * Constructor.
+	 *
+	 * @since 6.8.0
+	 *
+	 * @param array<string, string> $contexts Optional. Map of `$context_string => $base_path` pairs. Default is the
+	 *                                        contexts returned by the
+	 *                                        {@see WP_URL_Pattern_Prefixer::get_default_contexts()} method.
+	 */
+	public function __construct( array $contexts = array() ) {
+		if ( count( $contexts ) > 0 ) {
+			$this->contexts = array_map(
+				static function ( string $str ): string {
+					return self::escape_pattern_string( trailingslashit( $str ) );
+				},
+				$contexts
+			);
+		} else {
+			$this->contexts = self::get_default_contexts();
+		}
+	}
+
+	/**
+	 * Prefixes the given URL path pattern with the base path for the given context.
+	 *
+	 * This ensures that these path patterns work correctly on WordPress subdirectory sites, for example in a multisite
+	 * network, or when WordPress itself is installed in a subdirectory of the hostname.
+	 *
+	 * The given URL path pattern is only prefixed if it does not already include the expected prefix.
+	 *
+	 * @since 6.8.0
+	 *
+	 * @param string $path_pattern URL pattern starting with the path segment.
+	 * @param string $context      Optional. Context to use for prefixing the path pattern. Default 'home'.
+	 * @return string URL pattern, prefixed as necessary.
+	 */
+	public function prefix_path_pattern( string $path_pattern, string $context = 'home' ): string {
+		// If context path does not exist, the context is invalid.
+		if ( ! isset( $this->contexts[ $context ] ) ) {
+			_doing_it_wrong(
+				__FUNCTION__,
+				esc_html(
+					sprintf(
+						/* translators: %s: context string */
+						__( 'Invalid URL pattern context %s.' ),
+						$context
+					)
+				),
+				'6.8.0'
+			);
+			return $path_pattern;
+		}
+
+		// In the event that the context path contains a :, ? or # (which can cause the URL pattern parser to
+		// switch to another state, though only the latter two should be percent encoded anyway), we need to
+		// additionally enclose it in grouping braces. The final forward slash (trailingslashit ensures there is
+		// one) affects the meaning of the * wildcard, so is left outside the braces.
+		$context_path         = $this->contexts[ $context ];
+		$escaped_context_path = $context_path;
+		if ( strcspn( $context_path, ':?#' ) !== strlen( $context_path ) ) {
+			$escaped_context_path = '{' . substr( $context_path, 0, -1 ) . '}/';
+		}
+
+		// If the path already starts with the context path (including '/'), remove it first
+		// since it is about to be added back.
+		if ( str_starts_with( $path_pattern, $context_path ) ) {
+			$path_pattern = substr( $path_pattern, strlen( $context_path ) );
+		}
+
+		return $escaped_context_path . ltrim( $path_pattern, '/' );
+	}
+
+	/**
+	 * Returns the default contexts used by the class.
+	 *
+	 * @since 6.8.0
+	 *
+	 * @return array<string, string> Map of `$context_string => $base_path` pairs.
+	 */
+	public static function get_default_contexts(): array {
+		return array(
+			'home'       => self::escape_pattern_string( trailingslashit( (string) wp_parse_url( home_url( '/' ), PHP_URL_PATH ) ) ),
+			'site'       => self::escape_pattern_string( trailingslashit( (string) wp_parse_url( site_url( '/' ), PHP_URL_PATH ) ) ),
+			'uploads'    => self::escape_pattern_string( trailingslashit( (string) wp_parse_url( wp_upload_dir( null, false )['baseurl'], PHP_URL_PATH ) ) ),
+			'content'    => self::escape_pattern_string( trailingslashit( (string) wp_parse_url( content_url(), PHP_URL_PATH ) ) ),
+			'plugins'    => self::escape_pattern_string( trailingslashit( (string) wp_parse_url( plugins_url(), PHP_URL_PATH ) ) ),
+			'template'   => self::escape_pattern_string( trailingslashit( (string) wp_parse_url( get_stylesheet_directory_uri(), PHP_URL_PATH ) ) ),
+			'stylesheet' => self::escape_pattern_string( trailingslashit( (string) wp_parse_url( get_template_directory_uri(), PHP_URL_PATH ) ) ),
+		);
+	}
+
+	/**
+	 * Escapes a string for use in a URL pattern component.
+	 *
+	 * @since 6.8.0
+	 * @see https://urlpattern.spec.whatwg.org/#escape-a-pattern-string
+	 *
+	 * @param string $str String to be escaped.
+	 * @return string String with backslashes added where required.
+	 */
+	private static function escape_pattern_string( string $str ): string {
+		return addcslashes( $str, '+*?:{}()\\' );
+	}
+}

src/wp-includes/default-filters.php

@@ -352,6 +352,7 @@
 add_action( 'wp_head', 'wp_shortlink_wp_head', 10, 0 );
 add_action( 'wp_head', 'wp_custom_css_cb', 101 );
 add_action( 'wp_head', 'wp_site_icon', 99 );
+add_action( 'wp_footer', 'wp_print_speculation_rules' );
 add_action( 'wp_footer', 'wp_print_footer_scripts', 20 );
 add_action( 'template_redirect', 'wp_shortlink_header', 11, 0 );
 add_action( 'wp_print_footer_scripts', '_wp_footer_scripts' );

src/wp-includes/speculative-loading.php

@@ -0,0 +1,248 @@
+<?php
+/**
+ * Speculative loading functions.
+ *
+ * @package WordPress
+ * @subpackage Speculative Loading
+ * @since 6.8.0
+ */
+
+/**
+ * Returns the speculation rules configuration.
+ *
+ * @since 6.8.0
+ *
+ * @return array<string, string>|null Associative array with 'mode' and 'eagerness' keys, or null if speculative
+ *                                    loading is disabled.
+ */
+function wp_get_speculation_rules_configuration(): ?array {
+	$config = array(
+		'mode'      => 'auto',
+		'eagerness' => 'auto',
+	);
+
+	/**
+	 * Filters the way that speculation rules are configured.
+	 *
+	 * The Speculation Rules API is a web API that allows to automatically prefetch or prerender certain URLs on the
+	 * page, which can lead to near-instant page load times. This is also referred to as speculative loading.
+	 *
+	 * There are two aspects to the configuration:
+	 * * The "mode" (whether to "prefetch" or "prerender" URLs).
+	 * * The "eagerness" (whether to speculatively load URLs in an "eager", "moderate", or "conservative" way).
+	 *
+	 * By default, the speculation rules configuration is decided by WordPress Core ("auto"). This filter can be used
+	 * to force a certain configuration, which could for instance load URLs more or less eagerly.
+	 *
+	 * @since 6.8.0
+	 * @see https://developer.chrome.com/docs/web-platform/prerender-pages
+	 *
+	 * @param array<string, string>|null $config Associative array with 'mode' and 'eagerness' keys. The default value
+	 *                                           for both of them is 'auto'. Other possible values for 'mode' are
+	 *                                           'prefetch' and 'prerender'. Other possible values for 'eagerness' are
+	 *                                           'eager', 'moderate', and 'conservative'. Alternatively, you may
+	 *                                           return `null` to disable speculative loading entirely.
+	 */
+	$config = apply_filters( 'wp_speculation_rules_configuration', $config );
+
+	// Allow the value `null` to indicate that speculative loading is disabled.
+	if ( null === $config ) {
+		return null;
+	}
+
+	// Sanitize the configuration and replace 'auto' with current defaults.
+	$default_mode      = 'prefetch';
+	$default_eagerness = 'conservative';
+	if ( ! is_array( $config ) ) {
+		return array(
+			'mode'      => $default_mode,
+			'eagerness' => $default_eagerness,
+		);
+	}
+	if ( ! isset( $config['mode'] ) || 'auto' === $config['mode'] || ! wp_is_valid_speculation_rules_mode( $config['mode'] ) ) {
+		$config['mode'] = $default_mode;
+	}
+	if ( ! isset( $config['eagerness'] ) || 'auto' === $config['eagerness'] || ! wp_is_valid_speculation_rules_eagerness( $config['eagerness'] ) ) {
+		$config['eagerness'] = $default_eagerness;
+	}
+
+	return array(
+		'mode'      => $config['mode'],
+		'eagerness' => $config['eagerness'],
+	);
+}
+
+/**
+ * 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.
+ */
+function wp_is_valid_speculation_rules_mode( string $mode ): bool {
+	static $mode_allowlist = array(
+		'prefetch'  => true,
+		'prerender' => true,
+	);
+	return isset( $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.
+ */
+function wp_is_valid_speculation_rules_eagerness( string $eagerness ): bool {
+	static $eagerness_allowlist = array(
+		'eager'        => true,
+		'moderate'     => true,
+		'conservative' => true,
+	);
+	return isset( $eagerness_allowlist[ $eagerness ] );
+}
+
+/**
+ * Returns the full speculation rules data based on the given configuration.
+ *
+ * Plugins with features that rely on frontend URLs to exclude from prefetching or prerendering should use the
+ * {@see 'wp_speculation_rules_href_exclude_paths'} filter to ensure those URL patterns are excluded.
+ *
+ * @since 6.8.0
+ * @access private
+ *
+ * @param array<string, string> $configuration Associative array with 'mode' and 'eagerness' keys.
+ * @return array<string, array<int, array<string, mixed>>> Associative array of speculation rules by type.
+ */
+function wp_get_speculation_rules( array $configuration ): array {
+	// If the passed configuration is invalid, trigger a warning and fall back to the default configuration.
+	if (
+		! isset( $configuration['mode'] ) ||
+		! wp_is_valid_speculation_rules_mode( $configuration['mode'] ) ||
+		! isset( $configuration['eagerness'] ) ||
+		! wp_is_valid_speculation_rules_eagerness( $configuration['eagerness'] )
+	) {
+		_doing_it_wrong(
+			__FUNCTION__,
+			esc_html(
+				sprintf(
+					/* translators: %s is $configuration */
+					__( 'The %s parameter was provided with an invalid value.' ),
+					'$configuration'
+				)
+			),
+			'6.8.0'
+		);
+		$configuration = wp_get_speculation_rules_configuration();
+	}
+
+	$mode      = $configuration['mode'];
+	$eagerness = $configuration['eagerness'];
+
+	$prefixer = new WP_URL_Pattern_Prefixer();
+
+	$base_href_exclude_paths = array(
+		$prefixer->prefix_path_pattern( '/wp-login.php', 'site' ),
+		$prefixer->prefix_path_pattern( '/wp-admin/*', 'site' ),
+		$prefixer->prefix_path_pattern( '/*\\?*(^|&)_wpnonce=*', 'home' ),
+		$prefixer->prefix_path_pattern( '/*', 'uploads' ),
+		$prefixer->prefix_path_pattern( '/*', 'content' ),
+		$prefixer->prefix_path_pattern( '/*', 'plugins' ),
+		$prefixer->prefix_path_pattern( '/*', 'template' ),
+		$prefixer->prefix_path_pattern( '/*', 'stylesheet' ),
+	);
+
+	/**
+	 * Filters the paths for which speculative loading should be disabled.
+	 *
+	 * All paths should start in a forward slash, relative to the root document. The `*` can be used as a wildcard.
+	 * If the WordPress site is in a subdirectory, the exclude paths will automatically be prefixed as necessary.
+	 *
+	 * Note that WordPress always excludes certain path patterns such as `/wp-login.php` and `/wp-admin/*`, and those
+	 * cannot be modified using the filter.
+	 *
+	 * @since 6.8.0
+	 *
+	 * @param string[] $href_exclude_paths Additional path patterns to disable speculative loading for.
+	 * @param string   $mode               Mode used to apply speculative loading. Either 'prefetch' or 'prerender'.
+	 */
+	$href_exclude_paths = (array) apply_filters( 'wp_speculation_rules_href_exclude_paths', array(), $mode );
+
+	// Ensure that:
+	// 1. There are no duplicates.
+	// 2. The base paths cannot be removed.
+	// 3. The array has sequential keys (i.e. array_is_list()).
+	$href_exclude_paths = array_values(
+		array_unique(
+			array_merge(
+				$base_href_exclude_paths,
+				array_map(
+					static function ( string $href_exclude_path ) use ( $prefixer ): string {
+						return $prefixer->prefix_path_pattern( $href_exclude_path );
+					},
+					$href_exclude_paths
+				)
+			)
+		)
+	);
+
+	$rules = array(
+		array(
+			'source'    => 'document',
+			'where'     => array(
+				'and' => array(
+					// Include any URLs within the same site.
+					array(
+						'href_matches' => $prefixer->prefix_path_pattern( '/*' ),
+					),
+					// Except for excluded paths.
+					array(
+						'not' => array(
+							'href_matches' => $href_exclude_paths,
+						),
+					),
+					// Also exclude rel=nofollow links, as certain plugins use that on their links that perform an action.
+					array(
+						'not' => array(
+							'selector_matches' => 'a[rel~="nofollow"]',
+						),
+					),
+					// Last but not least, exclude links that are explicitly marked to opt out.
+					array(
+						'not' => array(
+							'selector_matches' => ".no-{$mode}",
+						),
+					),
+				),
+			),
+			'eagerness' => $eagerness,
+		),
+	);
+
+	return array( $mode => $rules );
+}
+
+/**
+ * Prints the speculation rules.
+ *
+ * For browsers that do not support speculation rules yet, the `script[type="speculationrules"]` tag will be ignored.
+ *
+ * @since 6.8.0
+ * @access private
+ */
+function wp_print_speculation_rules(): void {
+	$configuration = wp_get_speculation_rules_configuration();
+	if ( null === $configuration ) {
+		return;
+	}
+
+	wp_print_inline_script_tag(
+		(string) wp_json_encode(
+			wp_get_speculation_rules( $configuration )
+		),
+		array( 'type' => 'speculationrules' )
+	);
+}

src/wp-settings.php

@@ -404,6 +404,8 @@
 require ABSPATH . WPINC . '/interactivity-api/class-wp-interactivity-api-directives-processor.php';
 require ABSPATH . WPINC . '/interactivity-api/interactivity-api.php';
 require ABSPATH . WPINC . '/class-wp-plugin-dependencies.php';
+require ABSPATH . WPINC . '/class-wp-url-pattern-prefixer.php';
+require ABSPATH . WPINC . '/speculative-loading.php';
 
 add_action( 'after_setup_theme', array( wp_script_modules(), 'add_hooks' ) );
 add_action( 'after_setup_theme', array( wp_interactivity(), 'add_hooks' ) );