Implement `fpm-server-requirement-status` API Endpoint for FPFE Health Check and Script Access Verification

[hussain-t]

Feature Description

Develop a new fpm-server-requirement-status API endpoint within the First-party mode infrastructure to verify connectivity to the FPFE /healthy endpoint and check direct PHP script access to the wp-content/plugins. This endpoint should assess whether the WordPress server can support First-party mode by performing the necessary checks.

See fpm-server-requirement-status from the REST API Controller and Health Check for First-Party Frontend sections for more details.

---

Do not alter or remove anything below. The following sections will be managed by moderators only.

Acceptance criteria

• A new GET REST API endpoint fpm-server-requirement-status should be created in the REST_First_Party_Mode_Settings_Controller class within the First-party mode infrastructure.
• The fpm-server-requirement-status endpoint should perform the following checks:
  • FPFE Health Check: Attempt to connect to the FPFE /healthy endpoint (e.g., https://g-1234.fps.goog/mpath/healthy) to verify that the server can make outbound requests required for First-party mode. The endpoint should expect a 200 status response with “ok” to confirm successful connectivity.
  • Direct PHP Script Access Check: Perform an HTTP request to confirm whether the server can directly access PHP files within the wp-content/plugins/google-site-kit/fpm directory.
• The endpoint should update and return the following properties in the googlesitekit_first_party_mode settings object based on the checks:
  • isFPMHealthy: Set to true if the FPFE health check passes; otherwise, set to false.
  • isScriptAccessEnabled: Set to true if the HTTP request to the PHP script is successful; otherwise, set to false.
• The endpoint should return a JSON response with the properties isFPMHealthy and isScriptAccessEnabled to allow the client to update the state directly.

Implementation Brief

• [x] Create a stub {plugin root}/fpm/measurement.php file.
  • This should accept a healthCheck query parameter and return ok if the query parameter is present. If not, it can return an empty response.
  • This script will have the Google-provided code merged into it in a later issue, https://github.com/google/site-kit-wp/issues/9665.
• [x] Add a new REST_Route in the REST_First_Party_Mode_Settings_Controller::get_rest_routes() method (added via https://github.com/google/site-kit-wp/issues/9625), with the following configuration:
  • URI: core/site/data/fpm-server-requirement-status
  • Method: WP_REST_Server::READABLE
  • Permissions: Permissions::MANAGE_OPTIONS
  • In the handler callback:
  • Define $is_fpm_healthy:
    • Use file_get_contents() to fetch the contents of https://g-1234.fps.goog/mpath/healthy.
    • If the response is the string 'ok', and the response code is 200, set $is_fpm_healthy to true. Otherwise, set it to false.
    • To check the response code, examine the $http_response_header variable which will be set locally after the file_get_contents() call.
  • Define $is_script_access_enabled:
    • Use file_get_contents() to fetch the contents of plugins_url( 'fpm/measurement.php', GOOGLESITEKIT_PLUGIN_MAIN_FILE ) with the healthCheck query parameter set to a truthy value.
    • If the response is the string 'ok' and the response code is 200, set $is_script_access_enabled to true. Otherwise, set it to false.
  • Merge $is_fpm_healthy and $is_script_access_enabled into the FPM settings as isFPMHealthy and isScriptAccessEnabled using the First_Party_Mode_Settings::merge() method.
  • Return an object with the isFPMHealthy and isScriptAccessEnabled properties.

Test Coverage

• Add test coverage for the new REST route.

QA Brief

Happy path

• Set up Site Kit with the firstPartyMode feature flag enabled.
• Use the following snippet in the JS console to make a request to the fpm-server-requirement-status endpoint:

  await googlesitekit.api.get('core','site','fpm-server-requirement-status', undefined, { useCache: false });

• Verify the isFPMHealthy and isScriptAccessEnabled properties are true in the response. The isEnabled property is expected to remain null.
• Verify the googlesitekit_first_party_mode option is set in the DB with the properties defined as above.

Unhappy paths

QA:Eng

Note that when testing on a local development environment, the measurement.php health check will work for a Local WP install, but it won't work for a WP Local Docker installation, this is because the hostname won't resolve to the correct IP address within the Docker container.

The easiest way to test the unhappy path scenarios is to manually modify the requested URLs in REST_First_Party_Mode_Controller. However it's also possible to test them by proxying the calls made by file_get_contents(). To do this, create a file in mu-plugins with the following content:

<?php

stream_context_set_default(
  array(
    'http' => array( 'proxy' => 'localhost:8080' ), // Set the addresses according to your local environment.
    'https' => array( 'proxy' => 'localhost:8080' ),
    'ssl' => array( 'verify_peer' => false ), // This may be necessary depending on your local environment.
  )
);

Follow the happy path test, but modify the requested URLs or use a proxy to intercept the calls and verify the isFPMHealthy and isScriptAccessEnabled properties are set to false under various erroneous conditions.

Changelog entry

• Add an fpm-server-requirement-status API endpoint to verify First-Party Mode readiness by performing FPFE health checks and verifying direct PHP script access.

[techanvil]

Hey @hussain-t, reviewing these AC has made me reconsider the endpoint name. I'd suggest a preferable name would be fpm-server-requirement-status so we can GET fpm-server-requirement-status which would be more aligned with the general RESTful approach with the HTTP verb and resource name making semantic sense.

I'd also suggest that it should directly return the is_fpm_health_check_failed and is_script_access_disabled properties, that way we can update the client-side state with them directly rather than needing to make another request to the settings endpoint when we call this one.

There's also the outstanding question of whether we actually rename is_fpm_health_check_failed and is_script_access_disabled as per https://github.com/google/site-kit-wp/issues/9625#issuecomment-2462850044.

[hussain-t]

Thanks, @techanvil! Overall, I agree with your suggestions, renaming the properties and the endpoint to fpm-server-requirement-status to make it clearer. I’d suggest keeping it as a POST since the endpoint performs checks and updates the server-side properties, even though it’s not directly taking data from the client. Let me know if that works!

[hussain-t]

Thanks for the suggestions, @techanvil 👍

[techanvil]

Thanks @hussain-t, a fair point about the use of POST. I think it could go either way but I'm happy enough keeping it a POST.

[hussain-t]

Thanks, @techanvil. After giving it some more thought, I think a GET request might suit this endpoint better, given that it retrieves the current server status without taking input from the client.

[techanvil]

Thanks @hussain-t. SGTM too, let's go with the GET, then.

[techanvil]

Thanks for updating the AC, @hussain-t. I've noticed there's one additional aspect that could use clarifying and potentially updating.

• Direct PHP Script Access Check: A test should confirm whether the server can directly access PHP files within the wp-content/plugins directory.

As per my comment on the design doc, I'd like to clarify the intention here, essentially I would advise making an HTTP request to check the script accessibility rather than a local filesystem level check, if that's not already the plan.

[hussain-t]

Thanks, @techanvil. I've updated the AC accordingly.

[techanvil]

Thanks @hussain-t!

AC ✅

[hussain-t]

Hi @techanvil, I’ve updated the AC to include the full URL for the /healthy endpoint (e.g., https://G-1234.fps.goog/mpath/healthy).

[hussain-t]

Thanks, @techanvil. The IB LGTM! I've slightly bumped the estimate up to 15.

IB ✅

[mohitwp]

QA Update ✅

• Tested on dev environment.
• Verified that the isFPMHealthy and isScriptAccessEnabled properties are true in the response. The isEnabledproperty is expected to remain null.
• Verified the googlesitekit_first_party_mode option is set in the DB with the properties defined as above.
• Tagging QA:engto test remaining QAB.