Add site health check to detect blocked REST API and short-circuit optimization when Inaccessible #1762

b1ink0 · 2024-12-19T17:59:46Z

Summary

Relevant technical choices

Adds a site health check to verify the availability and status of the /optimization-detective/v1/url-metrics:store REST API endpoint. The process will short-circuit if the endpoint is inaccessible.
A site health check will run weekly and update the status.
Based on the status, a notice will be displayed on the plugins page.

Scenarios:

When the health check passes
When the REST API endpoint returns a forbidden error
When the REST API endpoint returns an unauthorized error
When other errors are encountered

westonruter

Should there be a plugin activation hook added as well which does add_option() for the new option and then also kicks off (or schedules) a REST API check? Ideally there would be a warning shown immediately after activating the plugin (e.g. on the plugins list table screen) whether the REST API is working so that the user doesn't have to discover it later via Site Health.

westonruter · 2024-12-19T18:26:02Z

plugins/optimization-detective/includes/site-health/load.php

Maybe put site-health in the root directory instead of inside includes since there are no other directories in there?

I thought in future if we added something like admin dashboard for managing URL metrics or any other admin dashboard related thing then it would be better to add that feature in includes/admin. But we can just refactor things later when we need it so moving site-health to root makes sence.

Yeah, let's put it in the root for now since all other directories are there.

if we added something like admin dashboard for managing URL metrics or any other admin dashboard related thing

Aside: I did put together a rough utility plugin for this: https://github.com/westonruter/od-admin-ui

westonruter · 2024-12-19T18:27:41Z

plugins/optimization-detective/includes/site-health/rest-api/helper.php

+			'<p>%s</p>',
+			esc_html__( 'The Optimization Detective endpoint could not be reached. This might mean the REST API is disabled or blocked.', 'optimization-detective' )
+		);
+		update_option(


This is the first PR that adds an option to to Optimization Detective. We'll need to make sure that the relevant delete_option() calls get added to the plugin's uninstall.php.

westonruter · 2024-12-19T18:29:24Z

plugins/optimization-detective/optimization.php

+	// Disable detection if the REST API is disabled.
+	$od_rest_api_info = get_option( 'od_rest_api_info' );
+	if ( is_array( $od_rest_api_info ) && isset( $od_rest_api_info['available'] ) ) {
+		$needs_detection = (bool) $od_rest_api_info['available'];
+	}
+


Actually, this check wouldn't make sense here. It should rather be done in od_maybe_add_template_output_buffer_filter() to short-circuit if the REST API it is not available.

westonruter · 2024-12-19T18:32:01Z

plugins/optimization-detective/includes/site-health/rest-api/helper.php

+		update_option(
+			'od_rest_api_info',
+			array(
+				'status'    => 'error',


Should the $error->get_message() and maybe $error->get_code() be stored here?

westonruter · 2024-12-19T18:34:40Z

plugins/optimization-detective/includes/site-health/rest-api/helper.php

+		update_option(
+			'od_rest_api_info',
+			array(
+				'status'    => 'forbidden',


Instead of storing the string, what about storing the $status_code instead?

westonruter · 2024-12-19T18:35:07Z

plugins/optimization-detective/includes/site-health/rest-api/helper.php

+				'available' => false,
+			)
+		);
+	}


The else condition should be added as an error result as well. Here especially the $status_code could be used.

westonruter · 2024-12-19T18:38:03Z

plugins/optimization-detective/includes/site-health/rest-api/helper.php

+		&& count( $expected_params ) === count( array_intersect( $data['data']['params'], $expected_params ) )
+	) {
+		// The REST API endpoint is available.
+		update_option(


Instead of having update_option() appearing in multiple places, each condition could populate an $info variable which is then sent into update_option() once at the end of the function.

…ndition

westonruter · 2024-12-20T21:13:28Z

plugins/optimization-detective/site-health/rest-api/helper.php

+		wp_schedule_event( time(), 'hourly', 'od_rest_api_health_check_event' );
+	}
+}
+add_action( 'wp', 'od_schedule_rest_api_health_check' );


Is this a best practice? Should it rather go in admin_init to avoid frontend writes? I'm not sure what others do here.

I think scheduling on plugin activation hook will be better than admin_init.

The problem is that the plugin activation hook doesn't work when network-activating a plugin in multisite.

In looking at WP_Site_Health, it goes ahead and schedules an event even for frontend requests, since it calls its maybe_create_scheduled_event method in the constructor. And the instance is loaded in wp-settings.php. Nevertheless, since a database write is involved, it is preferable if event scheduling happens via an admin request and not unauthenticated frontend requests.

westonruter · 2024-12-20T21:13:42Z

plugins/optimization-detective/site-health/rest-api/helper.php

+ */
+function od_schedule_rest_api_health_check(): void {
+	if ( ! (bool) wp_next_scheduled( 'od_rest_api_health_check_event' ) ) {
+		wp_schedule_event( time(), 'hourly', 'od_rest_api_health_check_event' );


I think hourly is too much. Maybe weekly would make sense.

I currently have it set to run weekly, but that might be too infrequent. If a configuration change disables the REST API, it could take an entire week for user to detect the issue. I believe running it daily would be a better choice.

I think weekly is fine. It's not likely that a user would be changing the availability of the REST API. If we check at the moment that a plugin is activated, and then check weekly thereafter, then this should be good. Note that Site Health's own checks run on a weekly basis via the wp_site_health_scheduled_check action.

…ck fails

…tion

github-actions · 2024-12-24T14:12:43Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

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

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

westonruter

Sorry for the delay in reviewing. Just getting back from the holidays.

westonruter · 2025-01-07T00:17:44Z

plugins/optimization-detective/load.php

+
+			register_activation_hook(
+				__FILE__,
+				static function () use ( $bootstrap ): void {
+					/*
+					 * The activation hook is called before the init action, so the plugin is not loaded yet. This
+					 * means that the plugin must be bootstrapped here to run the activation logic.
+					 */
+					$bootstrap();
+					od_rest_api_health_check_plugin_activation();
+				}
+			);


See note below about how the activation hook does not run when network-activating a plugin. I think this should switch to use admin_init. For example, add this to hooks.php:

add_action( 'admin_init', 'od_rest_api_health_check_plugin_activation' );

westonruter · 2025-01-07T00:21:34Z

plugins/optimization-detective/site-health/rest-api/hooks.php

+add_filter( 'site_status_tests', 'od_optimization_detective_add_rest_api_test' );
+
+// Hook for the scheduled REST API health check.
+add_action( 'od_rest_api_health_check_event', 'od_run_scheduled_rest_api_health_check' );
+add_action( 'after_plugin_row_meta', 'od_rest_api_health_check_admin_notice', 30 );


What about moving these to a section in the plugin's existing hooks.php?

westonruter · 2025-01-07T00:22:33Z

plugins/optimization-detective/site-health/rest-api/hooks.php

+/**
+ * Adds the Optimization Detective REST API check to site health tests.
+ *
+ * @since n.e.x.t
+ *
+ * @param array{direct: array<string, array{label: string, test: string}>} $tests Site Health Tests.
+ * @return array{direct: array<string, array{label: string, test: string}>} Amended tests.
+ */
+function od_optimization_detective_add_rest_api_test( array $tests ): array {
+	$tests['direct']['optimization_detective_rest_api'] = array(
+		'label' => __( 'Optimization Detective REST API Endpoint Availability', 'optimization-detective' ),
+		'test'  => 'od_optimization_detective_rest_api_test',
+	);
+
+	return $tests;
+}


I think this could be moved to a /site-health.php file.

westonruter · 2025-01-07T00:23:21Z

plugins/optimization-detective/site-health/rest-api/helper.php

Since there is only one Site Health test, what about eliminating the load.php file and moving this file to /site-health.php?

westonruter · 2025-01-07T00:23:48Z

plugins/optimization-detective/load.php

@@ -127,5 +139,8 @@ class_alias( OD_URL_Metric_Group_Collection::class, 'OD_URL_Metrics_Group_Collec

 		// Add hooks for the above requires.
 		require_once __DIR__ . '/hooks.php';
+
+		// Load site health checks.
+		require_once __DIR__ . '/site-health/load.php';


As noted below, I think the directory can be removed in favor of just a simpler site-health.php for now:

Suggested change

require_once __DIR__ . '/site-health/load.php';

require_once __DIR__ . '/site-health.php';

westonruter · 2025-01-07T00:24:49Z

plugins/optimization-detective/site-health/load.php

I think this file can be removed in favor of moving the /site-health/rest-api/helper.php file below up to /site-health.php.

adamsilverstein · 2025-01-07T14:59:06Z

plugins/optimization-detective/site-health/rest-api/helper.php

+ */
+function od_schedule_rest_api_health_check(): void {
+	if ( ! (bool) wp_next_scheduled( 'od_rest_api_health_check_event' ) ) {
+		wp_schedule_event( time(), 'weekly', 'od_rest_api_health_check_event' );


Do we really need to check this weekly? That seems excessive as it is very unlikely to change. How about checking when the plugin is activated and when users visit the Site Health screen?

adamsilverstein · 2025-01-07T15:01:19Z

plugins/optimization-detective/site-health/rest-api/helper.php

+	if ( ! (bool) get_option( 'od_rest_api_info' ) ) {
+		add_option( 'od_rest_api_info', array() );
+	}
+	od_schedule_rest_api_health_check();


just run check directly, caching results?

b1ink0 added 7 commits December 19, 2024 18:34

Add REST API health check for Optimization Detective

88952a5

Improve error message of site health check

4bff9fe

Add scheduled health check for Optimization Detective REST API

56d769a

Save site health check status for Optimization Detective REST API

ba911e1

Add test for when REST API is available

12a229c

Add tests for REST API unauthorized error handling

a0f460d

Add test for REST API forbidden error handling

c29cb7c

b1ink0 changed the title ~~Add/site health check for od rest api~~ Optimization Detective can be blocked from working due to sites disabling the REST API Dec 19, 2024

westonruter reviewed Dec 19, 2024

View reviewed changes

westonruter added this to the optimization-detective n.e.x.t milestone Dec 19, 2024

westonruter added [Type] Enhancement A suggestion for improvement of an existing feature [Plugin] Optimization Detective Issues for the Optimization Detective plugin labels Dec 19, 2024

b1ink0 added 6 commits December 20, 2024 18:04

Refactor to move site-health directory to plugin root directory

8d8ae3e

Clear site health check data during plugin uninstallation

422a5bf

Move REST API availability check to appropriate function

0bc74f7

Add error message and error code to option

36042fd

Refactor to store status code instead of string, Add fallback else co…

ad21df8

…ndition

Refactor to only use update_option once

0bba468

b1ink0 changed the title ~~Optimization Detective can be blocked from working due to sites disabling the REST API~~ Add site health check to detect blocked REST API and short-circuit optimization when Inaccessible Dec 20, 2024

westonruter reviewed Dec 20, 2024

View reviewed changes

b1ink0 added 7 commits December 23, 2024 19:07

Add activation hook to initialize option value

e1b9004

Move scheduling to activation hook

dbede65

Change health check scheduling from hourly to weekly

2b2ca3e

Run REST API health check on plugin activation, Display notice if che…

e7c1001

…ck fails

Move activation logic to separate function

7e4e057

Refactor activation logic to directly call REST API health check func…

a2baa65

…tion

Merge branch 'trunk' into add/site-health-check-for-od-rest-api

e1ec10c

b1ink0 marked this pull request as ready for review December 24, 2024 14:12

b1ink0 requested a review from felixarntz as a code owner December 24, 2024 14:12

b1ink0 requested a review from westonruter December 24, 2024 14:12

Improve site health status messages for clarity and consistency

48c83a5

westonruter requested changes Jan 7, 2025

View reviewed changes

adamsilverstein reviewed Jan 7, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add site health check to detect blocked REST API and short-circuit optimization when Inaccessible #1762

Add site health check to detect blocked REST API and short-circuit optimization when Inaccessible #1762

b1ink0 commented Dec 19, 2024 •

edited

Loading

westonruter left a comment

westonruter Dec 19, 2024

b1ink0 Dec 19, 2024

westonruter Dec 19, 2024

westonruter Dec 19, 2024

westonruter Dec 19, 2024

westonruter Dec 19, 2024

westonruter Dec 19, 2024

westonruter Dec 19, 2024

westonruter Dec 19, 2024

westonruter Dec 20, 2024

b1ink0 Dec 23, 2024

westonruter Jan 6, 2025

westonruter Jan 7, 2025

westonruter Dec 20, 2024

b1ink0 Dec 24, 2024

westonruter Jan 7, 2025

github-actions bot commented Dec 24, 2024

westonruter left a comment

westonruter Jan 7, 2025

westonruter Jan 7, 2025

westonruter Jan 7, 2025

westonruter Jan 7, 2025

westonruter Jan 7, 2025

westonruter Jan 7, 2025

adamsilverstein Jan 7, 2025

adamsilverstein Jan 7, 2025

	require_once __DIR__ . '/site-health/load.php';
	require_once __DIR__ . '/site-health.php';

Add site health check to detect blocked REST API and short-circuit optimization when Inaccessible #1762

Are you sure you want to change the base?

Add site health check to detect blocked REST API and short-circuit optimization when Inaccessible #1762

Conversation

b1ink0 commented Dec 19, 2024 • edited Loading

Summary

Relevant technical choices

Scenarios:

westonruter left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

github-actions bot commented Dec 24, 2024

westonruter left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

b1ink0 commented Dec 19, 2024 •

edited

Loading