Merge pull request #2097 from WordPress/add/authenticated-speculative-loading

Add Speculative Loading opt-in for authenticated requests

Co-authored-by: westonruter <[email protected]>
Co-authored-by: swissspidy <[email protected]>
Co-authored-by: felixarntz <[email protected]>

Author: 3 people

plugins/speculation-rules/hooks.php

@@ -12,6 +12,53 @@
 }
 // @codeCoverageIgnoreEnd
 
+/**
+ * Determines whether Speculative Loading is enabled.
+ *
+ * @since n.e.x.t
+ *
+ * @return bool Whether enabled.
+ */
+function plsr_is_speculative_loading_enabled(): bool {
+	$option = plsr_get_stored_setting_value();
+
+	// Disabled if the user is logged in, unless the setting explicitly allows the current user's role.
+	if (
+		is_user_logged_in()
+		&&
+		'any' !== $option['authentication']
+		&&
+		( ! current_user_can( 'manage_options' ) || 'logged_out_and_admins' !== $option['authentication'] )
+	) {
+		return false;
+	}
+
+	// Disable if pretty permalinks are not enabled, unless explicitly overridden by the filter.
+	if (
+		! (bool) get_option( 'permalink_structure' )
+		&&
+		/**
+		 * Filters whether speculative loading should be enabled even though the site does not use pretty permalinks.
+		 *
+		 * Since query parameters are commonly used by plugins for dynamic behavior that can change state, ideally any
+		 * such URLs are excluded from speculative loading. If the site does not use pretty permalinks though, they are
+		 * impossible to recognize. Therefore, speculative loading is disabled by default for those sites.
+		 *
+		 * For site owners of sites without pretty permalinks that are certain their site is not using such a pattern,
+		 * this filter can be used to still enable speculative loading at their own risk.
+		 *
+		 * @since 1.4.0
+		 *
+		 * @param bool $enabled Whether speculative loading is enabled even without pretty permalinks.
+		 */
+		! apply_filters( 'plsr_enabled_without_pretty_permalinks', false )
+	) {
+		return false;
+	}
+
+	return true;
+}
+
 // Conditionally use either the WordPress Core API, or load the plugin's API implementation otherwise.
 if ( function_exists( 'wp_get_speculation_rules_configuration' ) ) {
 	require_once __DIR__ . '/wp-core-api.php';

plugins/speculation-rules/plugin-api.php

@@ -130,34 +130,10 @@ static function ( string $href_exclude_path ) use ( $prefixer ): string {
  * @since 1.0.0
  */
 function plsr_print_speculation_rules(): void {
-	// Skip speculative loading for logged-in users.
-	if ( is_user_logged_in() ) {
+	if ( ! plsr_is_speculative_loading_enabled() ) {
 		return;
 	}
 
-	// Skip speculative loading for sites without pretty permalinks, unless explicitly enabled.
-	if ( ! (bool) get_option( 'permalink_structure' ) ) {
-		/**
-		 * Filters whether speculative loading should be enabled even though the site does not use pretty permalinks.
-		 *
-		 * Since query parameters are commonly used by plugins for dynamic behavior that can change state, ideally any
-		 * such URLs are excluded from speculative loading. If the site does not use pretty permalinks though, they are
-		 * impossible to recognize. Therefore speculative loading is disabled by default for those sites.
-		 *
-		 * For site owners of sites without pretty permalinks that are certain their site is not using such a pattern,
-		 * this filter can be used to still enable speculative loading at their own risk.
-		 *
-		 * @since 1.4.0
-		 *
-		 * @param bool $enabled Whether speculative loading is enabled even without pretty permalinks.
-		 */
-		$enabled = (bool) apply_filters( 'plsr_enabled_without_pretty_permalinks', false );
-
-		if ( ! $enabled ) {
-			return;
-		}
-	}
-
 	wp_print_inline_script_tag(
 		(string) wp_json_encode( plsr_get_speculation_rules() ),
 		array( 'type' => 'speculationrules' )

plugins/speculation-rules/readme.txt

@@ -13,6 +13,8 @@ Enables browsers to speculatively prerender or prefetch pages to achieve near-in
 
 This plugin adds support for the [Speculation Rules API](https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API), which allows defining rules by which certain URLs are dynamically prefetched or prerendered. This core Speculative Loading functionality was [merged into WordPress 6.8](https://make.wordpress.org/core/2025/03/06/speculative-loading-in-6-8/), but it only prefetches with conservative eagerness by default. In contrast, this plugin defaults to prerendering with moderate eagerness (i.e. when interacting with a link), and it provides a user interface to customize the mode and eagerness via the "Speculative Loading" section on the _Settings > Reading_ admin screen.
 
+By default, speculative loading is only enabled for logged-out users, since unauthenticated pages are typically only eligible for caching and so more efficient to prefetch/prerender. This means that sites with frequent logged-in users on the frontend—such as e-commerce, forums, or membership sites—will not benefit from the feature. If your server can handle the additional load (for example, with persistent object caching), you can opt in to enable speculative loading for all logged-in users or for administrators only. This setting exclusively affects frontend pages; admin screens are always excluded.
+
 A filter can be used to exclude certain URL paths from being eligible for prefetching and prerendering (see FAQ section). Alternatively, you can add the `no-prerender` CSS class to any link (`<a>` tag) that should not be prerendered. See FAQ for more information.
 
 = Browser support =

plugins/speculation-rules/settings.php

@@ -41,22 +41,39 @@ function plsr_get_eagerness_labels(): array {
 	);
 }
 
+/**
+ * Returns the available options for the Speculative Loading authentication and their labels.
+ *
+ * @since n.e.x.t
+ *
+ * @return array{ logged_out: string, logged_out_and_admins: string, any: string } Associative array of `$authentication => $label` pairs.
+ */
+function plsr_get_authentication_labels(): array {
+	return array(
+		'logged_out'            => _x( 'Logged-out visitors only (default)', 'setting label', 'speculation-rules' ),
+		'logged_out_and_admins' => _x( 'Administrators and logged-out visitors', 'setting label', 'speculation-rules' ),
+		'any'                   => _x( 'Any user (logged-in or logged-out)', 'setting label', 'speculation-rules' ),
+	);
+}
+
 /**
  * Returns the default setting value for Speculative Loading configuration.
  *
  * @since 1.0.0
  *
- * @return array{ mode: 'prerender', eagerness: 'moderate' } {
+ * @return array{ mode: 'prerender', eagerness: 'moderate', authentication: 'logged_out' } {
  *     Default setting value.
  *
- *     @type string $mode      Mode.
- *     @type string $eagerness Eagerness.
+ *     @type string $mode           Mode.
+ *     @type string $eagerness      Eagerness.
+ *     @type string $authentication Authentication.
  * }
  */
 function plsr_get_setting_default(): array {
 	return array(
-		'mode'      => 'prerender',
-		'eagerness' => 'moderate',
+		'mode'           => 'prerender',
+		'eagerness'      => 'moderate',
+		'authentication' => 'logged_out',
 	);
 }
 
@@ -65,11 +82,12 @@ function plsr_get_setting_default(): array {
  *
  * @since 1.4.0
  *
- * @return array{ mode: 'prefetch'|'prerender', eagerness: 'conservative'|'moderate'|'eager' } {
+ * @return array{ mode: 'prefetch'|'prerender', eagerness: 'conservative'|'moderate'|'eager', authentication: 'logged_out'|'logged_out_and_admins'|'any' } {
  *     Stored setting value.
  *
- *     @type string $mode      Mode.
- *     @type string $eagerness Eagerness.
+ *     @type string $mode           Mode.
+ *     @type string $eagerness      Eagerness.
+ *     @type string $authentication Authentication.
  * }
  */
 function plsr_get_stored_setting_value(): array {
@@ -83,11 +101,12 @@ function plsr_get_stored_setting_value(): array {
  * @todo  Consider whether the JSON schema for the setting could be reused here.
  *
  * @param mixed $input Setting to sanitize.
- * @return array{ mode: 'prefetch'|'prerender', eagerness: 'conservative'|'moderate'|'eager' } {
+ * @return array{ mode: 'prefetch'|'prerender', eagerness: 'conservative'|'moderate'|'eager', authentication: 'logged_out'|'logged_out_and_admins'|'any' } {
  *     Sanitized setting.
  *
- *     @type string $mode      Mode.
- *     @type string $eagerness Eagerness.
+ *     @type string $mode           Mode.
+ *     @type string $eagerness      Eagerness.
+ *     @type string $authentication Authentication.
  * }
  */
 function plsr_sanitize_setting( $input ): array {
@@ -107,6 +126,9 @@ function plsr_sanitize_setting( $input ): array {
 	if ( ! in_array( $value['eagerness'], array_keys( plsr_get_eagerness_labels() ), true ) ) {
 		$value['eagerness'] = $default_value['eagerness'];
 	}
+	if ( ! in_array( $value['authentication'], array_keys( plsr_get_authentication_labels() ), true ) ) {
+		$value['authentication'] = $default_value['authentication'];
+	}
 
 	return $value;
 }
@@ -130,16 +152,21 @@ function plsr_register_setting(): void {
 				'schema' => array(
 					'type'                 => 'object',
 					'properties'           => array(
-						'mode'      => array(
+						'mode'           => array(
 							'description' => __( 'Whether to prefetch or prerender URLs.', 'speculation-rules' ),
 							'type'        => 'string',
 							'enum'        => array_keys( plsr_get_mode_labels() ),
 						),
-						'eagerness' => array(
+						'eagerness'      => array(
 							'description' => __( 'The eagerness setting defines the heuristics based on which the loading is triggered. "Eager" will have the minimum delay to start speculative loads, "Conservative" increases the chance that only URLs the user actually navigates to are loaded.', 'speculation-rules' ),
 							'type'        => 'string',
 							'enum'        => array_keys( plsr_get_eagerness_labels() ),
 						),
+						'authentication' => array(
+							'description' => __( 'Only unauthenticated pages are typically served from cache. So in order to reduce load on the server, speculative loading is not enabled by default for logged-in users. If your server can handle the additional load, you can opt in to speculative loading for all logged-in users or just administrator users only. This only applies to pages on frontend; admin screens remain excluded.', 'speculation-rules' ),
+							'type'        => 'string',
+							'enum'        => array_keys( plsr_get_authentication_labels() ),
+						),
 					),
 					'additionalProperties' => false,
 				),
@@ -174,14 +201,18 @@ static function (): void {
 	);
 
 	$fields = array(
-		'mode'      => array(
+		'mode'           => array(
 			'title'       => __( 'Speculation Mode', 'speculation-rules' ),
 			'description' => __( 'Prerendering will lead to faster load times than prefetching. However, in case of interactive content, prefetching may be a safer choice.', 'speculation-rules' ),
 		),
-		'eagerness' => array(
+		'eagerness'      => array(
 			'title'       => __( 'Eagerness', 'speculation-rules' ),
 			'description' => __( 'The eagerness setting defines the heuristics based on which the loading is triggered. "Eager" will have the minimum delay to start speculative loads, "Conservative" increases the chance that only URLs the user actually navigates to are loaded.', 'speculation-rules' ),
 		),
+		'authentication' => array(
+			'title'       => __( 'User Authentication Status', 'speculation-rules' ),
+			'description' => __( 'Only unauthenticated pages are typically served from cache. So in order to reduce load on the server, speculative loading is not enabled by default for logged-in users. If your server can handle the additional load, you can opt in to speculative loading for all logged-in users or just administrator users only. This only applies to pages on frontend; admin screens remain excluded.', 'speculation-rules' ),
+		),
 	);
 	foreach ( $fields as $slug => $args ) {
 		add_settings_field(
@@ -205,7 +236,7 @@ static function (): void {
  * @since 1.0.0
  * @access private
  *
- * @param array{ field: 'mode'|'eagerness', title: non-empty-string, description: non-empty-string } $args {
+ * @param array{ field: 'mode'|'eagerness'|'authentication', title: non-empty-string, description: non-empty-string } $args {
  *     Associative array of arguments.
  *
  *     @type string $field       The slug of the sub setting controlled by the field.
@@ -223,6 +254,9 @@ function plsr_render_settings_field( array $args ): void {
 		case 'eagerness':
 			$choices = plsr_get_eagerness_labels();
 			break;
+		case 'authentication':
+			$choices = plsr_get_authentication_labels();
+			break;
 		default:
 			// Invalid (and this case should never occur).
 			return; // @codeCoverageIgnore