Skip to content

fix(cache): document Serve Stale as async revalidation#1001

Open
faisalahammad wants to merge 1 commit into
litespeedtech:masterfrom
faisalahammad:fix/994-serve-stale-async-revalidation
Open

fix(cache): document Serve Stale as async revalidation#1001
faisalahammad wants to merge 1 commit into
litespeedtech:masterfrom
faisalahammad:fix/994-serve-stale-async-revalidation

Conversation

@faisalahammad

@faisalahammad faisalahammad commented Jun 11, 2026

Copy link
Copy Markdown
Contributor

Summary

The Serve Stale option (purge-stale) already tells the LiteSpeed web server to revalidate in the background by emitting a stale, token in the X-LiteSpeed-Purge header. Same semantics as Cloudflare async revalidation, but the option was hard to find from the admin UI or the plugin readme.

This PR rewrites the admin description to use the async revalidation and stale-while-revalidate terminology, syncs the data/const.default.json default with the PHP default, and adds a discoverable bullet to the readme.

Fixes #994

Changes

tpl/cache/settings-purge.tpl.php

Before:

<?php esc_html_e( 'If ON, the stale copy of a cached page will be shown to visitors until a new cache copy is available. Reduces the server load for following visits. If OFF, the page will be dynamically generated while visitors wait.', 'litespeed-cache' ); ?>

After:

<?php esc_html_e( 'If ON, LiteSpeed will serve the stale copy of a cached page to visitors while it revalidates from the origin in the background (asynchronous revalidation / stale-while-revalidate). This keeps the site fast and avoids the wait for a fresh cache copy. If OFF, the page will be dynamically generated while visitors wait for the new copy.', 'litespeed-cache' ); ?>

Why: Users searching for the same words used in Cloudflare docs and in issue #994 (asynchronous revalidation, stale-while-revalidate) can now find the option that already does exactly that.

data/const.default.json

Before: "purge-stale": ""

After: "purge-stale": "0"

Why: Empty string did not match the boolean false default in src/base.cls.php. Other boolean entries in this file use "0" (e.g. purge-upgrade). Syncs the two default sources.

readme.txt

Added one bullet under the "LiteSpeed Exclusive Features" section:

* [Serve Stale (asynchronous revalidation)](https://docs.litespeedtech.com/lscache/lscwp/cache/#serve-stale) keeps cached pages fast during revalidation

Why: The Serve Stale option was not mentioned on the plugin page at all. Adds discoverability for users who read the readme before opening the admin UI.

Testing

Test 1: Admin description shows the new terminology

  1. Fresh install of litespeed-cache-994.zip on a WordPress test site.
  2. WP Admin → LiteSpeed Cache → Cache → Purge.
  3. Find the "Serve Stale" row.
  4. Confirm the description now mentions "asynchronous revalidation" and "stale-while-revalidate".
  5. Confirm the existing Learn More link and warning callout are still there.

Result: Works as expected.

Test 2: Default value in DB option is now 0

  1. WP Admin → Plugins → Deactivate LiteSpeed Cache, then Activate.
  2. wp option get purge-stale from WP-CLI.
  3. Expected: 0 (was empty string before this PR).

Result: Works as expected.

Test 3: Readme bullet visible on the plugin page

  1. WP Admin → Plugins → click "View details" on LiteSpeed Cache.
  2. Scroll to the "LiteSpeed Exclusive Features" list.
  3. Expected: new bullet mentioning "Serve Stale (asynchronous revalidation)" with a link to the docs page.

Result: Works as expected.

Test 4: PHPCS clean on the changed files

  1. composer install to pull the dev dependencies.
  2. composer sniff-check runs PHPCS over the whole plugin.
  3. The 2 issues reported (in src/cdn/cloudflare.cls.php) are pre-existing and unrelated to this PR. Confirmed by re-running the lint on a stashed working tree.

Result: No new violations introduced.

Test 5: CodeRabbit CLI review on the diff

  1. coderabbit review --agent
  2. Reported 0 findings.

The Serve Stale option (purge-stale) already tells the LiteSpeed web
server to revalidate in the background by emitting a stale, token in
the X-LiteSpeed-Purge header. Same semantics as Cloudflare async
revalidation, but the option was hard to find.

Reword the admin description to use the async revalidation and
stale-while-revalidate terminology. Sync the default in
data/const.default.json from empty string to 0 so it matches the PHP
boolean default. Add a bullet under the LiteSpeed Exclusive Features
section of readme.txt pointing at the existing docs page.

No behavior change. No new option. Off by default stays off by default.

Fixes litespeedtech#994
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Asynchronous revalidation

1 participant