# Architecture — git-pages

> Komponentit, datavirrat ja rajapinnat. Miksi näin on rakennettu: [design-rationale.md](design-rationale.md).
> Secretit: [secrets.md](secrets.md). Teknologiat: [tech-stack.md](tech-stack.md).

Tämä dokumentti koskee vain `git-pages/`-palvelua — ei juuren `gitea-ci-library`-kirjastoa.

---

## Yleiskuvaus

git-pages on jaettu **HTML-raporttiarkisto**: yksi apex-host, monta Gitea-repoa, commit-kohtaiset
raporttipolut. Julkaisija (esim. CI) puskaa sisällön tar-arkistona; lukija avaa raportin
selaimella commit-linkistä.

Codeberg git-pages ajaa `PAGES_INSECURE=1` — sovellus ei tee forge-authia. Julkaisu- ja
TLS-rajaukset ovat Kubernetes-kerroksessa (Traefik, cert-manager, Secretit).

---

## Komponentit

| Komponentti | Rooli |
|-------------|-------|
| **git-pages Pod** | Codeberg git-pages `0.9.1`, filesystem-storage `/app/data` |
| **retention sidecar** | Samassa podissa, HTTP API localhost:3000, siivoaa vanhat raportit |
| **PVC** | Raporttisisältö (storage v2 — `.index` + blob) |
| **Service** | ClusterIP :3000 git-pagesille |
| **Traefik IngressRoute** | Julkaisu (PATCH/PUT + BasicAuth) ja luku (GET/HEAD) eri säännöillä |
| **Traefik Middleware** | `git-pages-publish-auth` (BasicAuth), HTTPS-redirect |
| **cert-manager Certificate** | TLS → Secret `git-pages-tls` |

| Secret | Rooli |
|--------|-------|
| `git-pages-publish-auth` | htpasswd julkaisuun (Traefik) |
| `git-pages-publish-token` | plaintext token (Gitea Actions -secretiin vietäväksi) |
| `git-pages-retention-gitea` | Gitea PAT branch-tarkistukseen (sidecar)

---

## URL ja sisältö

Julkinen osoite:

```
https://ci-reports.helm-dev.keskikuja.site/niko/gitea-ci-library/reports/f4baa286/cucumber/index.html
         └────────── selvä URL ─────────┘ └───────────────── Gitea-yhteensopiva polku ─────────────────────────┘
```

Levyllä (apex index-site):

```
/app/data/site/{host}/
  .index          # Protobuf-manifesti (storage v2 — kaikki tiedostot tässä yhdessä tiedostossa)
```

Tiedostot eivät ole flat-FS:nä — katso `implementation-notes.md`.

Apex-juuri `/` on tyhjä — ei landing-sivua.

---

## Järjestelmäkaavio

```mermaid
flowchart TB
    subgraph ext["Ulkoiset"]
        PUB["Julkaisija\n(CI)"]
        BR["Selain"]
        GITEA["Gitea API\n(branch-lista)"]
    end

    subgraph edge["Reuna"]
        TRAEFIK["Traefik\nIngressRoute + Middleware"]
        CM["cert-manager\nTLS"]
    end

    subgraph cluster["git-pages Pod"]
        GP["git-pages\n(kontti)"]
        RT["retention sidecar\n(kontti)\nHTTP API localhost:3000"]
        PVC["PVC /app/data"]
    end

    PUB -->|"PATCH/PUT + BasicAuth\ntar"| TRAEFIK
    BR -->|"GET/HEAD"| TRAEFIK
    TRAEFIK --> GP
    CM --> TRAEFIK
    GP --> PVC
    RT -->|"reads .git-pages/manifest.json\nHTTP localhost"| GP
    RT -->|"check branches"| GITEA
```

---

## Julkaisu

1. Julkaisija paketoi `{owner}/{repo}/reports/{sha8}/` tar-arkistoksi (sis. `.meta`)
2. `PATCH` tai `PUT` apex-URL:iin (`https://{host}/`) + `Content-Type: application/x-tar`
3. Traefik tarkistaa BasicAuth (`publish` + token) → välittää git-pagesille
4. git-pages kirjoittaa PVC:lle

Julkaisu kulkee aina julkisen ingressin kautta — ei suoraa ClusterIP-kirjoitusta ulkopuolelta.

---

## Luku

1. Selain avaa commit-statuslinkin (GET/HEAD)
2. Traefik välittää git-pagesille ilman julkaisu-Middlewarea
3. git-pages palauttaa HTML:n polusta

Luku-auth (OIDC) ei ole toteutettu — GET/HEAD on julkinen, jos URL tunnetaan.
Katso [design-rationale.md — Luku-auth](design-rationale.md#luku-auth).

---

## Retention

Sidecar-kontti samassa podissa, ajaa retention-cleanup.sh 24h välein:

1. Lukee `.git-pages/manifest.json` HTTP:lla localhost:3000
2. Etsii `.meta`-tiedostot, tarkistaa iän ja branchin
3. **Poistettu branch** — jos `.meta.branch` ei ole Giteassa → whiteout PATCH
4. **Aktiivinen branch** — `maxAgeDays` + `keepMin` (`retention.rules`)
5. Whiteout-tar → PATCH localhost:3000 — poistaa raportit

Gitea API: `GET /api/v1/repos/{owner}/{repo}/branches/{branch}` — `read:repository` PAT.
Katso [secrets.md](secrets.md).

---

## Rajapinnat

| Suunta | Protokolla | Auth | Kuvaus |
|--------|------------|------|--------|
| Julkaisija → Traefik | HTTPS PATCH/PUT | BasicAuth `publish` | tar → apex site |
| Selain → Traefik | HTTPS GET/HEAD | — (tänään) | HTML-raportti |
| Sidecar → Gitea | HTTPS GET | PAT `read:repository` | branch-tarkistus per repo |
| Sidecar → git-pages | HTTP :3000 | — (PAGES_INSECURE) | manifestin luku + whiteout PATCH |
| Traefik → git-pages | HTTP :3000 | — | sisäverkko |

git-pages ei käytä Gitea forge-API:a julkaisuun eikä `pages`-branchia.