# Cache busting, builds en distributie (Parcel v2 + manifest)

Dit document beschrijft hoe cache busting nu structureel is geïmplementeerd met Parcel v2 (filename hashing) en hoe je builds en distributie uitvoert in de verschillende omgevingen.

## Overzicht van de aanpak

- Parcel v2 bouwt de frontend bundles met content-hashes in de bestandsnamen (bijv. `/static/dist/chat-client.abcd123.js`).
- We bouwen via minimale HTML entries (frontend_src/entries/*.html) die de JS importeren; dit dwingt Parcel tot consistente hashing en CSS-extractie.
- Na de build schrijven we een `manifest.json` in `nginx/static/dist/` met een mapping van logische namen naar gehashte paden.
- Templates gebruiken nu `asset_url('dist/chat-client.js|css')` om automatisch naar de juiste gehashte bestanden te verwijzen.
- Nginx (DEV/TEST) is ingesteld om voor `/static/dist/` lange cache headers te sturen: `Cache-Control: public, max-age=31536000, immutable`.
- HTML krijgt geen agressieve caching via Nginx; de browser ontdekt bij volgende request de nieuwe gehashte asset-URLs.
- In STAGING/PROD (Ingress + Bunny) volg je dezelfde principes; CDN ziet unieke URLs en cachet langdurig, zonder purges te vereisen.

## Relevante bestanden die zijn aangepast/toegevoegd

- `nginx/package.json`
  - DevDependency: `@parcel/reporter-bundle-manifest` toegevoegd.
  - `postbuild` script toegevoegd (optioneel; puur informatief).
- `nginx/.parcelrc`
  - Parcel reporter geconfigureerd zodat `manifest.json` wordt weggeschreven.
- `common/utils/template_filters.py`
  - Nieuwe Jinja global `asset_url(logical_path)` geregistreerd.
- `eveai_chat_client/asset_manifest.py`
  - Hulpfuncties om manifest in te lezen en paden te resolven met caching.
- `eveai_chat_client/templates/base.html` en `templates/scripts.html`
  - CSS/JS referenties omgezet naar `{{ asset_url('dist/chat-client.css|js') }}`.
- `nginx/nginx.conf`
  - Extra location voor `/static/dist/` met lange cache headers.

## Build uitvoeren (lokaal of in CI)

1. Ga naar de `nginx` directory.
2. Installeer dependencies (eenmalig of na wijzigingen):
   - `npm install`
3. Run build:
   - `npm run clean`
   - `npm run build`

Resultaat:
- Bundles met content-hash in `nginx/static/dist/`
- `nginx/static/dist/manifest.json` aanwezig

Tip: De build wordt ook aangeroepen door het bestaande script `docker/rebuild_chat_client.sh`.

## rebuild_chat_client.sh

Script: `docker/rebuild_chat_client.sh`
- Kopieert client images naar `nginx/static/assets/img`.
- Voert vervolgens `npm run clean` en `npm run build` uit in `nginx/`.
- Bouwt en pusht daarna de `nginx` container.

Door de nieuwe Parcel configuratie zal de build automatisch `manifest.json` genereren en gehashte assets outputten. Er zijn geen extra stappen nodig in dit script.

## Hoe de templates de juiste bestanden vinden

- De Jinja global `asset_url()` zoekt in `manifest.json` de gehashte bestandsnaam op basis van een logische naam.
- Voorbeelden in templates:
  - CSS: `{{ asset_url('dist/chat-client.css') }}`
  - JS: `{{ asset_url('dist/chat-client.js') }}`
- Als het manifest onverhoopt ontbreekt (bijv. in een edge-case), valt `asset_url` automatisch terug naar het on-gehashte pad onder `/static/` zodat de pagina niet breekt.

## Nginx (DEV/TEST)

In `nginx/nginx.conf` is toegevoegd:

```
location ^~ /static/dist/ {
    alias /etc/nginx/static/dist/;
    add_header Cache-Control "public, max-age=31536000, immutable" always;
}
```

- Hiermee krijgen gehashte assets lange caching. Omdat de URL wijzigt bij iedere inhoudswijziging, halen browsers/CDN de nieuwe versie zonder problemen op.
- HTML wordt niet agressief gecachet door Nginx; wil je volledig no-cache afdwingen voor HTML, dan kun je dat ook applicatie‑zijde doen (Flask) of via extra Nginx rules voor specifieke HTML routes.

## Ingress (STAGING/PROD) en Bunny.net

- Ingress: Zet (indien nog niet aanwezig) voor het pad dat `/static/dist/` serveert een configuration snippet met dezelfde header:
  - `add_header Cache-Control "public, max-age=31536000, immutable" always;`
- HTML/endpoints laat je kort/no-cache of standaard; belangrijk is dat templates met nieuwe gehashte URLs snel door de clients worden opgepakt.
- Bunny.net (pull zone): CDN cachet op basis van volledige URL. Door de content-hash in de bestandsnaam zijn purges normaliter niet nodig.

## Troubleshooting / Tips

- Controleer na build of `manifest.json` bestaat:
  - `ls nginx/static/dist/manifest.json`
- Inspecteer headers in DEV:
  - `curl -I http://<host>/static/dist/chat-client.<hash>.js`
  - Moet `Cache-Control: public, max-age=31536000, immutable` tonen.
- Als een client toch oude CSS/JS toont:
  - Check of de geleverde HTML naar de nieuwste gehashte bestandsnaam verwijst (View Source / Network tab).
  - Zorg dat de HTML niet op CDN langdurig wordt gecachet.

## Samenvatting workflow per omgeving

- DEV/TEST (Nginx):
  1) `docker/rebuild_chat_client.sh` draaien (of handmatig `npm run build` in `nginx/`).
  2) Nginx container wordt vernieuwd met nieuwe `static/dist` inclusief manifest en gehashte bundles.

- STAGING/PROD (Ingress + Bunny):
  1) Zelfde build, gehashte bundles en manifest worden gedeployed via container image.
  2) Ingress dient `/static/dist/` met lange cache headers.
  3) Bunny.net cachet de nieuwe URLs automatisch; purgen niet nodig.

Met deze setup combineren we maximale performance (lange caching) met directe updates (nieuwe URL bij wijziging).