Status: seed jetpack_offline_mode to avoid per-request reads

[darssen]

Fixes JETPACK-1994

Proposed changes

• Status::is_offline_mode(): when the jetpack_offline_mode option is absent, seed it as an autoloaded false so it isn't re-queried on every request.
• Distinguishes "never stored" from a stored false with a null sentinel default, and seeds via add_option (not update_option, which short-circuits when the new value equals the current default false and would leave the row unset).
• Adjust the Status_Test unit tests accordingly.

Why are these changes being made

On a site without a persistent object cache, WP's per-request option caches (alloptions/notoptions) are discarded each request, so any non-autoloaded option costs a dedicated SELECT … FROM wp_options on every request it's read — a passed default doesn't help, because the query is what discovers the option is missing.

jetpack_offline_mode is read via Status::is_offline_mode() on essentially every request (it runs during Jetpack's bootstrap), and it's never written by Jetpack — it's a manual escape hatch (offline mode is normally enabled via the jetpack_offline_mode filter, the JETPACK_DEV_DEBUG/WP_LOCAL_DEV constants, or local-site detection, all checked before the option). So on most sites the option is absent and re-read every request. Seeding an autoloaded default the first time it's found missing moves the value into the single bulk alloptions load, eliminating the per-request read. The option is not synced, so seeding produces no Sync traffic, and behaviour is unchanged (an unset option already resolved to the same false; a stored value still wins and is never overwritten).

(A row that exists but is non-autoloaded would still churn — we only seed when the option is absent and don't flip autoload on existing rows — but that doesn't arise for this option in the sites we investigated.)

Related product discussion/links

• JETPACK-1539

Does this pull request change what data or activity we track or use?

No. Seeding writes the existing default value (false) to the local options table; it is not synced to WordPress.com.

Testing instructions

1. Create a test site with no persistent object cache. On jurassic.ninja, open the options and uncheck "Drop-in Cache Plugins", then create the site. (Without this, JN installs an object cache that hides the issue — notoptions would persist across requests.) Confirm it's off:

wp eval 'var_dump( wp_using_ext_object_cache() );'   // must be false

2. Add a small logger so the option reads are visible on logged-out requests. Create wp-content/mu-plugins/1994-check.php:

<?php
add_filter( 'query', function ( $q ) {
    if ( stripos( $q, 'option_value' ) !== false && strpos( $q, 'jetpack_offline_mode' ) !== false ) {
        @file_put_contents( WP_CONTENT_DIR . '/jp1994.log',
            gmdate( 'c' ) . ' ' . trim( preg_replace( '/\s+/', ' ', $q ) ) . "\n",
            FILE_APPEND | LOCK_EX );
    }
    return $q;
}, 0 );

3. Load the front end logged out, using a different query string each time so the edge page cache doesn't serve a cached page (each unique URL is a cache miss that runs PHP). For example, open these in a private/incognito window:

https://your-site.jurassic.ninja/?cachebust=1
https://your-site.jurassic.ninja/?cachebust=2
https://your-site.jurassic.ninja/?cachebust=3

4. Check the log: cat wp-content/jp1994.log

• Before this PR: one SELECT … 'jetpack_offline_mode' per request.

• After this PR: it appears only on the first request (the one-time seed), then stops. Confirm the row now exists autoloaded:

  wp db query "SELECT option_name, autoload FROM wp_options WHERE option_name = 'jetpack_offline_mode'"
  

  (should show autoload = on). Re-test with fresh ?cachebust= values, since the ones above are now cached.

5. Behaviour is unchanged: Status::is_offline_mode() still returns true with JETPACK_DEV_DEBUG/WP_LOCAL_DEV, on a local site, when the jetpack_offline_mode filter returns true, or when the option is 1; false otherwise.

Unit tests: projects/packages/status (Status_Test).

[github-actions]

Are you an Automattician? Please test your changes on all WordPress.com environments to help mitigate accidental explosions.

• To test on WoA, go to the Plugins menu on a WoA dev site. Click on the "Upload" button and follow the upgrade flow to be able to upload, install, and activate the Jetpack Beta plugin. Once the plugin is active, go to Jetpack > Jetpack Beta, select your plugin (Jetpack or WordPress.com Site Helper), and enable the fix/jetpack-1539-connection-status-option-churn branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack fix/jetpack-1539-connection-status-option-churn

bin/jetpack-downloader test jetpack-mu-wpcom-plugin fix/jetpack-1539-connection-status-option-churn

Interested in more tips and information?

• In your local development environment, use the jetpack rsync command to sync your changes to a WoA dev blog.
• Read more about our development workflow here: PCYsg-eg0-p2
• Figure out when your changes will be shipped to customers here: PCYsg-eg5-p2

[github-actions]

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

• ✅ Include a description of your PR changes.
  
• ✅ Add a "[Status]" label (In Progress, Needs Review, ...).
  
• ✅ Add testing instructions.
  
• ✅ Specify whether this PR includes any changes to data or privacy.
  
• ✅ Add changelog entries to affected projects
  

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

---

Follow this PR Review Process:

1. Ensure all required checks appearing at the bottom of this PR are passing.
2. Make sure to test your changes on all platforms that it applies to. You're responsible for the quality of the code you ship.
3. You can use GitHub's Reviewers functionality to request a review.
4. When it's reviewed and merged, you will be pinged in Slack to deploy the changes to WordPress.com simple once the build is done.

If you have questions about anything, reach out in #jetpack-developers for guidance!

[jp-launch-control]

Code Coverage Summary

Coverage changed in 1 file.

File	Coverage	Δ%	Δ Uncovered
projects/packages/status/src/class-status.php	92/107 (85.98%)	0.69%	0 💚

Full summary · PHP report · JS report

[Copilot]

Pull request overview

This PR optimizes Jetpack’s Status::is_offline_mode() path by persisting a default jetpack_offline_mode option as an autoloaded row the first time it’s observed missing, reducing repeated per-request option-table reads on sites without a persistent object cache.

Changes:

• Seed jetpack_offline_mode as an autoloaded false when it’s absent, avoiding repeated DB queries.
• Update Status_Test to reflect the new “missing vs stored” behavior and seeding via add_option.
• Add a changelog entry documenting the performance-related fix.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
projects/packages/status/src/class-status.php	Adds missing-option detection and one-time seeding via add_option() to prevent per-request option reads.
projects/packages/status/tests/php/Status_Test.php	Adjusts unit tests for the new seeding/missing-option behavior.
projects/packages/status/changelog/fix-jetpack-1539-option-read-churn	Adds a patch-level changelog entry describing the change.

[darssen]

Done in 8b8bcf0

[darssen]

Makes sense, implemented with f964df4

[bindlegirl]

Thanks for working on this @darssen I agree with the approach.

I do have some questions.

1. Should the seed be skipped when there's a persistent object cache?

The optimization only helps sites without one. But the seed runs unconditionally, so sites with persistent cache (WoW) also get a write and a permanent autoloaded row.
Gating it would confine the change to the sites that benefit:

if ( $sentinel === $option && ! wp_using_ext_object_cache() ) {
	add_option( 'jetpack_offline_mode', false, '', true );
}

I can see the argument for keeping behaviour uniform rather than branching on the cache backend, so I'm not insisting.

2. The failure case is now worse than the status quo

If add_option() doesn't create the row (e.g. a write error) every subsequent request pays the original SELECT plus an INSERT attempt.

I think it's worth considering restricting the seed to contexts where a write is expected anyway (admin, cron, WP-CLI) and the front-end path stays read-only. What do you think?

3. The sentinel is truthy (non-blocking, but cheap to harden)

new \stdClass() is truthy, so anything that reaches (bool) $option as an object silently puts the site into offline mode. The identity check handles the normal path correctly, but note that default_option_jetpack_offline_mode filters now receive the sentinel as $default_value, and $passed_default flips from false to true because get_option() is called with two arguments. A filter returning a modified or cloned value lands in the else branch and evaluates as true.

One-liner that closes it:

$offline_mode = is_scalar( $option ) ? (bool) $option : false;

Separately and much more theoretically: add_option() skips its own existence guard when notoptions already has the key — which our get_option() call just put there — so it goes straight to INSERT ... ON DUPLICATE KEY UPDATE. A concurrent write in that window would be clobbered. Given this option is only ever set by hand, I'd note it and move on.

[darssen]

Many thanks for the review @bindlegirl!

They are not really blockers, since 2 is the only one a bit more severe, but still, if the site is not able to add options, it's not really healthy. In any case I addressed all three with 9585330.

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

[bindlegirl]

Nice work!