Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(cloudflare): cache purge (Phase 2)

Juan Denis6bc0ac36e52f
diff --git a/backend/app/api/cloudflare.py b/backend/app/api/cloudflare.py
index 1c8b63a2..5c122d19 100644
--- a/backend/app/api/cloudflare.py
+++ b/backend/app/api/cloudflare.py
@@ -79,3 +79,22 @@ def update_zone_setting(zone_id, setting_id):
except CloudflareError as e:
return jsonify({'error': str(e)}), 400
return _service_response(res)
+
+
+# ── Cache ────────────────────────────────────────────────────────────────────
+
+@cloudflare_bp.route('/zones/<int:zone_id>/purge-cache', methods=['POST'])
+@jwt_required()
+def purge_cache(zone_id):
+ if not _require_admin():
+ return jsonify({'error': 'Admin access required'}), 403
+ data = request.get_json(silent=True) or {}
+ try:
+ res = CloudflareService.purge_cache(
+ zone_id,
+ everything=bool(data.get('purge_everything') or data.get('everything')),
+ files=data.get('files'), hosts=data.get('hosts'),
+ prefixes=data.get('prefixes'), tags=data.get('tags'))
+ except CloudflareError as e:
+ return jsonify({'error': str(e)}), 400
+ return _service_response(res)
diff --git a/backend/app/services/cloudflare_service.py b/backend/app/services/cloudflare_service.py
index cc13d742..9d87ce41 100644
--- a/backend/app/services/cloudflare_service.py
+++ b/backend/app/services/cloudflare_service.py
@@ -218,3 +218,36 @@ class CloudflareService:
applied = sum(1 for r in results if r['success'])
return {'success': applied > 0, 'applied': applied,
'total': len(results), 'results': results}
+
+ # Free/Pro plans can purge everything or up to 30 individual files per request;
+ # hosts/prefixes/tags are Enterprise-only (Cloudflare returns a plan error,
+ # which we surface verbatim).
+ MAX_PURGE_FILES = 30
+
+ @classmethod
+ def purge_cache(cls, zone_id, *, everything=False, files=None, hosts=None,
+ prefixes=None, tags=None):
+ """Purge the zone's Cloudflare cache. Either ``everything`` or one/more of
+ ``files``/``hosts``/``prefixes``/``tags``. Raises :class:`CloudflareError`
+ when nothing was requested (a caller error)."""
+ zone, client = cls._zone_and_client(zone_id)
+
+ if everything:
+ payload = {'purge_everything': True}
+ else:
+ payload = {}
+ clean = [f.strip() for f in (files or []) if f and f.strip()]
+ if clean:
+ payload['files'] = clean[:cls.MAX_PURGE_FILES]
+ for key, val in (('hosts', hosts), ('prefixes', prefixes), ('tags', tags)):
+ items = [v.strip() for v in (val or []) if v and v.strip()]
+ if items:
+ payload[key] = items
+ if not payload:
+ raise CloudflareError('Nothing to purge — choose "everything" or '
+ 'provide files, hosts, prefixes, or tags')
+
+ res = client.purge_cache(zone.provider_zone_id, payload)
+ if not res.get('success'):
+ return {'success': False, 'error': res.get('error', 'Cache purge failed')}
+ return {'success': True, 'purged': payload}
diff --git a/backend/app/services/dns/cloudflare.py b/backend/app/services/dns/cloudflare.py
index 53a55c08..fc737588 100644
--- a/backend/app/services/dns/cloudflare.py
+++ b/backend/app/services/dns/cloudflare.py
@@ -256,3 +256,8 @@ class CloudflareClient:
structured object for compound settings (e.g. HSTS ``security_header``)."""
return self.request('PATCH', f'/zones/{zone_id}/settings/{setting_id}',
json={'value': value})
+
+ def purge_cache(self, zone_id: str, payload: dict) -> dict:
+ """Purge the zone's Cloudflare cache. ``payload`` is one of
+ ``{purge_everything: true}`` or ``{files|hosts|prefixes|tags: [...]}``."""
+ return self.request('POST', f'/zones/{zone_id}/purge_cache', json=payload)
diff --git a/backend/tests/test_cloudflare_zone_settings.py b/backend/tests/test_cloudflare_zone_settings.py
index 5e7288d8..79348e29 100644
--- a/backend/tests/test_cloudflare_zone_settings.py
+++ b/backend/tests/test_cloudflare_zone_settings.py
@@ -158,3 +158,65 @@ def test_service_apply_preset_reports_each(app, monkeypatch):
assert res['total'] == len(CloudflareService.RECOMMENDED_PRESET)
assert res['applied'] == res['total'] - 1
assert any(r['setting'] == 'http3' and not r['success'] for r in res['results'])
+
+
+# ── cache purge (Phase 2) ────────────────────────────────────────────────────
+
+def test_client_purge_cache_posts_payload(monkeypatch):
+ from app.services.dns import cloudflare as cf
+ seen = {}
+
+ def capture(method, url, headers=None, json=None, params=None, timeout=None):
+ seen.update(method=method, url=url, json=json)
+ return _Resp({'success': True, 'result': {'id': 'zoneA'}})
+ monkeypatch.setattr(cf.requests, 'request', capture)
+ res = _client().purge_cache('zoneA', {'purge_everything': True})
+ assert res['success'] is True
+ assert seen['method'] == 'POST'
+ assert seen['url'].endswith('/zones/zoneA/purge_cache')
+ assert seen['json'] == {'purge_everything': True}
+
+
+def test_service_purge_everything(app, monkeypatch):
+ from app.services.dns import cloudflare as cf
+ from app.services.cloudflare_service import CloudflareService
+ zone = _make_cf_zone()
+ sent = {}
+ monkeypatch.setattr(cf.requests, 'request',
+ lambda method, url, headers=None, json=None, params=None, timeout=None:
+ (sent.update(json=json) or _Resp({'success': True})))
+ res = CloudflareService.purge_cache(zone.id, everything=True)
+ assert res['success'] is True
+ assert sent['json'] == {'purge_everything': True}
+
+
+def test_service_purge_files_caps_at_30(app, monkeypatch):
+ from app.services.dns import cloudflare as cf
+ from app.services.cloudflare_service import CloudflareService
+ zone = _make_cf_zone()
+ sent = {}
+ monkeypatch.setattr(cf.requests, 'request',
+ lambda method, url, headers=None, json=None, params=None, timeout=None:
+ (sent.update(json=json) or _Resp({'success': True})))
+ urls = [f'https://example.com/{i}.css' for i in range(50)]
+ res = CloudflareService.purge_cache(zone.id, files=urls)
+ assert res['success'] is True
+ assert len(sent['json']['files']) == 30
+
+
+def test_service_purge_nothing_raises(app):
+ from app.services.cloudflare_service import CloudflareService, CloudflareError
+ zone = _make_cf_zone()
+ with pytest.raises(CloudflareError):
+ CloudflareService.purge_cache(zone.id)
+
+
+def test_service_purge_surfaces_provider_error(app, monkeypatch):
+ from app.services.dns import cloudflare as cf
+ from app.services.cloudflare_service import CloudflareService
+ zone = _make_cf_zone()
+ monkeypatch.setattr(cf.requests, 'request',
+ lambda *a, **k: _Resp({'success': False,
+ 'errors': [{'message': 'rate limited'}]}))
+ res = CloudflareService.purge_cache(zone.id, everything=True)
+ assert res['success'] is False and 'rate limited' in res['error']
diff --git a/frontend/src/pages/CloudflareZoneSettings.jsx b/frontend/src/pages/CloudflareZoneSettings.jsx
index 6f3e4102..60983bf1 100644
--- a/frontend/src/pages/CloudflareZoneSettings.jsx
+++ b/frontend/src/pages/CloudflareZoneSettings.jsx
@@ -1,16 +1,18 @@
import { useState, useEffect, useCallback } from 'react';
import { useParams, Link } from 'react-router-dom';
-import { Cloud, ShieldCheck, Lock, Gauge, Database, Wand2 } from 'lucide-react';
+import { Cloud, ShieldCheck, Lock, Gauge, Database, Wand2, Eraser } from 'lucide-react';
import { PageTopbar } from '@/components/ds';
import { Tabs, TabsList, TabsTrigger, TabsContent } from '@/components/ui/tabs';
import { Switch } from '@/components/ui/switch';
import { Button } from '@/components/ui/button';
import { Badge } from '@/components/ui/badge';
+import { Textarea } from '@/components/ui/textarea';
import {
Select, SelectTrigger, SelectContent, SelectItem, SelectValue,
} from '@/components/ui/select';
import PageLoader from '../components/PageLoader';
import EmptyState from '../components/EmptyState';
+import ConfirmDialog from '../components/ConfirmDialog';
import { useToast } from '../contexts/ToastContext';
import { useAuth } from '../contexts/AuthContext';
import api from '../services/api';
@@ -46,6 +48,9 @@ const CloudflareZoneSettings = () => {
const [settings, setSettings] = useState({});
const [saving, setSaving] = useState(null); // setting id in flight
const [applying, setApplying] = useState(false);
+ const [purgeUrls, setPurgeUrls] = useState('');
+ const [purging, setPurging] = useState(false);
+ const [confirmPurgeAll, setConfirmPurgeAll] = useState(false);
const loadSettings = useCallback(async () => {
setLoading(true);
@@ -98,6 +103,38 @@ const CloudflareZoneSettings = () => {
}
};
+ const handlePurgeEverything = async () => {
+ setConfirmPurgeAll(false);
+ setPurging(true);
+ try {
+ await api.purgeCloudflareCache(zoneId, { purge_everything: true });
+ toast.success('Purged the entire cache');
+ } catch (err) {
+ toast.error(err.message || 'Failed to purge cache');
+ } finally {
+ setPurging(false);
+ }
+ };
+
+ const handlePurgeFiles = async () => {
+ const files = purgeUrls.split('\n').map(u => u.trim()).filter(Boolean);
+ if (files.length === 0) {
+ toast.error('Enter at least one URL to purge');
+ return;
+ }
+ setPurging(true);
+ try {
+ const res = await api.purgeCloudflareCache(zoneId, { files });
+ const n = res.purged?.files?.length ?? files.length;
+ toast.success(`Purged ${n} URL${n === 1 ? '' : 's'} from cache`);
+ setPurgeUrls('');
+ } catch (err) {
+ toast.error(err.message || 'Failed to purge URLs');
+ } finally {
+ setPurging(false);
+ }
+ };
+
if (loading) return <PageLoader />;
const crumbs = (
@@ -189,9 +226,64 @@ const CloudflareZoneSettings = () => {
</p>
)}
</div>
+
+ <div className="cf-panel cf-actions">
+ <div className="cf-action">
+ <div className="cf-action__text">
+ <h3><Eraser size={15} /> Purge cache</h3>
+ <p>
+ Clear Cloudflare&apos;s cached copy of your site so visitors get
+ fresh content. Purge everything, or list specific URLs below.
+ </p>
+ </div>
+ <Button
+ variant="destructive"
+ onClick={() => setConfirmPurgeAll(true)}
+ disabled={purging || !isAdmin}
+ >
+ {purging ? 'Purging…' : 'Purge everything'}
+ </Button>
+ </div>
+ <div className="cf-purge-files">
+ <label htmlFor="cf-purge-urls" className="cf-purge-files__label">
+ Purge specific URLs (one per line, up to 30)
+ </label>
+ <Textarea
+ id="cf-purge-urls"
+ rows={4}
+ placeholder={'https://example.com/style.css\nhttps://example.com/app.js'}
+ value={purgeUrls}
+ disabled={purging || !isAdmin}
+ onChange={(e) => setPurgeUrls(e.target.value)}
+ />
+ <div className="cf-purge-files__actions">
+ <Button
+ variant="outline"
+ onClick={handlePurgeFiles}
+ disabled={purging || !isAdmin || !purgeUrls.trim()}
+ >
+ Purge URLs
+ </Button>
+ </div>
+ </div>
+ </div>
</TabsContent>
</Tabs>
</div>
+
+ {confirmPurgeAll && (
+ <ConfirmDialog
+ isOpen
+ title="Purge entire cache"
+ message={`Clear Cloudflare's entire cache for ${zone?.domain || 'this zone'}? `
+ + 'The next visit to each page will be served from your origin until '
+ + 'it re-caches. This is safe but can briefly increase origin load.'}
+ confirmText="Purge everything"
+ onConfirm={handlePurgeEverything}
+ onCancel={() => setConfirmPurgeAll(false)}
+ variant="danger"
+ />
+ )}
</div>
);
};
diff --git a/frontend/src/services/api/cloudflare.js b/frontend/src/services/api/cloudflare.js
index f21b3824..71bb182a 100644
--- a/frontend/src/services/api/cloudflare.js
+++ b/frontend/src/services/api/cloudflare.js
@@ -22,3 +22,12 @@ export async function applyCloudflareSettingsPreset(zoneId) {
method: 'POST',
});
}
+
+// Purge the zone's Cloudflare cache. payload is { purge_everything: true } or
+// { files: [...] } (and on Enterprise, hosts/prefixes/tags).
+export async function purgeCloudflareCache(zoneId, payload) {
+ return this.request(`/cloudflare/zones/${zoneId}/purge-cache`, {
+ method: 'POST',
+ body: payload,
+ });
+}
diff --git a/frontend/src/styles/pages/_cloudflare-zone.scss b/frontend/src/styles/pages/_cloudflare-zone.scss
index 93c02462..efb598ac 100644
--- a/frontend/src/styles/pages/_cloudflare-zone.scss
+++ b/frontend/src/styles/pages/_cloudflare-zone.scss
@@ -110,6 +110,8 @@
}
.cf-actions {
+ & + & { margin-top: $spacing-md; }
+
.cf-action {
display: flex;
align-items: center;
@@ -118,7 +120,13 @@
padding: $spacing-md 0;
&__text {
- h3 { margin: 0 0 4px; font-size: 1rem; }
+ h3 {
+ margin: 0 0 4px;
+ font-size: 1rem;
+ display: inline-flex;
+ align-items: center;
+ gap: $spacing-xs;
+ }
p { margin: 0; color: $text-muted; font-size: 0.88rem; max-width: 60ch; line-height: 1.5; }
}
}
@@ -129,3 +137,21 @@
font-size: 0.85rem;
}
}
+
+.cf-purge-files {
+ border-top: 1px solid $border-color;
+ padding-top: $spacing-md;
+
+ &__label {
+ display: block;
+ font-size: 0.85rem;
+ color: $text-secondary;
+ margin-bottom: $spacing-xs;
+ }
+
+ &__actions {
+ display: flex;
+ justify-content: flex-end;
+ margin-top: $spacing-sm;
+ }
+}