a cache purge that reports success and clears nothing

"""Purge a URL and verify from CF-Cache-Status that it actually cleared.

The purge API is idempotent: clearing an object that is not there succeeds. So a
purge that names the wrong cache key is indistinguishable from one that worked,
unless you go and look.
"""
import argparse
import logging
import os
import sys

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("cloudflare_purge_verify")

API = "https://api.cloudflare.com/client/v4"
# Objects cached with any of these in the key are not cleared by a dashboard
# single-file purge. Documented list, not a guess.
KEY_HEADERS = {"origin", "x-forwarded-host", "x-host", "x-forwarded-scheme",
               "x-original-url", "x-rewrite-url", "forwarded"}


def purge_will_miss(cache_rule):
    """Pure decision function: can single-file purge clear objects under this rule?

    Two documented reasons it cannot: a custom cache key containing headers or
    cookies (the purge request cannot supply them), and an expression that matches
    only GET (purge uses a different method internally).
    """
    reasons = []
    key = cache_rule.get("cache_key", {}) or {}
    custom = key.get("custom_key", {}) or {}
    if custom.get("header") or custom.get("cookie"):
        reasons.append("custom cache key includes headers or cookies -- dashboard "
                       "single-file purge cannot supply them; use the API with "
                       "headers, or purge by prefix/tag")
    expr = cache_rule.get("expression", "")
    if 'http.request.method eq "GET"' in expr and "PURGE" not in expr:
        reasons.append('expression matches only GET -- purge uses a different method; '
                       'add or http.request.method eq "PURGE"')
    return reasons


def interpret(status, age):
    """What CF-Cache-Status means after a purge.

    EXPIRED is not a failure with tiered cache on: the lower tier is revalidating
    against the upper tier.
    """
    s = (status or "").upper()
    if s in ("MISS", "EXPIRED"):
        return True, f"{s} -- purge took effect"
    if s == "HIT":
        return (False, f"HIT with age={age} -- still serving a stored copy; the purge "
                       "did not match this object's cache key")
    if s in ("DYNAMIC", "BYPASS"):
        return True, f"{s} -- this URL is not cached at all"
    return True, f"{s or 'no CF-Cache-Status'} -- nothing to purge here"


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("--zone-id", required=True)
    ap.add_argument("--url", required=True)
    ap.add_argument("--header", action="append", default=[],
                    help="Name:Value that is part of the cache key; repeatable")
    ap.add_argument("--apply", action="store_true")
    args = ap.parse_args()

    token = os.environ.get("CF_API_TOKEN")
    if not token:
        log.error("set CF_API_TOKEN")
        return 2
    s = requests.Session()
    s.headers.update({"Authorization": f"Bearer {token}"})

    headers = {}
    for h in args.header:
        name, _, value = h.partition(":")
        headers[name.strip()] = value.strip()
        if name.strip().lower() in KEY_HEADERS:
            log.info("%s is a known cache-key header -- good that you passed it", name.strip())

    if not args.apply:
        log.info("WOULD purge %s with headers=%s -- pass --apply", args.url, headers or "{}")
        return 0

    body = {"files": [{"url": args.url, "headers": headers} if headers else args.url]}
    r = s.post(f"{API}/zones/{args.zone_id}/purge_cache", json=body, timeout=30)
    r.raise_for_status()
    log.info("purge API returned success=%s (this does NOT mean anything was removed)",
             r.json().get("success"))

    probe = requests.get(args.url, headers=headers, timeout=30)
    ok, msg = interpret(probe.headers.get("CF-Cache-Status"), probe.headers.get("Age"))
    (log.info if ok else log.error)(msg)
    if not ok:
        log.error("try purge by prefix, hostname or tag -- none of those are affected "
                  "by custom cache keys")
    return 0 if ok else 1


if __name__ == "__main__":
    sys.exit(main())

/**
 * Purge a URL and verify from CF-Cache-Status that it actually cleared.
 *
 * The purge API is idempotent: clearing an object that is not there succeeds. So a
 * purge that names the wrong cache key looks exactly like one that worked.
 */
const API = 'https://api.cloudflare.com/client/v4';
// Objects cached with any of these in the key are not cleared by a dashboard
// single-file purge. Documented list, not a guess.
const KEY_HEADERS = new Set(['origin', 'x-forwarded-host', 'x-host',
  'x-forwarded-scheme', 'x-original-url', 'x-rewrite-url', 'forwarded']);

/**
 * Pure decision function: can single-file purge clear objects under this rule?
 * Two documented reasons it cannot -- a custom cache key containing headers or
 * cookies, and an expression matching only GET.
 */
export function purgeWillMiss(cacheRule) {
  const reasons = [];
  const custom = cacheRule.cache_key?.custom_key ?? {};
  if (custom.header || custom.cookie) {
    reasons.push('custom cache key includes headers or cookies -- dashboard single-file '
      + 'purge cannot supply them; use the API with headers, or purge by prefix/tag');
  }
  const expr = cacheRule.expression ?? '';
  if (expr.includes('http.request.method eq "GET"') && !expr.includes('PURGE')) {
    reasons.push('expression matches only GET -- purge uses a different method; '
      + 'add or http.request.method eq "PURGE"');
  }
  return reasons;
}

/** What CF-Cache-Status means after a purge. EXPIRED is fine with tiered cache. */
export function interpret(status, age) {
  const s = (status ?? '').toUpperCase();
  if (s === 'MISS' || s === 'EXPIRED') return [true, `${s} -- purge took effect`];
  if (s === 'HIT') {
    return [false, `HIT with age=${age} -- still serving a stored copy; the purge did `
      + "not match this object's cache key"];
  }
  if (s === 'DYNAMIC' || s === 'BYPASS') return [true, `${s} -- this URL is not cached at all`];
  return [true, `${s || 'no CF-Cache-Status'} -- nothing to purge here`];
}

async function main() {
  const arg = (n) => process.argv[process.argv.indexOf(n) + 1];
  const zone = arg('--zone-id');
  const url = arg('--url');
  const apply = process.argv.includes('--apply');
  const headers = {};
  process.argv.forEach((a, i) => {
    if (a !== '--header') return;
    const [name, ...rest] = process.argv[i + 1].split(':');
    headers[name.trim()] = rest.join(':').trim();
    if (KEY_HEADERS.has(name.trim().toLowerCase())) {
      console.log(`${name.trim()} is a known cache-key header -- good that you passed it`);
    }
  });
  const token = process.env.CF_API_TOKEN;
  if (!token) { console.error('set CF_API_TOKEN'); process.exit(2); }

  if (!apply) {
    console.log(`WOULD purge ${url} with headers=${JSON.stringify(headers)} -- pass --apply`);
    process.exit(0);
  }

  const files = [Object.keys(headers).length ? { url, headers } : url];
  const res = await fetch(`${API}/zones/${zone}/purge_cache`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ files }),
  });
  const { success } = await res.json();
  console.log(`purge API returned success=${success} (this does NOT mean anything was removed)`);

  const probe = await fetch(url, { headers });
  const [ok, msg] = interpret(probe.headers.get('cf-cache-status'), probe.headers.get('age'));
  (ok ? console.log : console.error)(msg);
  if (!ok) {
    console.error('try purge by prefix, hostname or tag -- none are affected by custom cache keys');
  }
  process.exit(ok ? 0 : 1);
}

if (import.meta.url === `file://${process.argv[1]}`) main();

from cloudflare_purge_verify import interpret, purge_will_miss


def test_miss_means_the_purge_worked():
    ok, _ = interpret("MISS", None)
    assert ok


def test_expired_is_success_under_tiered_cache():
    """The lower tier is revalidating against the upper tier. Not a failure."""
    ok, _ = interpret("EXPIRED", "3")
    assert ok


def test_hit_with_a_large_age_is_a_failed_purge():
    ok, msg = interpret("HIT", "86400")
    assert not ok and "cache key" in msg


def test_dynamic_is_not_a_failure():
    ok, _ = interpret("DYNAMIC", None)
    assert ok


def test_a_custom_key_with_headers_blocks_single_file_purge():
    rule = {"cache_key": {"custom_key": {"header": {"include": ["Origin"]}}}}
    assert any("custom cache key" in r for r in purge_will_miss(rule))


def test_a_get_only_expression_is_flagged():
    rule = {"expression": 'http.request.method eq "GET"'}
    assert any("only GET" in r for r in purge_will_miss(rule))


def test_an_expression_that_allows_purge_is_not_flagged():
    rule = {"expression": '(http.request.method eq "GET" or http.request.method eq "PURGE")'}
    assert purge_will_miss(rule) == []


def test_a_plain_rule_is_clean():
    assert purge_will_miss({"expression": 'http.host eq "example.com"'}) == []

import { test } from 'node:test';
import assert from 'node:assert/strict';
import { interpret, purgeWillMiss } from './cloudflare-purge-verify.mjs';

test('MISS means the purge worked', () => {
  assert.equal(interpret('MISS', null)[0], true);
});

test('EXPIRED is success under tiered cache', () => {
  assert.equal(interpret('EXPIRED', '3')[0], true);
});

test('HIT with a large age is a failed purge', () => {
  const [ok, msg] = interpret('HIT', '86400');
  assert.equal(ok, false);
  assert.ok(msg.includes('cache key'));
});

test('a custom key with headers blocks single-file purge', () => {
  const rule = { cache_key: { custom_key: { header: { include: ['Origin'] } } } };
  assert.ok(purgeWillMiss(rule).some((r) => r.includes('custom cache key')));
});

test('an expression that allows PURGE is not flagged', () => {
  const rule = { expression: '(http.request.method eq "GET" or http.request.method eq "PURGE")' };
  assert.deepEqual(purgeWillMiss(rule), []);
});