fetchspec

Overview ¶

Command fetchspec downloads the Freelo OpenAPI document with a conditional GET, replacing the plain `curl` call that used to open `make gen`.

Why this exists: `make gen-check` runs on every CI push and on the weekly spec refresh, and each run re-transferred the full ~270 KB document even when upstream had not changed. A conditional request lets the server answer "304 Not Modified" instead, and gives us a recorded fingerprint of the exact upstream bytes the committed spec was derived from.

Cache metadata lives next to the spec in a small JSON file that is committed to the repo — CI checks out a fresh tree, so an uncommitted cache would never produce a 304 there. The file therefore holds only stable fields (no timestamps): an unchanged spec must serialize byte-identically, otherwise `gen-check`'s `git diff` would report drift on every run.

Three fields, three jobs:

etag / last_modified  validators echoed back as If-None-Match /
                      If-Modified-Since to earn the 304.
raw_sha256            hash of the upstream body, so a server that sends no
                      validators (see below) can still be told "unchanged".
patched_sha256        hash of spec/freelo-api.yaml *after* the patch
                      pipeline, recorded by -seal. Guards the shortcut: a
                      hand-edited spec must not be able to hide behind a
                      304, so a fingerprint mismatch drops the validators
                      and forces a full re-download.

As of this writing api.freelo.io sends neither ETag nor Last-Modified for the spec (it replies `cache-control: no-cache, private`), so every run currently takes the 200 path and falls back to comparing raw_sha256 — the same work the old curl did, plus a definitive changed/unchanged verdict. The conditional headers start paying off, with no further change here, the day upstream emits a validator.

Usage (see the `gen` target):

go run ./scripts/fetchspec -url URL -out spec.yaml -meta meta.json
go run ./scripts/fetchspec -seal  -out spec.yaml -meta meta.json

-force skips the validators for one run and always rewrites the spec from the response body. Exit status is 0 for both "changed" and "unchanged"; only a genuine failure is non-zero.