[retrofox]

Fixes CONNECT-496. Built on #53154, which this PR targets until it merges.

Proposed changes

Proxy_Request can now cache a read.

The consumer declares the cache and the forward runs it, so the key is built in one place.

The cache argument

to_path() and to_site() take cache, off by default:

• prefix: the consumer's transient prefix.
• success and error: seconds a response stays cached, by status below or from 400. Each one is opt-in.
• bypass: skips the cached response and stores the fresh one.

Only a GET is cached.

The connection check runs before the cache is read, so a site or a user without a token gets no cached data.

The key

It is computed, never supplied: path, query in any order, version, base, token context, the user id when the request is signed as the user, and the prefix's generation.

Proxy_Request::forget( $prefix ) renews the generation, so every read under the prefix misses.
The generation is a token in a non-autoloaded option.

The trait

WPCOM_REST_API_Proxy_Request gets three properties, $cache_prefix, $cache_duration_success, and $cache_duration_error, which default to '' and 0.

A consumer sets them in its constructor: PHP refuses a class that redeclares a trait property with another default.

A call overrides them through $request_options['cache'], and false turns the cache off for that call.

No existing consumer changes: without a prefix, nothing is cached.

Decisions to review

• What is stored is the response as wpcom sent it (status, body as a string, and headers), so the trait decodes on every call, hit or miss.
• A transport error (WP_Error) is never cached. Only a wpcom response is.
• Expired entries are left to WordPress's daily delete_expired_transients. A consumer with many distinct keys can add its prefix to jetpack_stats_transient_cleanup_prefixes.

Related product discussion/links

• pdWQjU-1Ke-p2
• Connection: add Proxy_Request, the forward to WordPress.com as its own class #53154

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

No.

Testing instructions

jp test php packages/connection
jp test php packages/publicize

Both suites are green.

Proxy_Request_Test covers the key (path, query order, version, context, and user), the durations by status, bypass, forget(), and the trait's properties with their per-call override.

[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 update/proxy-request-read-cache branch.
• To test on Simple, run the following command on your sandbox:

bin/jetpack-downloader test jetpack update/proxy-request-read-cache

bin/jetpack-downloader test jetpack-mu-wpcom-plugin update/proxy-request-read-cache

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

No summary data is available for parent commit 542924a, so cannot calculate coverage changes. 😴

If that commit is a feature branch rather than a trunk commit, this is expected. Otherwise, this should be updated once coverage for 542924a is available.

Full summary · PHP report · JS report