Fix Fastly domain purge, and make both cache adapters consistent

[Meldiron]

What does this PR do?

Fixes a real defect in Fastly::purgeDomain(), applies the same scrutiny to Cloudflare, and moves the part both providers repeat into one place. Targets main and is independent of #5 — that PR only adds files and touches no existing adapter, so the two can merge in either order.

Everything below comes from reading the provider docs rather than from assumption: Fastly purge API, Fastly purging concepts, Cloudflare purge API, Cloudflare purge cache.

1. Fastly::purgeDomain() never purged a domain

On main the argument is validated and then discarded:

public function purgeDomain(string $domain): void
{
    Domain::validate($domain);   // ← $domain is used here and nowhere else
    $this->requireServiceId('domain purging');
    $result = $this->request(Method::POST, '/service/' . $this->serviceId . '/purge_all');
    //                                   ← the domain never reaches the request

Two different domains therefore produce byte-identical requests:

purgeDomain('alice.example.com') -> https://api.fastly.com/service/shared-svc/purge_all
purgeDomain('bob.example.com')   -> https://api.fastly.com/service/shared-svc/purge_all
identical requests? YES

On a service fronting many domains that evicts all of them. And purge_all is no mild substitute: Fastly documents it as taking up to two minutes, warns that "purging a large amount of content from a high traffic service is likely to result in a rapid increase in traffic to origin", and states it "is not compatible with soft purge or bulk purge" — so softPurge: true was silently ignored here. A caller asking to soft purge one domain got a hard purge of everything.

Fastly has no purge-by-host operation. Its API is URL purge, surrogate key purge (single or batch), and purge-all — nothing in between. A domain is therefore addressed by the surrogate key the origin attaches, which is Fastly's own recommendation: surrogate key purges "can be used in place of single URL purge and purge-all".

domainKeyPrefix is therefore required, and there is no longer any configuration in which purgeDomain() means purge_all. Pass '' when the key is the bare hostname.

2. Cloudflare needed no such fix, and gained what it was missing

Cloudflare purges a hostname natively ({"hosts": [...]}), so purgeDomain() already sent the domain rather than discarding it. Worth stating plainly: the bug was Fastly's, not a shared design flaw.

What Cloudflare was missing is a zone-wide purge — purge_everything was not implemented at all. It is now purgeZone().

Its batch ceiling is also now configurable, because Cloudflare's own pages disagree: the purge overview tables say 100 operations per request for tags/hostnames/prefixes (and 100 URLs for single-file purge, 500 on Enterprise), while the purge-by-hostname page says 30 hostnames at a time. The default stays at the lower figure, which is within both readings; itemsPerPurge raises it. Also relevant to batching: Cloudflare's Free tier allows only 5 purge requests per minute.

3. purge_all / purge_everything becomes purgeZone() on both

Renamed from purgeService() per review. Both adapters use the same name, and both keep it off the Adapter interface, so a routing adapter can never reach it by fanning out an interface method — a test asserts its absence from the interface.

4. A shared base so bulk operations and provider-specific methods are easy to add

Cache\Adapter\Api owns the sequence both providers repeat — authenticate a request, send it, decide whether the answer means success, turn a failure into a message. Each adapter supplies only those four pieces plus a USER_AGENT, and an operation becomes the request it makes:

// One call.
$this->send(Method::POST, '/zones/' . $this->zoneId . '/purge_cache', ['purge_everything' => true]);

// As few calls as the provider's per-request ceiling allows.
$this->batch($keys, self::KEYS_PER_PURGE, function (array $chunk): void {
    $this->send(Method::POST, '/service/' . $this->serviceId . '/purge', ['surrogate_keys' => $chunk]);
});

Both adapters previously carried their own copy of the request-building, JSON decoding and error-formatting code. Per-request ceilings are now named constants (Fastly::KEYS_PER_PURGE, Cloudflare::ITEMS_PER_PURGE) rather than inline magic numbers.

Fastly::purgeKeys() uses this to adopt the batch endpoint: POST /service/{sid}/purge with {"surrogate_keys": [...]}, up to 256 keys per request instead of one request per key. Soft purge still applies — Fastly: "Single object, surrogate key, and bulk surrogate key purges all support soft purge". Keys in a body also need no percent-encoding, which would purge a key the origin never attached.

Test Plan

composer test — 40 tests, 71 assertions, from 26/49 on main. composer analyse (level 6) [OK] No errors; composer lint passes.

The extraction changed no wire behaviour. I captured method, URL, every header and body for Cloudflare's three operations and Fastly's path purge on main and on this branch, and diffed: IDENTICAL: no wire change for these operations. Only Fastly's key and domain purges differ, which is the point of the PR.

Three behaviours seen red before being claimed:

Regression introduced	Result
purgeDomain() pointed back at purgeZone()	Failures: 2, printing +'…/service/shared-service/purge_all' — the original bug
rawurlencode re-added to the batch body	Failures: 1, -'domain-example.com-summer sale' / +'…summer%20sale'
purgeZone() sending hosts instead of purge_everything	Failures: 1, -'purge_everything' => true
Cloudflare isSuccess() reduced to the HTTP status	Failures: 1 — a {"success":false} body stops being caught

New coverage: Fastly domain purge as exactly one key-purge request; an empty prefix yielding the bare hostname; keys asserted unencoded; 257 keys becoming 2 requests not 257; purgeZone() on both adapters; purgeZone absent from the interface; zone purge requiring a service ID; Cloudflare batching URLs and tags with the boundary asserted; a configurable ceiling collapsing 100 tags into one request; Cloudflare rejecting a 2xx whose body says success: false; empty purges touching nothing.

Every README example for both providers was extracted from the markdown and executed against this branch, so the reordered Fastly constructor and the new Cloudflare snippets are known to resolve and construct rather than merely to look right.

Not verified against the live Fastly or Cloudflare APIs — coverage is at request-construction level throughout, as with the rest of the suite.

Breaking changes

• Fastly: domainKeyPrefix is a required second constructor argument, so positional calls shift.
• Fastly::purgeDomain() no longer purges the whole service; callers who wanted that call purgeZone().
• Fastly::purgeKeys() sends raw keys in a body, so callers that pre-encoded keys must stop.
• Both adapters now extend Cache\Adapter\Api; anyone subclassing them will see the new abstract methods.
• Cloudflare's constructor gains a trailing itemsPerPurge; existing calls are unaffected.

Library is 0.0.x. The only consumer I know of is appwrite-labs/cloud#5259, which passes named arguments, calls neither purgeZone(), and is updated for the Fastly wire format.

Related PRs and Issues

Split out of #5, then widened after reading the provider docs. Both are needed by appwrite-labs/cloud#5259, which tracks the integration/balancer-and-fastly branch (a merge of the two) until they are merged and tagged.

Checklist

• I read the contributing guide
• I ran composer lint
• I ran composer analyse
• I ran composer test

🤖 Generated with Claude Code

[greptile-apps]

Greptile Summary

The PR corrects Fastly domain purging by mapping domains to surrogate keys and adds explicit whole-zone purge operations for Fastly and Cloudflare.

• Batches Fastly surrogate-key purges through the provider’s bulk endpoint.
• Adds Cloudflare and Fastly purgeZone() implementations.
• Consolidates provider request handling and expands request-construction coverage.
• Documents the revised adapter behavior and Fastly constructor contract.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
src/Cdn/Cache/Adapter/Fastly.php	Replaces service-wide domain purges with batched surrogate-key purges and exposes whole-service purging separately.
src/Cdn/Cache/Adapter/Cloudflare.php	Consolidates purge requests, names batching limits, validates body-level success, and adds whole-zone purging.
src/Cdn/Cache/Adapter.php	Adds whole-zone purging to the common adapter contract; the previously reported fanout path is absent from the current repository.
src/Cdn/Cache.php	Delegates whole-zone purging to the facade’s single configured adapter.
tests/Cdn/Cache/AdapterTest.php	Verifies consistent adapter operations and provider-specific batching constants.

_{Reviews (8): Last reviewed commit: "Correct the adapter comments and docs" | Re-trigger Greptile}

[Meldiron]

lgtm