From 9a5ef06c804b89d0972eec94fee69d7f94ea548e Mon Sep 17 00:00:00 2001 From: clawbot <35+clawbot@noreply.example.org> Date: Mon, 5 Oct 2026 02:42:58 +0000 Subject: [PATCH] Serve the format auto, chosen from the Accept header (closes #88) auto is a format in the /v1/image/ path, an encrypted URL's token and the generator page. Once the signature or token is checked, pixa chooses AVIF when Accept names image/avif, else WebP when it names image/webp, else JPEG when the most specific of image/jpeg, image/* and */* allows it or Accept is absent. q=0 refuses a format; a header allowing none of the three answers 406, one that does not parse 400. The signature and token cover auto itself; the cache key and ETag use the chosen format. Answers from then on carry Vary: Accept. Model: opus-5-5 --- README.md | 42 +++++++--- TODO.md | 13 ++- internal/handlers/auth.go | 2 +- internal/handlers/format_auto.go | 131 ++++++++++++++++++++++++++++++ internal/handlers/image.go | 5 ++ internal/handlers/imageenc.go | 2 +- internal/imgcache/imgcache.go | 5 ++ internal/imgcache/urlparser.go | 2 + internal/templates/generator.html | 1 + 9 files changed, 189 insertions(+), 14 deletions(-) create mode 100644 internal/handlers/format_auto.go diff --git a/README.md b/README.md index 95d9079..bfa0451 100644 --- a/README.md +++ b/README.md @@ -175,12 +175,14 @@ path under `/v1/` answers 200, in maintenance mode too. - `GET` or `HEAD` `/v1/image///.` — an image, fetched, resized and converted (below). Needs: a signature, unless the host is allowlisted (see Source Hosts). Answers: 200; 304 when `If-None-Match` matches - the image's `ETag`; 400 for a URL or parameter that is not valid; 401 for a - missing or wrong signature, a missing `exp` or an `exp` in the past; 403 when - the request's `Referer` names a host in `referer_blocklist`, checked before - the signature, the cache and the upstream fetch; 403 when the upstream host, - or a host it redirects to, is `localhost`, ends in `.localhost` or `.local`, - or has an address in a blocked network (see `blocked_networks`); 502 when the + the image's `ETag`; 400 for a URL or parameter that is not valid, or for the + format `auto` an `Accept` header that is not valid; 406 for the format `auto` + when `Accept` allows none of the formats it chooses from; 401 for a missing or + wrong signature, a missing `exp` or an `exp` in the past; 403 when the + request's `Referer` names a host in `referer_blocklist`, checked before the + signature, the cache and the upstream fetch; 403 when the upstream host, or a + host it redirects to, is `localhost`, ends in `.localhost` or `.local`, or has + an address in a blocked network (see `blocked_networks`); 502 when the upstream answered with an error status, and for 5 minutes after that for the same source URL; 503 when pixa is busy or in maintenance mode; 500 for any other failure. @@ -190,7 +192,8 @@ path under `/v1/` answers 200, in maintenance mode too. decrypt, or that asks for a size or fit that is not valid; 410 once it has expired; 504 when the upstream has not sent its response headers within `upstream_fetch_timeout`, but 500 when that time runs out while the image - itself is still arriving; 403, 502, 503 and 500 as for `/v1/image/`. + itself is still arriving; 400 for an `Accept` header that is not valid, and + 406, 403, 502, 503 and 500, as for `/v1/image/`. - `GET /robots.txt` — asks every crawler to stay away (`Disallow: /`). Needs: nothing. Answers: 200. - `GET /.well-known/healthcheck.json` — JSON with `status` (`ok`), `now`, @@ -239,7 +242,7 @@ A request whose query string cannot be decoded, or gives any parameter more than once, is refused with 400. - ``: one of `orig` (or `original`), `jpeg` (or `jpg`), `png`, `webp`, - `avif`, `gif` + `avif`, `gif`, or `auto` (below) - ``: `orig` or `x` (e.g. `800x600`) - `sig` and `exp`: the signature and its expiry, needed unless the host is allowlisted (see Signature Specification) @@ -247,6 +250,24 @@ once, is refused with 400. both optional (values under Signature Specification). Both are part of what is cached, so each value of either is a separate cached image. +With the format `auto`, pixa chooses the format for each request from its +`Accept` header, in this order: + +1. AVIF, when the header names `image/avif`; +2. WebP, when it names `image/webp`; +3. JPEG, when the first of `image/jpeg`, `image/*` and `*/*` that it names + allows it, or when there is no `Accept` header or it is empty. + +An entry with `q=0` refuses its format; other `q` values do not change the +order. AVIF and WebP must be named, as clients that cannot show them also send +`image/*` and `*/*`. pixa never sends a format the client refused: when the +header allows none of the three, the answer is 406, and a header that does not +parse, or has a `q` that is not a number from 0 to 1, is refused with 400. The +signature, or the token of an encrypted URL, covers `auto` itself, so one URL +serves every client. Each format chosen is cached as a separate image, and every +answer that depends on `Accept` (the image, a 304, and the 400 and 406 above) +carries `Vary: Accept`, so a shared cache keeps the formats apart too. + An image is served with `Cache-Control: public, max-age=, immutable`. When the URL has an expiry (an `exp`, or the TTL of an encrypted URL), `max-age` is the whole seconds left until then, at most one year, so no browser or proxy @@ -297,7 +318,7 @@ nor change what it asks for. 3. The page shows the URL, `https:///v1/e//img.`, and when it expires. `` is the host the page was opened on, and the URL starts with `http` instead while `debug` is on. The name after the token is ignored - and only gives the URL a file extension, `jpg` for `orig`. + and only gives the URL a file extension, `jpg` for `orig` and `auto`. The token holds the source's host, path and query and the size, format, quality, fit and expiry, encrypted with a key derived from `signing_key`. The source @@ -353,7 +374,8 @@ Where: - `width` — requested width in pixels, `0` for original - `height` — requested height in pixels, `0` for original - `format` — output format, one of those listed under Routes, with `original` - signed as `orig` and `jpg` as `jpeg` + signed as `orig` and `jpg` as `jpeg`; `auto` is signed as `auto`, not as the + format chosen for the request - `expiration` — the URL's `exp` query parameter, the Unix timestamp when the signature expires; a request whose `exp` is not a whole number, an empty `exp=` included, is refused with 400 diff --git a/TODO.md b/TODO.md index cabe9e2..3cc0295 100644 --- a/TODO.md +++ b/TODO.md @@ -30,6 +30,17 @@ P2: security: per-IP rate limiting on the image routes # Completed Steps +- 2026-10-05 the format `auto` (closes #88): a format in the `/v1/image/` path, + an encrypted URL's token and the generator page's format choice, chosen for + each request from `Accept` once the signature or token is checked: AVIF when + the header names `image/avif`, else WebP when it names `image/webp`, else JPEG + when the first of `image/jpeg`, `image/*` and `*/*` that it names allows it, + or when it names nothing; `q=0` refuses a format. AVIF and WebP must be named, + as clients that cannot show them send the wildcards too. A header that allows + none of the three answers 406, one that does not parse 400. The signature and + the token cover `auto` itself; the cache key and `ETag` use the format chosen. + Answers from the point the format is chosen carry `Vary: Accept`, next to the + CORS `Vary: Origin`; fixed-format answers do not. - 2026-10-05 the markdown is formatted with prettier (closes #100): `script/fmt` and `script/fmt-check` run prettier 3.8.1, pinned in `package.json` and `yarn.lock`, on `**/*.md` after `gofmt`, with four-space tabs and @@ -661,8 +672,6 @@ P2: security: per-IP rate limiting on the image routes - per-origin rate limiting - P2: HTTP response handling - Last-Modified headers - - Vary header for content negotiation -- P2: auto format selection (format=auto based on Accept header) - P2: configuration - YAML config file support - P2: operational diff --git a/internal/handlers/auth.go b/internal/handlers/auth.go index a0ad493..8184ce9 100644 --- a/internal/handlers/auth.go +++ b/internal/handlers/auth.go @@ -371,7 +371,7 @@ func (s *Handlers) buildGeneratedURL(r *http.Request, token, format string) stri // Determine file extension for the trailing filename ext := format - if ext == "" || ext == "orig" { + if ext == "" || ext == "orig" || ext == "auto" { ext = "jpg" // Default extension } diff --git a/internal/handlers/format_auto.go b/internal/handlers/format_auto.go new file mode 100644 index 0000000..485faed --- /dev/null +++ b/internal/handlers/format_auto.go @@ -0,0 +1,131 @@ +package handlers + +import ( + "errors" + "fmt" + "mime" + "net/http" + "strconv" + "strings" + + "sneak.berlin/go/pixa/internal/imgcache" +) + +// Errors for an Accept header that an auto URL cannot be served for. +var ( + errInvalidAccept = errors.New("invalid Accept header") + errNotAcceptable = errors.New( + "not acceptable: auto serves image/avif, image/webp or image/jpeg") +) + +// chooseAutoFormat replaces the format auto in req with the format +// formatForAccept chooses from r's Accept header, and adds Vary: Accept to the +// response, which then depends on that header. It answers 400 for an Accept +// header that is not valid and 406 for one that allows none of the formats, +// and reports whether req can be served. Any other format is left as it is. +func (s *Handlers) chooseAutoFormat( + w http.ResponseWriter, r *http.Request, req *imgcache.ImageRequest, +) bool { + if req.Format != imgcache.FormatAuto { + return true + } + + w.Header().Add("Vary", "Accept") + + format, err := formatForAccept(strings.Join(r.Header.Values("Accept"), ",")) + if errors.Is(err, errNotAcceptable) { + s.respondError(w, err.Error(), http.StatusNotAcceptable) + + return false + } + + if err != nil { + s.respondError(w, err.Error(), http.StatusBadRequest) + + return false + } + + req.Format = format + + return true +} + +// formatForAccept returns the format an auto URL is served in for the Accept +// header accept: AVIF when it names image/avif, else WebP when it names +// image/webp, else JPEG when its most specific entry of image/jpeg, image/* +// and */* allows it, or when it names nothing. A q of 0 refuses a format. +// AVIF and WebP must be named, as clients that cannot show them send image/* +// and */* too. +func formatForAccept(accept string) (imgcache.ImageFormat, error) { + qualities, err := parseAccept(accept) + if err != nil { + return "", err + } + + if len(qualities) == 0 { + return imgcache.FormatJPEG, nil + } + + if qualities["image/avif"] > 0 { + return imgcache.FormatAVIF, nil + } + + if qualities["image/webp"] > 0 { + return imgcache.FormatWebP, nil + } + + // For JPEG, the most specific entry the header has decides + quality, named := qualities["image/jpeg"] + if !named { + quality, named = qualities["image/*"] + } + + if !named { + quality = qualities["*/*"] + } + + if quality > 0 { + return imgcache.FormatJPEG, nil + } + + return "", errNotAcceptable +} + +// parseAccept returns the q of each media range the Accept header accept +// names, 1 where it gives none. A media range named more than once keeps its +// lowest q, so a refusal is never overridden. A media range that does not +// parse, or a q that is not a number from 0 to 1, is an error. +func parseAccept(accept string) (map[string]float64, error) { + qualities := make(map[string]float64) + + for entry := range strings.SplitSeq(accept, ",") { + // A header field list may hold empty entries + if strings.TrimSpace(entry) == "" { + continue + } + + mediaRange, params, err := mime.ParseMediaType(entry) + if err != nil { + return nil, fmt.Errorf("%w: %q: %w", errInvalidAccept, entry, err) + } + + quality := 1.0 + + if qParam, given := params["q"]; given { + quality, err = strconv.ParseFloat(qParam, 64) + inRange := quality >= 0 && quality <= 1 + + if err != nil || !inRange { + return nil, fmt.Errorf("%w: %q: q is not a number from 0 to 1", + errInvalidAccept, entry) + } + } + + previous, named := qualities[mediaRange] + if !named || quality < previous { + qualities[mediaRange] = quality + } + } + + return qualities, nil +} diff --git a/internal/handlers/image.go b/internal/handlers/image.go index e099799..b3c3c31 100644 --- a/internal/handlers/image.go +++ b/internal/handlers/image.go @@ -43,6 +43,11 @@ func (s *Handlers) HandleImage() http.HandlerFunc { return } + // The signature covers the format auto, not the format chosen + if !s.chooseAutoFormat(w, r, req) { + return + } + // Get cache key for logging cacheKey := imgcache.CacheKey(req) diff --git a/internal/handlers/imageenc.go b/internal/handlers/imageenc.go index a9c672f..bf79054 100644 --- a/internal/handlers/imageenc.go +++ b/internal/handlers/imageenc.go @@ -30,7 +30,7 @@ func (s *Handlers) HandleImageEnc() http.HandlerFunc { start := time.Now() req, ok := s.parseImageEncRequest(w, r) - if !ok { + if !ok || !s.chooseAutoFormat(w, r, req) { return } diff --git a/internal/imgcache/imgcache.go b/internal/imgcache/imgcache.go index 1647658..7069f9e 100644 --- a/internal/imgcache/imgcache.go +++ b/internal/imgcache/imgcache.go @@ -22,6 +22,11 @@ const ( FormatWebP ImageFormat = "webp" FormatAVIF ImageFormat = "avif" FormatGIF ImageFormat = "gif" + + // FormatAuto stands for AVIF, WebP or JPEG, chosen for each request + // from its Accept header once the URL's signature or token has been + // checked; it is never processed or cached as itself. + FormatAuto ImageFormat = "auto" ) // Size represents requested image dimensions diff --git a/internal/imgcache/urlparser.go b/internal/imgcache/urlparser.go index a1a424c..b37d6ff 100644 --- a/internal/imgcache/urlparser.go +++ b/internal/imgcache/urlparser.go @@ -277,6 +277,8 @@ func parseFormat(s string) (ImageFormat, error) { return FormatAVIF, nil case "gif": return FormatGIF, nil + case "auto": + return FormatAuto, nil default: return "", fmt.Errorf("%w: %s", ErrInvalidFormat, s) } diff --git a/internal/templates/generator.html b/internal/templates/generator.html index 0f39502..8e6458e 100644 --- a/internal/templates/generator.html +++ b/internal/templates/generator.html @@ -95,6 +95,7 @@