Page MenuHomePhabricator

Create a mechanism for purging output from (parsoid) HTML endpoints from edge caches (without RESTbase)
Closed, DeclinedPublic


We are exposing parsoid endpoints from a number of MediaWiki REST endpoints, like /w/rest.php/{domain}/v3/page/html/{title} and /w/rest.php/v1/page/{title}/html. These currently are marked with a low TTL, because we have no mechanism in place to actively purge them. We need such a mechanism before we rely on these endpoints to replace the parsoid endpoints exposed by RESTbase, namely /api/rest_v1/page/html/{title}.

Currently, the endpoints exposed by RESTbase rely on puring implemented in the parsoid.js module, which emits events whenever it updates the stored/pregenerated copy of the parsoid output.

In a world without RESTbase, we will need to extend the mechanism we are currently using to purge page view URLs to also cover the HTML endpoints.

NOTE: we can't use the new mechanism for the RESTbase URLs while RESTbase is still storing content, because it would create a race condition.

See also T308424: Determine http cache control and active purging for REST endpoints serving parsoid output

Impact/Risk Assessment

Number of external queries that would be affected by (not) currectly puring:

  • /w/rest.php/v1/page/{title}/html: less than one per minute. No gateway. This endpoint is not advertized anywhere
  • /w/rest.php/{domain}/v3/page/html: less than one per month. No gateway. This endpoint is not advertized anywhere.
  • /api/rest_v1/page/html: more than 100 per second.

Top users of /api/rest_v1/page/html:

Screenshot 2023-08-25 102139.png (365×893 px, 17 KB)

(numbers are per day, samled 1/128)


  • HtmlCacheUpdater::getUrls should know at least about the canonical endpoint that exposes the page HTML.
  • Support for purging /api/rest_v1/page/html should be implemented in Bethos, based on the corresponding resource-change event. resource-change events apply to parsoid output and old parser output alike.
    • This must not be turned on as long as RESTbase is in the loop, as it would cause a race-condition when the purge is relayed to varnish before RESTbase has updated its internal store with the latest version!
    • The switch is risky as long as there are many callers of /api/rest_v1/page/html
    • We should then get the major users to switch to the canonical endpoint (though we may want to expose it through a nicer URL first, something like. /api/content.v1/page).

See T334238: Create deprecation plan for public parsoid endpoints and T328559: Replace usage of RESTbase parsoid endpoints

Event Timeline

MSantos triaged this task as High priority.Aug 31 2023, 2:19 PM
MSantos edited projects, added Parsoid (Tracking); removed Parsoid.
MSantos moved this task from Unsorted to Parsoid pile on the RESTBase Sunsetting board.

This could also be perceived as missing functionality for Parsoid, which depends on the Architectural decisions we are going to take moving forward.

The only correct way to send purges to the edge caches is doing that after the last layer of inner cache has been regenerated, or, if it's not regenerated, when it's invalidated. This means that if we generate parsoid cached output via a job on every edit/transclude, we should have that job spawn a ParsoidCdnPurgeJob (or maybe parametrize the current CdnPurge job, given the only thing changing would be the URLs?). That's a mechanism that is proven and would take a short implementation time too.

PCS is a different problem - mostly it depends on how we'll manage the internal caching for it.

After some discussion, we collectively realized that WikiPage::doPurge will invalidate all relevant parser cache entries, and any resource-change event emitted by it applies to output of parsoid and the old parser alike. This makes it a lot easier to reason about things, we don't have to worry about when things actually get written to the parser cache.

Is this still a valid concern/ticket? I think that at this point if we:

  • Disable storage for parsoid incoming requests (in progress)
  • Disable pregeneration for parsoid

all the requests are going to hit MW and eventually parser cache that has an existing mechanism for purges.

Overall in terms of purging needs after disabling storage:

  • ParserCache is handled internally in MW
  • We still have rules for /page/html to be purged on resource change events. That should be good enough in order to remove the stored parsoid dependency from RESTBase.
    • We have rules on changeprop to emit purge via /sys/queue/events to purge edge /page/html
  • We still have rules for /page/html to be purged on resource change events. That should be good enough in order to remove the stored parsoid dependency from RESTBase.

Right now, we still do pre-generation in restbase. We should stop doing that ASAP. Then we will also no longer hit core after template changes.

  • Have have rules on changeprop to emit purge via /sys/queue/events to purge edge /page/html

We do need purge events to be sent to the edge caches for /w/rest.php/v1/(page|revision)/.*/(with_)?html. Currently, responses from these endpoints have a very short TTL. Once we have pirge events in palce, we can fix that.

I seem to recall that @Joe said there was a new system for this in place, instead of (or on top of?) changeprop. I don't recall the details. It would be good to know if we can up the TTL on these responses.