Merge pull request #927 from AvaloniaUI/update-caching

Implement 5-min client caching and 7-day edge caching with purge on deploy

Author: msivers

.github/workflows/docs-avaloniaui-net.yml

@@ -130,3 +130,14 @@ jobs:
           npx wrangler kv bulk put redirects/kv-redirects.json \
             --namespace-id ae8131374b0d409e9ab0537882dafe0b \
             --remote
+
+      - name: Purge Cloudflare edge cache
+        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+        run: |
+          curl -sf -X POST \
+            "https://api.cloudflare.com/client/v4/zones/aaa9cb3f1e40e56edad4ceba5226d0e0/purge_cache" \
+            -H "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
+            -H "Content-Type: application/json" \
+            --data '{"hosts":["docs.avaloniaui.net"]}'

README.md

@@ -105,6 +105,20 @@ If you want API reference content to regenerate automatically before every local
 
 Do not commit these hooks, as CI does not have `dotnet-apiref` installed and the build will fail. The generated API reference files are already committed to the repository.
 
+## Caching
+
+The site is served through a Cloudflare Worker ([`workers/docs-redirects`](workers/docs-redirects)) which handles redirects, trailing-slash normalization, and edge caching.
+
+| Content | Edge (Cloudflare) | Browser |
+|---|---|---|
+| Hashed assets (`/assets/*`) | 1 year | 1 year, immutable |
+| Other static files (`/img/*`, etc.) | Respects origin headers | 5 min |
+| HTML pages | 7 days | 5 min |
+
+The edge cache for `docs.avaloniaui.net` is automatically purged on every deploy to `main`, so content updates are served immediately.
+
+See [`workers/docs-redirects/README.md`](workers/docs-redirects/README.md) for full details.
+
 ## Thanks 💜
 
 Thanks for all your contributions and efforts towards improving the Avalonia UI documentation. We thank you being part of our ✨ community ✨!

redirects/cloudflare_worker_kv_redirects/README.md

@@ -43,9 +43,12 @@ This produces `kv-redirects.json` (gitignored).
 
 ```bash
 npx wrangler kv bulk put kv-redirects.json \
-  --namespace-id ae8131374b0d409e9ab0537882dafe0b
+  --namespace-id ae8131374b0d409e9ab0537882dafe0b \
+  --remote
 ```
 
+> **Note:** Wrangler v4 defaults to local KV. The `--remote` flag is required to write to the production KV namespace.
+
 ## CI/CD
 
 KV entries are automatically regenerated and uploaded on every deploy to `main` via the `docs.avaloniaui.net CI/CD` GitHub Actions workflow (`.github/workflows/docs-avaloniaui-net.yml`). A validation step checks that all redirect targets point to allowed domains (`docs.avaloniaui.net`, `github.com/AvaloniaUI`) before uploading.

workers/docs-redirects/README.md

@@ -6,15 +6,16 @@ Cloudflare Worker that handles server-side redirects and trailing-slash normaliz
 
 1. **KV redirects** — Looks up the request path in the `DOCS_REDIRECTS` KV namespace. If a match is found, returns a `301` redirect to the target URL.
 2. **Trailing-slash rewrite** — If no redirect is found and the path looks like a page (no file extension), the Worker internally rewrites the request to append a trailing slash. S3-compatible object storage (e.g. AWS, Scaleway) always returns a `302` redirect to the trailing-slash version when a path is requested without one (e.g. `/docs/welcome` → `302` → `/docs/welcome/`). This rewrite eliminates that round-trip by fetching the trailing-slash path internally, so the browser gets the page directly.
-3. **Static asset bypass** — Requests for static assets (`.js`, `.css`, `.png`, etc. and `/assets/*` paths) skip KV lookup entirely and pass straight through to origin.
+3. **Edge caching** — HTML pages are cached at the Cloudflare edge for 7 days (`cacheTtl: 604800`, `cacheEverything: true`). Browsers receive `Cache-Control: public, max-age=300` (5 minutes). The edge cache is purged by hostname on every deploy via the CI/CD workflow, so new content is served immediately after a push to `main`.
+4. **Static asset bypass** — Requests for static assets (`.js`, `.css`, `.png`, etc. and `/assets/*` paths) skip KV lookup and edge caching, passing straight through to origin (Cloudflare caches these by default based on file extension).
 
 ## Request flow
 
 ```
 Browser request
        │
        ▼
-  Static asset? ──YES──▶ passthrough to origin
+  Static asset? ──YES──▶ passthrough to origin (cached by file extension)
        │
       NO
        ▼
@@ -25,13 +26,24 @@ Browser request
        │
     NOT FOUND
        ▼
-  Needs trailing slash? ──YES──▶ rewrite: fetch(path/) internally
+  Needs trailing slash? ──YES──▶ rewrite: fetch(path/) with edge cache
        │
       NO
        ▼
-  passthrough to origin
+  fetch with edge cache ──▶ origin (7-day edge TTL, 5-min browser TTL)
 ```
 
+## Caching strategy
+
+| Content | Edge (Cloudflare) | Browser | Set by |
+|---|---|---|---|
+| Hashed assets (`/assets/*`) | 1 year | 1 year, immutable | Origin `Cache-Control` header (set during S3 upload) |
+| Other static files (`/img/*`, etc.) | Cloudflare default (respects origin headers) | 5 min | Origin `Cache-Control` header (set during S3 upload) |
+| HTML pages | 7 days | 5 min | Worker `cf` fetch options + `withBrowserCache` |
+| KV redirects (301s) | N/A (generated by Worker) | 24 hours | Worker response header |
+
+The edge cache for `docs.avaloniaui.net` is purged by hostname on every deploy to `main` via the CI/CD workflow, so new content is available immediately regardless of edge TTL.
+
 ## Configuration
 
 - **Route**: `docs.avaloniaui.net/*`

workers/docs-redirects/src/index.ts

@@ -4,6 +4,11 @@ export interface Env {
 
 const STATIC_EXT = /\.(?:js|css|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot|map|json|xml|txt|webp|avif|mp4|webm)$/i;
 
+const EDGE_CACHE: RequestInitCfProperties = {
+  cacheTtl: 604800,
+  cacheEverything: true,
+};
+
 function isStaticAsset(path: string): boolean {
   return path.startsWith('/assets/') || path.startsWith('/img/') || STATIC_EXT.test(path);
 }
@@ -59,10 +64,19 @@ export default {
       const rewrittenUrl = new URL(request.url);
       rewrittenUrl.pathname = url.pathname + '/';
       const rewrittenRequest = new Request(rewrittenUrl.toString(), request);
-      return fetch(rewrittenRequest);
+      return withBrowserCache(await fetch(rewrittenRequest, { cf: EDGE_CACHE }));
     }
 
     // Default: passthrough to origin
-    return fetch(request);
+    return withBrowserCache(await fetch(request, { cf: EDGE_CACHE }));
   },
 };
+
+function withBrowserCache(response: Response): Response {
+  if (response.headers.has('Cache-Control')) {
+    return response;
+  }
+  const newResponse = new Response(response.body, response);
+  newResponse.headers.set('Cache-Control', 'public, max-age=300');
+  return newResponse;
+}