README describes storage paths, formats, and features that do not match the code #74

New Issue

2026-08-09T03:47:33+02:00

clawbot commented

2026-08-09 03:47:33 +02:00

Verified against main at 61f42e6. Docs-only issue; each item is a factual mismatch between README.md and the implementation.

On-disk layout is wrong. README.md:38-45 documents <statedir>/cache/src-content/, cache/src-metadata/, and cache/dst-content/. The actual directories (internal/imgcache/cache.go:52-65) are cache/sources, cache/variants, cache/metadata. The SQL schema comments repeat the README's wrong paths (internal/database/schema/001_initial_schema.sql, lines 5, 12, 38). Fix the docs (renaming the directories would be a migration for no benefit).
The format list contradicts itself. README.md:59 says <format> is one of orig, png, jpeg, webp. README.md:88, in the signature spec, lists jpeg, png, webp, avif, gif, orig. The code (internal/imgcache/urlparser.go:241-258) accepts jpg, avif, gif, and original as well. Make one accurate list.
allow_http is undocumented and contradicts a stated guarantee. README.md:57 states "Images are only fetched from origins using TLS with valid certificates." config.example.yml:26 documents allow_http, and internal/httpfetcher/httpfetcher.go:300-303 honors it. The README should describe the guarantee as conditional and document the key.
Two Architecture claims overstate what exists.
- README.md:49 — "In-process caching of request-to-output mappings targets 1-5k r/s". The field backing this is dead (filed separately). Either that issue implements it or this line must go.
- README.md:128 — "Metrics: Prometheus" implies pixa-specific metrics. Only generic HTTP metrics exist, and only when metrics credentials are configured (filed separately).

Definition of done

Items 1-3 corrected in README.md; item 1 also corrected in the 001_initial_schema.sql comments.
Items 4a/4b either corrected or explicitly deferred with a link to the issue that will make them true — no claim left standing that the code does not support.
make fmt run so the markdown matches repo formatting (prettier, 4-space tabs, proseWrap: always); formatted output committed.
make check green.

Process note

Docs-only (plus SQL comments). Per repo policy this skips adversarial review and goes straight to merge-ready once make check is green — provided the change really touches nothing but comments and markdown.

Verified against `main` at `61f42e6`. Docs-only issue; each item is a factual mismatch between `README.md` and the implementation. 1. **On-disk layout is wrong.** `README.md:38-45` documents `<statedir>/cache/src-content/`, `cache/src-metadata/`, and `cache/dst-content/`. The actual directories (`internal/imgcache/cache.go:52-65`) are `cache/sources`, `cache/variants`, `cache/metadata`. The SQL schema comments repeat the README's wrong paths (`internal/database/schema/001_initial_schema.sql`, lines 5, 12, 38). Fix the docs (renaming the directories would be a migration for no benefit). 2. **The format list contradicts itself.** `README.md:59` says `<format>` is one of `orig`, `png`, `jpeg`, `webp`. `README.md:88`, in the signature spec, lists `jpeg, png, webp, avif, gif, orig`. The code (`internal/imgcache/urlparser.go:241-258`) accepts `jpg`, `avif`, `gif`, and `original` as well. Make one accurate list. 3. **`allow_http` is undocumented and contradicts a stated guarantee.** `README.md:57` states "Images are only fetched from origins using TLS with valid certificates." `config.example.yml:26` documents `allow_http`, and `internal/httpfetcher/httpfetcher.go:300-303` honors it. The README should describe the guarantee as conditional and document the key. 4. **Two Architecture claims overstate what exists.** - `README.md:49` — "In-process caching of request-to-output mappings targets 1-5k r/s". The field backing this is dead (filed separately). Either that issue implements it or this line must go. - `README.md:128` — "**Metrics**: Prometheus" implies pixa-specific metrics. Only generic HTTP metrics exist, and only when metrics credentials are configured (filed separately). ## Definition of done 1. Items 1-3 corrected in `README.md`; item 1 also corrected in the `001_initial_schema.sql` comments. 2. Items 4a/4b either corrected or explicitly deferred with a link to the issue that will make them true — no claim left standing that the code does not support. 3. `make fmt` run so the markdown matches repo formatting (prettier, 4-space tabs, `proseWrap: always`); formatted output committed. 4. `make check` green. ## Process note Docs-only (plus SQL comments). Per repo policy this skips adversarial review and goes straight to `merge-ready` once `make check` is green — provided the change really touches nothing but comments and markdown.

clawbot added this to the 1.0.0 milestone 2026-08-09 03:47:33 +02:00

clawbot referenced this issue

2026-08-09 16:10:39 +02:00

Tracking: 1.0.0 sequencing and critical path #103

clawbot referenced this issue

2026-10-03 14:28:20 +02:00

Recommendations for a clearer, simpler object and data model #168

clawbot referenced this issue

2026-10-03 14:30:55 +02:00

Review toward 1.0: identify and file all next steps #109

clawbot referenced this issue

2026-10-03 18:24:29 +02:00

Review toward 1.0: identify and file all next steps #109

clawbot commented

2026-10-04 01:33:46 +02:00

Plan, checked against next at 021516e:

README.md "Storage": name the directories the code uses (cache/sources, cache/variants, cache/metadata, from internal/imgcache/cache.go) and how files are named under each, as internal/imgcache/storage.go does it. The comments in internal/db/migrations/001_schema.sql that repeat the old paths get the same correction; no schema change.
One accurate list of output formats, used both under "Routes" and in the signature section: what internal/imgcache/urlparser.go accepts, jpg and original included.
"Images are only fetched from origins using TLS with valid certificates" becomes true as written: it holds unless allow_http is set, which the settings table already documents.
Item 4a is already true: since #70 pixa keeps content types in memory, and the README now says only that. No change unless the wording claims more.
Item 4b: "Metrics: Prometheus" says what exists on next (the generic HTTP metrics at /metrics, and when they are collected), nothing more.
make fmt. The issue's process note is out of date: docs-only changes get an independent review like any other unit.

Model: opus-5-5

Plan, checked against `next` at `021516e`: - `README.md` "Storage": name the directories the code uses (`cache/sources`, `cache/variants`, `cache/metadata`, from `internal/imgcache/cache.go`) and how files are named under each, as `internal/imgcache/storage.go` does it. The comments in `internal/db/migrations/001_schema.sql` that repeat the old paths get the same correction; no schema change. - One accurate list of output formats, used both under "Routes" and in the signature section: what `internal/imgcache/urlparser.go` accepts, `jpg` and `original` included. - "Images are only fetched from origins using TLS with valid certificates" becomes true as written: it holds unless `allow_http` is set, which the settings table already documents. - Item 4a is already true: since https://git.eeqj.de/sneak/pixa/issues/70 pixa keeps content types in memory, and the README now says only that. No change unless the wording claims more. - Item 4b: "Metrics: Prometheus" says what exists on `next` (the generic HTTP metrics at `/metrics`, and when they are collected), nothing more. - `make fmt`. The issue's process note is out of date: docs-only changes get an independent review like any other unit. Model: opus-5-5

clawbot referenced this issue from a commit

2026-10-04 05:31:02 +02:00

Make the README's storage, formats, TLS and metrics match the code (closes #74)

clawbot referenced a pull request that will close this issue

2026-10-04 05:36:31 +02:00

Make the README's storage paths, formats, TLS and metrics match the code (closes #74) #172

clawbot commented

2026-10-04 05:36:37 +02:00