Add Speculative Loading opt-in for authenticated users

Author: westonruter

plugins/speculation-rules/hooks.php

@@ -12,6 +12,46 @@
 }
 // @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();
+	return (
+		(
+			! is_user_logged_in()
+			||
+			'any' === $option['authentication']
+			||
+			( current_user_can( 'manage_options' ) && 'logged_out_or_admins' === $option['authentication'] )
+		)
+		&&
+		(
+			(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.
+			 */
+			(bool) apply_filters( 'plsr_enabled_without_pretty_permalinks', false )
+		)
+	);
+}
+
 // 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/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_or_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_or_admins' => _x( 'Administrators or logged out visitors', 'setting label', 'speculation-rules' ),
+		'any'                  => _x( 'Any user (logged in or 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 $authenticaiton 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_or_admins'|'any' } {
  *     Stored setting value.
  *
- *     @type string $mode      Mode.
- *     @type string $eagerness Eagerness.
+ *     @type string $mode          Mode.
+ *     @type string $eagerness     Eagerness.
+ *     @type string $authenication 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_or_admins'|'any' } {
  *     Sanitized setting.
  *
- *     @type string $mode      Mode.
- *     @type string $eagerness Eagerness.
+ *     @type string $mode          Mode.
+ *     @type string $eagerness     Eagerness.
+ *     @type string $authenication 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 administrator users only.', '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'       => __( 'Authentication', '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 administrator users only.', '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

plugins/speculation-rules/wp-core-api.php

@@ -23,24 +23,20 @@
  * @return array<string, string>|null Filtered $config.
  */
 function plsr_filter_speculation_rules_configuration( $config ): ?array {
-	/*
-	 * If speculative loading should be disabled per the WordPress Core configuration, respect that value, unless pretty
-	 * permalinks are disabled and the plugin-specific filter to opt in to the feature despite that is set to true.
-	 * This is present for backward compatibility so that usage of the plugin-specific filter does not break.
-	 */
-	if (
-		null === $config &&
-		/** This filter is documented in plugin-api.php */
-		( (bool) get_option( 'permalink_structure' ) || ! (bool) apply_filters( 'plsr_enabled_without_pretty_permalinks', false ) )
-	) {
-		return null;
+	if ( ! is_array( $config ) ) {
+		// Because plugins do bad things.
+		$config = null;
 	}
 
-	$option = plsr_get_stored_setting_value();
-	return array(
-		'mode'      => $option['mode'],
-		'eagerness' => $option['eagerness'],
-	);
+	if ( plsr_is_speculative_loading_enabled() ) {
+		$option = plsr_get_stored_setting_value();
+		$config = array(
+			'mode'      => $option['mode'],
+			'eagerness' => $option['eagerness'],
+		);
+	}
+
+	return $config;
 }
 
 /**