1 Commits
Author SHA1 Message Date
sneak ec3d2b9e9f Name pixa's concepts at the start of the README's Design section (closes #321)
check / check (push) Canceled after 0s
The Design section starts with a Concepts list. Each concept gets one
sentence, under the name the code gives it. Storage calls the
transformed images variants, and the sentences it changed for that are
shorter. Its paths end in the source key and the variant key, and it
lists the image cache's tables in the database. Architecture names
internal/providers and lists the packages that work with the concepts.
No code or test changes.

Model: opus-5-5
2026-10-26 21:57:59 +00:00
+14 -7
View File
@@ -185,18 +185,24 @@ These terms are the names the code uses:
- **Source**: the image at one upstream URL, named by its host, path and query.
- **Source key**: the SHA-256 of a source's host, path and query, which names
the source's file and its row in the database.
- **Transform**: the output size and format an image request asks for, with its
quality and fit.
- **Transform**: the output size, format, quality and fit an image request asks
for; with the format `auto`, pixa chooses the output format from the `Accept`
header.
- **Image request**: a source and a transform, which each image route reads from
its URL.
- **Variant**: the image pixa serves for an image request, made from its source
with its transform.
- **Variant key**: the SHA-256 of an image request, which names the variant's
file and its row in the database, and gives its `ETag`.
- **Variant key**: the SHA-256 of a variant's source, size, format, quality and
fit, which names the variant's file and its row in the database, and gives its
`ETag`.
- **Signed URL**: a `/v1/image/` URL whose `sig` signs its image request and its
expiry `exp` with `signing_key`.
- **Encrypted URL**: a `/v1/e/` URL whose token holds an image request and its
expiry, encrypted with a key derived from `signing_key`.
- **Encrypted URL**: a `/v1/e/` URL whose token encrypts its image request, and
its expiry unless the URL lasts forever, with a key derived from
`signing_key`.
- **Login session**: an encrypted cookie that keeps a browser logged in to the
generator page for 30 days, or until a logout replaces the random value pixa
keeps in the `logout` table (see Encrypted URLs).
- **Negative cache**: the source URLs pixa does not fetch again for 5 minutes,
after one of these failed fetches:
- the upstream answered with an error status
@@ -256,7 +262,7 @@ hit hands the time it was served to a background writer and does not wait for
the writer. Eviction orders by that time. The hit is counted in memory. A miss
that uses a cached source image also hands that writer the time it used the
image. Once a second that writer writes the waiting times in one transaction. Up
to 10,000 times of variants, and as many of sources, can be waiting to be
to 10,000 access times of variants, and as many of sources, can wait to be
written. A time handed over beyond that is dropped. Its image then only looks
less recently used to eviction. `script/bench` measures how many hits pixa
serves per second (see Load Test).
@@ -935,6 +941,7 @@ See `configs/config.example.yml` for all options with defaults.
- `encurl`: making and reading the tokens of encrypted URLs
- `seal`: the keys derived from `signing_key`, and the encryption of those
tokens
- `session`: the login session
- **HTTP router**: go-chi
- **Image processing**: govips (CGO wrapper for libvips)
- **Database**: SQLite via modernc.org/sqlite