Return and pass on request IDs, and give /v1/e/ ETag, 304 and HEAD (closes #84)

Every response carries X-Request-Id, the upstream fetch sends it, and
the "upstream fetched", "image converted" and "image served" lines log
it as request_id. pixa's own RequestID middleware keeps a request's own
ID only when it is at most 64 letters, digits, '-', '_' or '.', and
otherwise makes a random one with crypto/rand, so nothing a client
chooses freely and nothing about the host reaches upstream. /v1/e/ now
sets ETag, answers a matching If-None-Match with 304 and is routed for
HEAD, through notModified, which both image handlers call. No Vary is
added: go-chi/cors already sends Vary: Origin.

Model: opus-5-5

internal/handlers/imageenc.go

@@ -9,6 +9,7 @@ import (
 	"time"
 
 	"github.com/go-chi/chi/v5"
+	"github.com/go-chi/chi/v5/middleware"
 
 	"sneak.berlin/go/pixa/internal/encurl"
 	"sneak.berlin/go/pixa/internal/httpfetcher"
@@ -24,43 +25,8 @@ func (s *Handlers) HandleImageEnc() http.HandlerFunc {
 		ctx := r.Context()
 		start := time.Now()
 
-		// Extract token from URL
-		token := chi.URLParam(r, "token")
-		if token == "" {
-			s.respondError(w, "missing token", http.StatusBadRequest)
-
-			return
-		}
-
-		// Decrypt and validate the payload
-		payload, err := s.encGen.Parse(token)
-		if err != nil {
-			if errors.Is(err, encurl.ErrExpired) {
-				s.log.Debug("encrypted URL expired", "error", err)
-				s.respondError(w, "URL has expired", http.StatusGone)
-
-				return
-			}
-
-			s.log.Debug("failed to decrypt URL", "error", err)
-			s.respondError(w, "invalid encrypted URL", http.StatusBadRequest)
-
-			return
-		}
-
-		// Convert payload to ImageRequest
-		req := payload.ToImageRequest()
-
-		// Apply the same dimension and fit-mode bounds as the plain image
-		// route: a sealed payload is trusted for its origin, not for staying
-		// within limits, so an over-limit size or unknown fit mode is a 400
-		// here rather than an out-of-memory or a 500 from the processor.
-		err = imgcache.ValidateImageRequest(req)
-		if err != nil {
-			s.log.Debug("encrypted URL failed validation", "error", err)
-			s.respondError(w, "invalid encrypted URL: "+err.Error(),
-				http.StatusBadRequest)
-
+		req, ok := s.parseImageEncRequest(w, r)
+		if !ok {
 			return
 		}
 
@@ -94,6 +60,17 @@ func (s *Handlers) HandleImageEnc() http.HandlerFunc {
 		w.Header().Set("Cache-Control", cacheControl(req.Expires))
 		w.Header().Set("X-Pixa-Cache", string(resp.CacheStatus))
 
+		if notModified(w, r, resp.ETag) {
+			return
+		}
+
+		// A HEAD request gets the headers only
+		if r.Method == http.MethodHead {
+			w.WriteHeader(http.StatusOK)
+
+			return
+		}
+
 		// Stream the response
 		written, err := io.Copy(w, resp.Content)
 		if err != nil {
@@ -105,6 +82,7 @@ func (s *Handlers) HandleImageEnc() http.HandlerFunc {
 		// Log completion
 		duration := time.Since(start)
 		s.log.Info("image served",
+			"request_id", middleware.GetReqID(ctx),
 			"cache_key", imgcache.CacheKey(req),
 			"host", req.SourceHost,
 			"path", req.SourcePath,
@@ -116,6 +94,56 @@ func (s *Handlers) HandleImageEnc() http.HandlerFunc {
 	}
 }
 
+// parseImageEncRequest decrypts the token of an encrypted image URL into an
+// ImageRequest and checks it. On a token that is missing, does not decrypt,
+// has expired or asks for something not valid, it writes an error response
+// and returns false.
+func (s *Handlers) parseImageEncRequest(
+	w http.ResponseWriter, r *http.Request,
+) (*imgcache.ImageRequest, bool) {
+	// Extract token from URL
+	token := chi.URLParam(r, "token")
+	if token == "" {
+		s.respondError(w, "missing token", http.StatusBadRequest)
+
+		return nil, false
+	}
+
+	// Decrypt and validate the payload
+	payload, err := s.encGen.Parse(token)
+	if err != nil {
+		if errors.Is(err, encurl.ErrExpired) {
+			s.log.Debug("encrypted URL expired", "error", err)
+			s.respondError(w, "URL has expired", http.StatusGone)
+
+			return nil, false
+		}
+
+		s.log.Debug("failed to decrypt URL", "error", err)
+		s.respondError(w, "invalid encrypted URL", http.StatusBadRequest)
+
+		return nil, false
+	}
+
+	// Convert payload to ImageRequest
+	req := payload.ToImageRequest()
+
+	// Apply the same dimension and fit-mode bounds as the plain image
+	// route: a sealed payload is trusted for its origin, not for staying
+	// within limits, so an over-limit size or unknown fit mode is a 400
+	// here rather than an out-of-memory or a 500 from the processor.
+	err = imgcache.ValidateImageRequest(req)
+	if err != nil {
+		s.log.Debug("encrypted URL failed validation", "error", err)
+		s.respondError(w, "invalid encrypted URL: "+err.Error(),
+			http.StatusBadRequest)
+
+		return nil, false
+	}
+
+	return req, true
+}
+
 // handleImageError converts image service errors to HTTP responses.
 func (s *Handlers) handleImageError(w http.ResponseWriter, err error) {
 	switch {