Keep each side at 1 or more with fit=outside too

fit=outside works both sides out again from the larger scale, and a side
scaled to 1 could come out just under 1 and round down to 0, which
libvips refuses: a 49x8192 source at 0x100 and a 49x49 source at 1x1
answered 500. README.md now says what fit=outside does, with the 8192x1
source at 100x0 that comes out at 8192x1, and how a 0 side is worked
out from the source's proportions.

Model: opus-5-5

README.md

@@ -131,6 +131,34 @@ What the [upaas](https://git.eeqj.de/sneak/upaas) app for pixa needs:
       the cache can grow to three quarters or more of the space they all have
       left, and to all of it when that is 500 MiB or less.
     - the rest are in the table under Configuration below
+- **Memory:** pixa can use up to `max_concurrent_processing` times 4.2 GiB for
+  the images it processes at once, plus `upstream_connections` times
+  `upstream_max_response_size` for the source images it has fetched that wait
+  for processing. 4.2 GiB is the most resident memory was measured to grow while
+  pixa, with pixad's libvips settings, processed one 8192x8192 source, the
+  largest it accepts, saving it at full size to each output format in turn, one
+  at a time. The sources were a JPEG, a GIF, a WebP, an 8-bit and a 16-bit PNG,
+  an 8-bit and a 12-bit AVIF, and an 8-bit, a 16-bit and a 32-bit floating-point
+  JPEG XL; memory grew most for the 16-bit JPEG XL, of random pixels, saved as
+  WebP. At the defaults that is half the CPUs pixa sees times 4.2 GiB, plus 64
+  times 50 MiB: on a host where pixa sees 48 CPUs, 24 times 4.2 GiB plus 3.1
+  GiB, about 104 GiB. Set `PIXA_MAX_CONCURRENT_PROCESSING` and
+  `PIXA_UPSTREAM_CONNECTIONS` so that this fits the memory the container may
+  use.
+- **Temporary files:** while pixa processes a large source, libvips writes its
+  decoded pixels to a file in `/tmp`. The file disappears from `/tmp` once it is
+  written, so a listing of `/tmp` does not show it, but it keeps its space, on
+  disk or, where `/tmp` is a tmpfs, in memory, until the image is done. For a
+  GIF, WebP, AVIF or JPEG XL source the decoded pixels are held in memory as
+  well as written to that file, and the 4.2 GiB above includes that memory. For
+  an 8192x8192 source the file was measured on pixad at 192 MiB for an 8-bit RGB
+  JPEG, 512 MiB for a 16-bit RGBA PNG or JPEG XL, and 1 GiB for a JPEG XL of
+  32-bit floating-point RGBA, the largest measured: up to 1 GiB per image
+  processed at once, 24 GiB at the defaults on a host where pixa sees 48 CPUs.
+  This `/tmp` is in the container's own filesystem, not on the volume at
+  `/var/lib/pixa`, and `cache_max_bytes` does not count it. The 4.2 GiB above
+  does not include these files; where `/tmp` is a tmpfs, they are memory on top
+  of it.
 - **Health check:** the image's `HEALTHCHECK` requests
   `/.well-known/healthcheck.json`. upaas reads the container's health 60 seconds
   after a deploy and marks the deploy failed unless it is `healthy`. The probe
@@ -288,6 +316,21 @@ 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.
 
+A source URL's query follows its path after `%3F`, the encoded `?`:
+`/v1/image/<host>/<path>%3F<query>/<size>.<format>`. pixa decodes the
+percent-escapes in the image URL's path once, then reads the host up to the
+first `/`, the size and format after the last `/`, and between them the source
+path up to the first `?` and the source query after it. So the `?` before the
+query, any `?` in the query, and every `%` in the source path or query must be
+percent-encoded, as `%3F` and `%25`. Any other character may be written as
+itself or percent-encoded: `/`, `;`, `,`, `=` and `&` work either way. Neither
+the source path nor the source query may hold a `#`, and an image URL that
+writes one as `%23` is refused with 400. For example,
+`https://cdn.example.com/img?url=https://origin.example.com/my%20cat.jpg` at
+800x600 WebP is
+`/v1/image/cdn.example.com/img%3Furl=https://origin.example.com/my%2520cat.jpg/800x600.webp`,
+signed as shown under Signature Specification.
+
 A size with one side `0` has that side scaled to keep the source's proportions,
 and is refused with 400 when that side would come out above 8192, the most
 either side may be; so is a size with `fit=outside`, which scales the image to
@@ -469,8 +512,13 @@ Where:
 - `query` — source query string, empty string if none, with `%` and `:` written
   as in `path`; neither then holds a `:`, so path `/a:b` with no query and path
   `/a` with query `b:` are signed differently
-- `width` — requested width in pixels, `0` for original
-- `height` — requested height in pixels, `0` for original
+- `width` — requested width in pixels, or `0`: the width is then worked out from
+  the source's proportions and the requested height, rounded down but at least
+  1, or is the source's own width when the height is `0` too (the `orig` size)
+- `height` — requested height in pixels, or `0`: the height is then worked out
+  from the source's proportions and the requested width, rounded down but at
+  least 1, or is the source's own height when the width is `0` too (the `orig`
+  size)
 - `format` — output format, one of those listed under Routes, with `original`
   signed as `orig`, `jpg` as `jpeg`, and no format as `jxl`, so a URL with no
   format has the signature of the same URL ending in `.jxl`; `auto` is signed as
@@ -483,7 +531,10 @@ Where:
   with 400
 - `fit` — the URL's `fit` query parameter (cover, contain, fill, inside,
   outside), or `cover` when the URL has no `fit`; a request whose `fit` is
-  anything else, an empty `fit=` included, is refused with 400
+  anything else, an empty `fit=` included, is refused with 400. `outside` scales
+  the image to cover the requested size, keeping its proportions, so it can come
+  out larger than that size on one side: an 8192x1 source at `100x0`, which is
+  100x1 by its proportions, comes out at 8192x1
 
 The URL's `sig` is the HMAC-SHA256 result in base64url (the URL-safe alphabet of
 RFC 4648) with the trailing `=` padding kept, 44 characters in all. pixa
@@ -507,6 +558,17 @@ For the same image at quality 40 with fit `contain`, the input ends in
 and the URL is
 `/v1/image/cdn.example.com/photos/cat.jpg/800x600.webp?sig=5IwXUx6vf7yefhaUvFzgXZvG2o0Df4RJxPTK3pKq5VU=&exp=1704067200&q=40&fit=contain`.
 
+For a source URL with a query,
+`https://cdn.example.com/img?url=https://origin.example.com/my%20cat.jpg`, at
+800x600 WebP with the same key and expiration and the default quality and fit:
+
+1. Build input, with the query's `:` written as `%3A` and its `%` as `%25`:
+   `cdn.example.com:/img:url=https%3A//origin.example.com/my%2520cat.jpg:800:600:webp:1704067200:85:cover`
+2. The signature is `37aFa9GSVCZM1kRY9SzMOk2fOg_M7Wt5gKNR4xM-FYA=`
+3. URL, with the `?` before the query written as `%3F` and the query's `%` as
+   `%25` (see Routes):
+   `/v1/image/cdn.example.com/img%3Furl=https://origin.example.com/my%2520cat.jpg/800x600.webp?sig=37aFa9GSVCZM1kRY9SzMOk2fOg_M7Wt5gKNR4xM-FYA=&exp=1704067200`
+
 **Allowlist patterns:**
 
 - **Exact match**: `cdn.example.com` — matches only that host
@@ -522,7 +584,11 @@ pixa lower-cases the host of a `/v1/image/` URL before anything else uses it, so
 `CDN.Example.com` is matched, fetched, cached and counted against
 `upstream_connections_per_host` as `cdn.example.com`. Such a URL whose host has
 a port, as in `cdn.example.com:8443`, or a `:` with no port, needs a signature
-even when the host is allowlisted. A host holding `@` is refused with 400.
+even when the host is allowlisted. The host must be a host name or an IPv4
+address (letters, digits, hyphens, underscores and dots) or an IPv6 address in
+brackets, either one optionally followed by `:` and a port. Any other host, such
+as one holding `@`, or a `?`, `#`, `%`, `\` or space written percent-encoded, is
+refused with 400.
 
 ### Configuration
 
@@ -566,7 +632,7 @@ tell. With no file, pixa uses the environment and the defaults.
 | `PIXA_ALLOW_HTTP`                    | `allow_http`                    | Allow plain-HTTP upstreams, for testing only; default `false`                |
 | `PIXA_UPSTREAM_CONNECTIONS_PER_HOST` | `upstream_connections_per_host` | Concurrent connections per upstream host; default `20`                       |
 | `PIXA_UPSTREAM_CONNECTIONS`          | `upstream_connections`          | Concurrent connections to all upstream hosts together; default `64`          |
-| `PIXA_MAX_CONCURRENT_PROCESSING`     | `max_concurrent_processing`     | Images processed at once; default the number of CPUs                         |
+| `PIXA_MAX_CONCURRENT_PROCESSING`     | `max_concurrent_processing`     | Images processed at once; default half the CPUs, at least 1                  |
 | `PIXA_IMAGE_REQUESTS_PER_MINUTE`     | `image_requests_per_minute`     | Image requests per client per minute; `0` turns it off; default `600`        |
 | `PIXA_UPSTREAM_FETCH_TIMEOUT`        | `upstream_fetch_timeout`        | Time allowed for one fetch from an upstream host; default `30s`              |
 | `PIXA_UPSTREAM_MAX_RESPONSE_SIZE`    | `upstream_max_response_size`    | Largest upstream response accepted, in bytes; default 50 MiB                 |
@@ -652,10 +718,12 @@ Key settings in more detail:
   does, and `downstream_timeout` has not ended first, the request is answered
   503 with the error `server busy, try again later`
 - `max_concurrent_processing` — the most images decoded and encoded at once;
-  default the number of CPUs pixa can use (`GOMAXPROCS`), which follows a
-  container's CPU limit. A request that finds all of them in use waits up to 10
-  seconds for one to free up; if none does, and `downstream_timeout` has not
-  ended first, it is answered 503 the same way
+  default half the CPUs pixa can use (`GOMAXPROCS`, which follows a container's
+  CPU limit), rounded down, and at least 1. A value that is not a whole number
+  of at least 1 aborts startup. A request that finds all of them in use waits up
+  to 10 seconds for one to free up; if none does, and `downstream_timeout` has
+  not ended first, it is answered 503 the same way. Each one can take a lot of
+  memory: see "Running under upaas"
 - `image_requests_per_minute` — how many requests one client may send to the
   image routes per minute (see the limit on them under Routes); default `600`.
   `0` turns the limit off, and a negative or non-integer value aborts startup.

TODO.md

@@ -30,6 +30,74 @@ P2: security: per-origin rate limiting
 
 # Completed Steps
 
+- 2026-10-16 a size with one side `0` keeps the side computed from the source's
+  proportions at 1 or more (closes #283): it was rounded down, so for a thin
+  source it came out at 0, and libvips then made the size square. An 8192x1
+  source at `100x0` came out at 100x100, and at `1300x0` with `fit=cover` made
+  libvips ask for about 39 GB at once; an 8192x2 source at `100x0` answered 500.
+  `fit=contain` and `fit=inside` work both sides out again from the smaller of
+  the two scales and `fit=outside` from the larger, and each keeps both sides at
+  1 or more too, so a 1x8192 source at `0x100` with `fit=contain`, and a 49x8192
+  source at `0x100` or a 49x49 source at `1x1` with `fit=outside`, no longer
+  answer 500. An 8192x1 source at `1300x0` now comes out at 1300x1, and the
+  process running it alone peaked at about 34 MiB resident. With `fit=outside`
+  the image is scaled to cover the size, so that source at `100x0` comes out at
+  8192x1. `README.md` now says this under Signature Specification, and says how
+  a `0` side is worked out where it said `0` meant the original.
+- 2026-10-15 a thin source requested with `fit=cover` no longer makes libvips
+  build a huge image (closes #282): libvips' thumbnail scaled the whole source
+  to cover the requested size and copied that into memory before it cut out the
+  centre, so an 8192x64 source at 8192x8192 made it allocate about 24 GiB, and
+  an 8192x1 source answered 500. The image processor now first cuts the centre
+  of the source, widened to whole source pixels, and thumbnail scales and cuts
+  only that, by the same amount on both sides as before. What it copies into
+  memory is then larger than the output by less than one scaled source pixel on
+  each side. With the runtime image's libvips and JPEG output at 8192x8192,
+  resident memory peaked at about 242 MiB for the 8192x64 source and 431 MiB for
+  the 8192x1 one. The output can sit a fraction of an output pixel from where it
+  was.
+- 2026-10-15 a `/v1/image/` URL whose source path or source query holds a `#`,
+  written as `%23`, is refused with 400 (closes #286): the source URL built from
+  it ended at the `#` when fetched, so each text after it fetched the same
+  upstream image, without a signature for an allowlisted host, and cached it
+  under keys of its own. `README.md` says neither may hold a `#`.
+- 2026-10-15 the host of a `/v1/image/` URL must be a host name or an IPv4
+  address (letters, digits, hyphens, underscores and dots) or an IPv6 address in
+  brackets, either one optionally followed by `:` and a port, and any other host
+  is refused with 400 (closes #275): only `@` was refused, so a `?` written as
+  `%3F` gave the host `cdn.example.com?x=1`, which Go's URL parser reads as
+  `cdn.example.com` with a query. Such a URL passed the allowlist, and each text
+  after the `?` fetched the host's root path and cached the answer under keys of
+  its own. A `#`, `%`, `\` or space written percent-encoded is refused the same
+  way, and so is an IPv6 address without brackets, which needed a signature
+  before. Underscores are kept because `allowlist_hosts` accepts host names
+  holding them.
+- 2026-10-15 the README says how a source URL with a query is written into an
+  image URL, and the image route accepts it (closes #255): the query follows the
+  source path after `%3F`. pixa now reads the image URL's path decoded once, so
+  the `?` before the query, any `?` in it and every `%` in the source path or
+  query must be percent-encoded, and any other character may be. The route used
+  to parse chi's wildcard, which holds the path as the client wrote it whenever
+  that is not Go's own encoding of it; a `/`, `;` or `,` in the query written as
+  `%2F`, `%3B` or `%2C`, as `GenerateSignedURL` wrote them, kept the `%3F` from
+  being read as `?`, and the request failed with 401. `GenerateSignedURL` now
+  writes Go's own encoding of the path. The README has an example with a query
+  and its signature. The path traversal check no longer reads the source query,
+  and keeps a `%` that does not start a percent-escape as it is instead of
+  refusing the URL, so a source path or query holding `%25` is accepted, while a
+  double-encoded `..` next to such a `%` is still refused.
+- 2026-10-15 `max_concurrent_processing` defaults to half the CPUs pixa sees,
+  rounded down, and at least 1 (closes #242): it defaulted to one image per CPU,
+  and a container with no CPU limit sees every CPU of the host, so on a 48-CPU
+  host pixa processed 48 images at once, each of which can take about 4.2 GiB.
+  `config.DefaultMaxConcurrentProcessing` gives the default to the config and to
+  `imageprocessor.New`; `PIXA_MAX_CONCURRENT_PROCESSING` still overrides it.
+  "Running under upaas" in `README.md` gives the worst-case memory, measured,
+  and tells the operator to set `PIXA_MAX_CONCURRENT_PROCESSING` and
+  `PIXA_UPSTREAM_CONNECTIONS` to fit the container's memory. It also gives the
+  file libvips writes to `/tmp` for each large source, up to 1 GiB, measured,
+  which is outside `/var/lib/pixa` and `cache_max_bytes` and is memory where
+  `/tmp` is a tmpfs.
 - 2026-10-15 the canonical files are re-vendored from `sneak/prompts` commit
   `e3f79c4` (closes #221): `.dockerignore`, `.editorconfig`,
   `.gitea/workflows/check.yml`, `.gitignore`, `.golangci.yml`,

configs/config.example.yml

@@ -108,10 +108,11 @@ upstream_connections_per_host: 20
 # downstream_timeout has ended first.
 upstream_connections: 64
 
-# Maximum number of images decoded and encoded at once (default: the
-# number of CPUs pixa can use, which follows a container's CPU limit). A
-# request that finds none free waits up to 10 seconds for one, and if none
-# frees up it is answered 503, unless downstream_timeout has ended first.
+# Maximum number of images decoded and encoded at once (default: half the
+# number of CPUs pixa can use, at least 1; the number of CPUs follows a
+# container's CPU limit). A request that finds none free waits up to 10
+# seconds for one, and if none frees up it is answered 503, unless
+# downstream_timeout has ended first.
 # max_concurrent_processing: 4
 
 # How many requests to the image routes (/v1/image/ and /v1/e/) one client

internal/config/concurrency_limits_internal_test.go

@@ -1,6 +1,7 @@
 package config
 
 import (
+	"fmt"
 	"runtime"
 	"testing"
 )
@@ -12,8 +13,8 @@ const (
 )
 
 // TestOmittedConcurrencyLimitsUseDefaults checks that an omitted
-// max_concurrent_processing is the number of CPUs Go uses and an omitted
-// upstream_connections is 64.
+// max_concurrent_processing is half the CPUs Go uses, and at least 1, and
+// an omitted upstream_connections is 64.
 func TestOmittedConcurrencyLimitsUseDefaults(t *testing.T) {
 	t.Parallel()
 
@@ -22,9 +23,9 @@ func TestOmittedConcurrencyLimitsUseDefaults(t *testing.T) {
 		t.Fatalf("minimal config should be valid, got error: %v", err)
 	}
 
-	if c.MaxConcurrentProcessing != runtime.GOMAXPROCS(0) {
-		t.Errorf("MaxConcurrentProcessing = %d, want %d, one per CPU",
-			c.MaxConcurrentProcessing, runtime.GOMAXPROCS(0))
+	if c.MaxConcurrentProcessing != max(runtime.GOMAXPROCS(0)/2, 1) {
+		t.Errorf("MaxConcurrentProcessing = %d, want %d, half the CPUs",
+			c.MaxConcurrentProcessing, max(runtime.GOMAXPROCS(0)/2, 1))
 	}
 
 	if c.UpstreamConnections != 64 {
@@ -32,6 +33,36 @@ func TestOmittedConcurrencyLimitsUseDefaults(t *testing.T) {
 	}
 }
 
+// TestOmittedMaxConcurrentProcessingIsHalfTheCPUsAndAtLeastOne checks
+// that an omitted max_concurrent_processing is half the CPUs Go uses,
+// rounded down, and 1 when Go uses one CPU.
+//
+//nolint:paralleltest // it sets GOMAXPROCS, which other tests read
+func TestOmittedMaxConcurrentProcessingIsHalfTheCPUsAndAtLeastOne(t *testing.T) {
+	cpusBefore := runtime.GOMAXPROCS(0)
+
+	t.Cleanup(func() { runtime.GOMAXPROCS(cpusBefore) })
+
+	for _, tc := range []struct{ cpus, want int }{
+		{1, 1}, {2, 1}, {3, 1}, {8, 4},
+	} {
+		runtime.GOMAXPROCS(tc.cpus)
+
+		c, err := configFromYAML(t, signingKeyLine)
+		if err != nil {
+			t.Fatalf("minimal config should be valid, got error: %v", err)
+		}
+
+		t.Logf("GOMAXPROCS %d: MaxConcurrentProcessing %d",
+			tc.cpus, c.MaxConcurrentProcessing)
+
+		if c.MaxConcurrentProcessing != tc.want {
+			t.Errorf("GOMAXPROCS %d: MaxConcurrentProcessing = %d, want %d",
+				tc.cpus, c.MaxConcurrentProcessing, tc.want)
+		}
+	}
+}
+
 // TestExplicitConcurrencyLimitsAreUsed checks that valid values for the
 // two limits are used as given.
 func TestExplicitConcurrencyLimitsAreUsed(t *testing.T) {
@@ -160,3 +191,19 @@ func TestConcurrencyLimitsFromEnvironment(t *testing.T) {
 		})
 	}
 }
+
+// TestInvalidMaxConcurrentProcessingFromEnvironmentAbortsStartup checks
+// that a PIXA_MAX_CONCURRENT_PROCESSING that is not a whole number of at
+// least 1, an empty one included, aborts startup naming the variable and
+// the key instead of taking the default.
+func TestInvalidMaxConcurrentProcessingFromEnvironmentAbortsStartup(t *testing.T) {
+	for _, value := range []string{"", " ", "0.5", "half", "-1", "4 images"} {
+		t.Run(fmt.Sprintf("value %q", value), func(t *testing.T) {
+			t.Setenv(testMaxConcurrentProcessingVar, value)
+
+			_, err := configFromYAML(t, signingKeyLine)
+			wantStartupError(t, err,
+				testMaxConcurrentProcessingVar, keyMaxConcurrentProcessing)
+		})
+	}
+}

internal/config/config.go

@@ -37,6 +37,14 @@ const (
 	DefaultImageRequestsPerMinute     = 600
 )
 
+// DefaultMaxConcurrentProcessing returns the most images processed at once
+// when max_concurrent_processing is omitted: half the CPUs Go uses
+// (runtime.GOMAXPROCS(0), which follows a container's CPU limit), rounded
+// down, and at least 1.
+func DefaultMaxConcurrentProcessing() int {
+	return max(runtime.GOMAXPROCS(0)/2, 1) //nolint:mnd // half the CPUs
+}
+
 // Configuration key names.
 const (
 	keyDebug                      = "debug"
@@ -297,10 +305,8 @@ func newFromSmartConfig(sc *smartconfig.Config) (*Config, error) {
 			keyUpstreamConnectionsPerHost, DefaultUpstreamConnectionsPerHost),
 		UpstreamConnections: loader.intVal(
 			keyUpstreamConnections, DefaultUpstreamConnections),
-		// Decoding and encoding are CPU-bound, so the default is one image
-		// per CPU Go uses, which follows a container's CPU limit.
 		MaxConcurrentProcessing: loader.intVal(
-			keyMaxConcurrentProcessing, runtime.GOMAXPROCS(0)),
+			keyMaxConcurrentProcessing, DefaultMaxConcurrentProcessing()),
 		UpstreamFetchTimeout: loader.durationVal(
 			keyUpstreamFetchTimeout, DefaultUpstreamFetchTimeout),
 		UpstreamMaxResponseSize: loader.int64Val(

internal/handlers/image.go

@@ -9,7 +9,6 @@ import (
 	"strconv"
 	"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"
@@ -80,20 +79,21 @@ func (s *Handlers) HandleRobotsTxt() http.HandlerFunc {
 	}
 }
 
-// parseImageRequest parses the wildcard path and query parameters into
+// parseImageRequest parses the image URL's path and query parameters into
 // an ImageRequest. On invalid input it writes an error response and
 // returns false.
 func (s *Handlers) parseImageRequest(
 	w http.ResponseWriter, r *http.Request,
 ) (*imgcache.ImageRequest, bool) {
-	// Get the wildcard path from chi
-	pathParam := chi.URLParam(r, "*")
-
-	// Parse the URL path
-	parsed, err := imgcache.ParseImagePath(pathParam)
+	// The path is parsed decoded once, as r.URL.Path holds it, and not from
+	// chi's wildcard: chi routes on the path as the client wrote it whenever
+	// that is not Go's own encoding of it, so its wildcard would still hold
+	// the %3F before a source query when, say, a "/" in the query is written
+	// as %2F
+	parsed, err := imgcache.ParseImageURL(r.URL.Path)
 	if err != nil {
 		s.log.Warn("failed to parse image URL",
-			"path", pathParam,
+			"path", r.URL.Path,
 			"error", err,
 		)
 		s.respondError(w, "invalid image URL: "+err.Error(), http.StatusBadRequest)

internal/handlers/image_errors_internal_test.go

@@ -264,3 +264,127 @@ func TestHandleImage_AllowlistOrSignature(t *testing.T) {
 		})
 	}
 }
+
+// TestHandleImage_InvalidHost_Returns400 sends image URLs whose host no URL
+// host can be, and checks that each is refused with 400 naming the host as
+// decoded: allowlistedHost with a character after it that a URL host cannot
+// hold, percent-encoded, an IPv6 address without brackets, and brackets
+// around something that is not an IPv6 address. A "?" or "#" after
+// allowlistedHost would otherwise end the host when the source URL is read,
+// so the request would pass the allowlist and be fetched and cached under a
+// host that is not the one fetched.
+func TestHandleImage_InvalidHost_Returns400(t *testing.T) {
+	t.Parallel()
+
+	photos := newPhotoFetcher(t, allowlistedHost)
+
+	tests := []struct {
+		name        string
+		writtenHost string
+		decodedHost string
+	}{
+		{"? written as %3F", allowlistedHost + "%3Fx=1", allowlistedHost + "?x=1"},
+		{"# written as %23", allowlistedHost + "%23x", allowlistedHost + "#x"},
+		{"% written as %25", allowlistedHost + "%253F", allowlistedHost + "%3F"},
+		{`\ written as %5C`, allowlistedHost + "%5Cx", allowlistedHost + `\x`},
+		{"space written as %20", allowlistedHost + "%20", allowlistedHost + " "},
+		{"IPv6 address without brackets", "2001:db8::1", "2001:db8::1"},
+		{"IPv4 address in brackets", "[203.0.113.5]", "[203.0.113.5]"},
+		{"no address in brackets", "[abc]", "[abc]"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			rec := sendGet(t, newImageRoute(t, photos), photoURL(tt.writtenHost))
+			checkErrorBody(t, rec, http.StatusBadRequest,
+				fmt.Sprintf("invalid image URL: invalid source host: %q",
+					tt.decodedHost))
+		})
+	}
+}
+
+// TestHandleImage_HostForms_Served checks that the image route serves, with
+// a valid signature, the image at photoPath on a host name, an IPv4 address,
+// an IPv6 address in brackets, and a host followed by ":" with or without a
+// port.
+func TestHandleImage_HostForms_Served(t *testing.T) {
+	t.Parallel()
+
+	hosts := []string{
+		allowlistedHost,
+		"img_1.example.com",
+		"203.0.113.5",
+		"[2001:db8::1]",
+		allowlistedHost + ":8443",
+		"[2001:db8::1]:8443",
+		allowlistedHost + ":",
+	}
+
+	photos := newPhotoFetcher(t, hosts...)
+	exp := time.Now().Add(time.Hour)
+
+	for _, host := range hosts {
+		t.Run(host, func(t *testing.T) {
+			t.Parallel()
+
+			sig := photoSignature(testSigningKey, host, exp)
+
+			rec := sendGet(t, newImageRoute(t, photos),
+				photoURLWithSig(host, sig, exp))
+			if rec.Code != http.StatusOK {
+				t.Errorf("status = %d, want %d: %s",
+					rec.Code, http.StatusOK, rec.Body)
+			}
+		})
+	}
+}
+
+// TestHandleImage_HashInSourcePathOrQuery_Returns400 sends image URLs whose
+// source path or source query holds a "#", written as %23, and checks that
+// each is refused with 400, the one signed for that source path included. The
+// source URL would otherwise end at the "#" when it is fetched, so each text
+// after it would fetch the image at photoPath and cache it under keys of its
+// own.
+func TestHandleImage_HashInSourcePathOrQuery_Returns400(t *testing.T) {
+	t.Parallel()
+
+	photos := newPhotoFetcher(t, allowlistedHost, signedHost)
+	exp := time.Now().Add(time.Hour)
+
+	sig := signature.New(testSigningKey).Sign(&signature.Request{
+		SourceHost: signedHost,
+		SourcePath: photoPath + "#x",
+		Width:      50,
+		Height:     50,
+		Format:     string(imgcache.FormatJPEG),
+		Quality:    85,
+		FitMode:    string(imgcache.FitCover),
+		Expires:    exp,
+	})
+
+	tests := []struct {
+		name   string
+		target string
+	}{
+		{"# in the source path",
+			"/v1/image/" + allowlistedHost + photoPath + "%23x/50x50.jpeg"},
+		{"# in the source query",
+			"/v1/image/" + allowlistedHost + photoPath + "%3Fv=1%23x/50x50.jpeg"},
+		{"# in the source path, signed",
+			fmt.Sprintf("/v1/image/%s%s%%23x/50x50.jpeg?sig=%s&exp=%d",
+				signedHost, photoPath, sig, exp.Unix())},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			rec := sendGet(t, newImageRoute(t, photos), tt.target)
+			checkErrorBody(t, rec, http.StatusBadRequest,
+				`invalid image URL: invalid image path: `+
+					`the source path or query holds a "#"`)
+		})
+	}
+}

internal/handlers/image_signature_internal_test.go

@@ -169,3 +169,166 @@ func TestHandleImage_InvalidExp_Returns400(t *testing.T) {
 		})
 	}
 }
+
+// TestHandleImage_GeneratedSignedURLWithSourceQueryVerifies sends URLs built
+// by the service's signed-URL generator for source URLs with a query to the
+// route, through a chi router: chi routes on the path as the client wrote it
+// whenever that is not Go's own encoding of it. A 502 means the signature
+// passed, so the route read the source path and query that were signed.
+func TestHandleImage_GeneratedSignedURLWithSourceQueryVerifies(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name  string
+		query string
+	}{
+		{"slash and colon", "url=https://origin.example.com/cat.jpg"},
+		{"semicolon", "a=1;b=2"},
+		{"comma", "crop=0,0,50,50"},
+		{"equals and ampersand", "a=1&b=2"},
+		{"percent-escape", "name=my%20cat"},
+		{"question mark", "next=/a?b=1"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			fix := setupTestHandler(t)
+
+			signedURL, err := fix.service.GenerateSignedURL("", &imgcache.ImageRequest{
+				SourceHost:  signedHost,
+				SourcePath:  photoPath,
+				SourceQuery: tt.query,
+				Size:        imgcache.Size{Width: 50, Height: 50},
+				Format:      imgcache.FormatJPEG,
+			}, time.Hour)
+			if err != nil {
+				t.Fatalf("GenerateSignedURL() error = %v", err)
+			}
+
+			status := getImage(t, fix, signedURL)
+			if status != http.StatusBadGateway {
+				t.Errorf("status = %d, want %d", status, http.StatusBadGateway)
+			}
+		})
+	}
+}
+
+// TestHandleImage_SourceQueryEncodedAnyWay signs one source URL with a query
+// and writes it into the image URL in ways the README allows: the "?" before
+// the query and each "%" in it percent-encoded, and every other character as
+// itself or percent-encoded. A 502 means the signature passed.
+func TestHandleImage_SourceQueryEncodedAnyWay(t *testing.T) {
+	t.Parallel()
+
+	expires := time.Now().Add(time.Hour)
+	signer := signature.New("test-signing-key-must-be-32-chars")
+	sig := signer.Sign(&signature.Request{
+		SourceHost:  signedHost,
+		SourcePath:  photoPath,
+		SourceQuery: "url=https://origin.example.com/my%20cat.jpg",
+		Width:       50,
+		Height:      50,
+		Format:      string(imgcache.FormatJPEG),
+		Quality:     85,
+		FitMode:     string(imgcache.FitCover),
+		Expires:     expires,
+	})
+
+	tests := []struct {
+		name         string
+		writtenQuery string
+	}{
+		{"only ? and % encoded",
+			"%3Furl=https://origin.example.com/my%2520cat.jpg"},
+		{"every reserved character encoded",
+			"%3Furl%3Dhttps%3A%2F%2Forigin.example.com%2Fmy%2520cat.jpg"},
+		{"lower-case hex digits",
+			"%3furl=https://origin.example.com/my%2520cat.jpg"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			target := fmt.Sprintf("/v1/image/%s%s%s/50x50.jpeg?sig=%s&exp=%d",
+				signedHost, photoPath, tt.writtenQuery, sig, expires.Unix())
+
+			status := getImage(t, setupTestHandler(t), target)
+			if status != http.StatusBadGateway {
+				t.Errorf("status = %d, want %d", status, http.StatusBadGateway)
+			}
+		})
+	}
+}
+
+// TestHandleImage_SourceURLHoldingPercent25Verifies signs a source path and a
+// source query that each hold %25, the percent-escape of a literal "%", and
+// sends each to the route written as the README says, with that "%" written as
+// %25, and as GenerateSignedURL writes it. A 502 means the signature passed.
+func TestHandleImage_SourceURLHoldingPercent25Verifies(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name        string
+		sourcePath  string
+		sourceQuery string
+		// writtenPathAndQuery is the source path and query as the README says
+		// to write them into the image URL
+		writtenPathAndQuery string
+	}{
+		{"path", "/sale/50%25off.jpg", "", "/sale/50%2525off.jpg"},
+		{"query", photoPath, "discount=50%25", photoPath + "%3Fdiscount=50%2525"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name+" written by the README rule", func(t *testing.T) {
+			t.Parallel()
+
+			expires := time.Now().Add(time.Hour)
+			signer := signature.New("test-signing-key-must-be-32-chars")
+			sig := signer.Sign(&signature.Request{
+				SourceHost:  signedHost,
+				SourcePath:  tt.sourcePath,
+				SourceQuery: tt.sourceQuery,
+				Width:       50,
+				Height:      50,
+				Format:      string(imgcache.FormatJPEG),
+				Quality:     85,
+				FitMode:     string(imgcache.FitCover),
+				Expires:     expires,
+			})
+
+			target := fmt.Sprintf("/v1/image/%s%s/50x50.jpeg?sig=%s&exp=%d",
+				signedHost, tt.writtenPathAndQuery, sig, expires.Unix())
+
+			status := getImage(t, setupTestHandler(t), target)
+			if status != http.StatusBadGateway {
+				t.Errorf("status = %d, want %d", status, http.StatusBadGateway)
+			}
+		})
+
+		t.Run(tt.name+" written by GenerateSignedURL", func(t *testing.T) {
+			t.Parallel()
+
+			fix := setupTestHandler(t)
+
+			signedURL, err := fix.service.GenerateSignedURL("", &imgcache.ImageRequest{
+				SourceHost:  signedHost,
+				SourcePath:  tt.sourcePath,
+				SourceQuery: tt.sourceQuery,
+				Size:        imgcache.Size{Width: 50, Height: 50},
+				Format:      imgcache.FormatJPEG,
+			}, time.Hour)
+			if err != nil {
+				t.Fatalf("GenerateSignedURL() error = %v", err)
+			}
+
+			status := getImage(t, fix, signedURL)
+			if status != http.StatusBadGateway {
+				t.Errorf("status = %d, want %d", status, http.StatusBadGateway)
+			}
+		})
+	}
+}

internal/imageprocessor/computed_side_internal_test.go

@@ -50,3 +50,69 @@ func TestImageProcessor_RefusesComputedSideAboveMaximum(t *testing.T) {
 		})
 	}
 }
+
+// TestImageProcessor_ComputedSideIsAtLeastOne verifies that, for a size with
+// one side 0, the side computed from the input's proportions is 1 where it
+// would round down to 0, and that Process makes that size in every fit mode
+// but FitOutside, which scales the input to cover the size and so can make
+// it longer. Each case checks the size targetDimensions gives before it
+// calls Process: with that side at 0, an 8192x1 input at 1300x0 makes
+// libvips ask for about 39 GB with FitCover.
+func TestImageProcessor_ComputedSideIsAtLeastOne(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name                    string
+		inputWidth, inputHeight int
+		size                    Size
+		wantWidth, wantHeight   int
+	}{
+		{"8192x1 at 100x0", 8192, 1, Size{Width: 100}, 100, 1},
+		{"8192x1 at 1300x0", 8192, 1, Size{Width: 1300}, 1300, 1},
+		{"8192x2 at 100x0", 8192, 2, Size{Width: 100}, 100, 1},
+		{"1x8192 at 0x100", 1, 8192, Size{Height: 100}, 1, 100},
+		{"1x8192 at 0x1300", 1, 8192, Size{Height: 1300}, 1, 1300},
+		{"2x8192 at 0x100", 2, 8192, Size{Height: 100}, 1, 100},
+	}
+
+	fits := []FitMode{FitCover, FitContain, FitFill, FitInside, FitOutside}
+
+	for _, tt := range tests {
+		for _, fit := range fits {
+			t.Run(tt.name+" "+string(fit), func(t *testing.T) {
+				t.Parallel()
+
+				width, height, err := targetDimensions(tt.size,
+					tt.inputWidth, tt.inputHeight)
+				if err != nil || width != tt.wantWidth || height != tt.wantHeight {
+					t.Fatalf("targetDimensions() = %dx%d, %v, want %dx%d",
+						width, height, err, tt.wantWidth, tt.wantHeight)
+				}
+
+				input := createTestJPEG(t, tt.inputWidth, tt.inputHeight)
+
+				result, err := New(Params{}).Process(t.Context(),
+					bytes.NewReader(input),
+					&Request{Size: tt.size, Format: FormatJPEG, FitMode: fit})
+				if err != nil {
+					t.Fatalf("Process() error = %v", err)
+				}
+
+				defer func() { _ = result.Content.Close() }()
+
+				t.Logf("Process() made %dx%d", result.Width, result.Height)
+
+				ok := result.Width == tt.wantWidth && result.Height == tt.wantHeight
+				if fit == FitOutside {
+					ok = result.Width >= tt.wantWidth && result.Height >= tt.wantHeight
+				}
+
+				if !ok {
+					t.Errorf("Process() made %dx%d, want %dx%d (at least, for %s)",
+						result.Width, result.Height, tt.wantWidth, tt.wantHeight,
+						FitOutside)
+				}
+			})
+		}
+	}
+}

internal/imageprocessor/fit_cover_internal_test.go

@@ -0,0 +1,268 @@
+package imageprocessor
+
+import (
+	"bytes"
+	"image"
+	"image/color"
+	"image/png"
+	"math"
+	"testing"
+)
+
+// TestImageProcessor_FitCoverServesThinSource verifies that FitCover serves
+// a thin source at the requested size. An 8192x1 source scaled to cover
+// 8192x8192 is 8192 times as long as the output on its long side. The centre
+// of an 8192x1 source with the proportions of 1x8192 is 1/8192 of a pixel
+// wide. Each case is also turned on its side.
+func TestImageProcessor_FitCoverServesThinSource(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name                    string
+		inputWidth, inputHeight int
+		size                    Size
+	}{
+		{"8192x1 at 8192x8192", 8192, 1, Size{Width: 8192, Height: 8192}},
+		{"8192x1 at 1x8192", 8192, 1, Size{Width: 1, Height: 8192}},
+		{"1x8192 at 8192x8192", 1, 8192, Size{Width: 8192, Height: 8192}},
+		{"1x8192 at 8192x1", 1, 8192, Size{Width: 8192, Height: 1}},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			input := createTestJPEG(t, tt.inputWidth, tt.inputHeight)
+
+			result, err := New(Params{}).Process(t.Context(),
+				bytes.NewReader(input),
+				&Request{Size: tt.size, Format: FormatJPEG, FitMode: FitCover})
+			if err != nil {
+				t.Fatalf("Process() error = %v", err)
+			}
+
+			defer func() { _ = result.Content.Close() }()
+
+			t.Logf("Process() made %dx%d", result.Width, result.Height)
+
+			if result.Width != tt.size.Width || result.Height != tt.size.Height {
+				t.Errorf("Process() made %dx%d, want %dx%d",
+					result.Width, result.Height, tt.size.Width, tt.size.Height)
+			}
+		})
+	}
+}
+
+// createBandsPNG creates a PNG of three equal bands, red, green and blue,
+// side by side when it is wider than tall and top to bottom otherwise.
+func createBandsPNG(t *testing.T, width, height int) []byte {
+	t.Helper()
+
+	bands := []color.RGBA{
+		{R: 255, A: 255},
+		{G: 255, A: 255},
+		{B: 255, A: 255},
+	}
+
+	img := image.NewRGBA(image.Rect(0, 0, width, height))
+	for y := range height {
+		for x := range width {
+			band := 3 * y / height
+			if width > height {
+				band = 3 * x / width
+			}
+
+			img.Set(x, y, bands[band])
+		}
+	}
+
+	return encodePNG(t, img)
+}
+
+// TestImageProcessor_FitCoverCropsTheCentre verifies that FitCover keeps the
+// centre of the source: a 300x100 source of red, green and blue bands side
+// by side, or a 100x300 one with them top to bottom, comes out at 50x50 as
+// its green band.
+func TestImageProcessor_FitCoverCropsTheCentre(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name                    string
+		inputWidth, inputHeight int
+	}{
+		{"bands side by side", 300, 100},
+		{"bands top to bottom", 100, 300},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			input := createBandsPNG(t, tt.inputWidth, tt.inputHeight)
+
+			result, err := New(Params{}).Process(t.Context(),
+				bytes.NewReader(input),
+				&Request{
+					Size:    Size{Width: 50, Height: 50},
+					Format:  FormatPNG,
+					FitMode: FitCover,
+				})
+			if err != nil {
+				t.Fatalf("Process() error = %v", err)
+			}
+
+			defer func() { _ = result.Content.Close() }()
+
+			output, err := png.Decode(result.Content)
+			if err != nil {
+				t.Fatalf("failed to decode output: %v", err)
+			}
+
+			bounds := output.Bounds()
+			t.Logf("Process() made %dx%d", bounds.Dx(), bounds.Dy())
+
+			if bounds.Dx() != 50 || bounds.Dy() != 50 {
+				t.Fatalf("Process() made %dx%d, want 50x50",
+					bounds.Dx(), bounds.Dy())
+			}
+
+			// Resampling may blend a little of the bands beside the
+			// green one into the output's edges.
+			for y := bounds.Min.Y; y < bounds.Max.Y; y++ {
+				for x := bounds.Min.X; x < bounds.Max.X; x++ {
+					r, g, b, _ := output.At(x, y).RGBA()
+					if r>>8 > 64 || g>>8 < 192 || b>>8 > 64 {
+						t.Fatalf("output pixel %d,%d is %d,%d,%d, want green",
+							x, y, r>>8, g>>8, b>>8)
+					}
+				}
+			}
+		})
+	}
+}
+
+// The greys of createSquarePNG, and the grey halfway between them.
+const (
+	backgroundGrey = 192
+	squareGrey     = 64
+	halfwayGrey    = (backgroundGrey + squareGrey) / 2
+)
+
+// createSquarePNG creates a grey PNG side pixels square with a darker grey
+// square squareSide pixels wide in its centre.
+func createSquarePNG(t *testing.T, side, squareSide int) []byte {
+	t.Helper()
+
+	first := (side - squareSide) / 2
+	last := first + squareSide - 1
+
+	img := image.NewGray(image.Rect(0, 0, side, side))
+	for y := range side {
+		for x := range side {
+			grey := uint8(backgroundGrey)
+			if x >= first && x <= last && y >= first && y <= last {
+				grey = squareGrey
+			}
+
+			img.SetGray(x, y, color.Gray{Y: grey})
+		}
+	}
+
+	return encodePNG(t, img)
+}
+
+// squareLength returns how long the square is along greys, the greys of a
+// row or column of the output that crosses it: the distance between the
+// first and the last point where greys passes halfwayGrey, or 0 when there
+// is no such point. Resampling blurs the square's edges over several
+// pixels, and each point is placed between the two pixels on either side
+// of it in proportion to their greys, so the length is measured to a
+// fraction of a pixel.
+func squareLength(greys []float64) float64 {
+	first, last := -1.0, -1.0
+
+	for i := 1; i < len(greys); i++ {
+		before, after := greys[i-1], greys[i]
+		if (before > halfwayGrey) == (after > halfwayGrey) {
+			continue
+		}
+
+		point := float64(i-1) + (before-halfwayGrey)/(before-after)
+		if first < 0 {
+			first = point
+		}
+
+		last = point
+	}
+
+	return last - first
+}
+
+// TestImageProcessor_FitCoverKeepsProportions verifies that FitCover scales
+// both sides of the source by the same amount: a square in the centre of
+// the source comes out square. Its width and height are measured along the
+// output's middle row and column.
+func TestImageProcessor_FitCoverKeepsProportions(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name             string
+		side, squareSide int
+		size             Size
+	}{
+		{"16x16 at 100x60", 16, 8, Size{Width: 100, Height: 60}},
+		{"16x16 at 60x100", 16, 8, Size{Width: 60, Height: 100}},
+		{"10x10 at 100x35", 10, 2, Size{Width: 100, Height: 35}},
+		{"10x10 at 35x100", 10, 2, Size{Width: 35, Height: 100}},
+		{"64x64 at 300x100", 64, 16, Size{Width: 300, Height: 100}},
+		{"64x64 at 100x300", 64, 16, Size{Width: 100, Height: 300}},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			input := createSquarePNG(t, tt.side, tt.squareSide)
+
+			result, err := New(Params{}).Process(t.Context(),
+				bytes.NewReader(input),
+				&Request{Size: tt.size, Format: FormatPNG, FitMode: FitCover})
+			if err != nil {
+				t.Fatalf("Process() error = %v", err)
+			}
+
+			defer func() { _ = result.Content.Close() }()
+
+			output, err := png.Decode(result.Content)
+			if err != nil {
+				t.Fatalf("failed to decode output: %v", err)
+			}
+
+			bounds := output.Bounds()
+			if bounds.Dx() != tt.size.Width || bounds.Dy() != tt.size.Height {
+				t.Fatalf("Process() made %dx%d, want %dx%d",
+					bounds.Dx(), bounds.Dy(), tt.size.Width, tt.size.Height)
+			}
+
+			row := make([]float64, bounds.Dx())
+			for x := range row {
+				r, _, _, _ := output.At(x, bounds.Dy()/2).RGBA()
+				row[x] = float64(r >> 8)
+			}
+
+			column := make([]float64, bounds.Dy())
+			for y := range column {
+				r, _, _, _ := output.At(bounds.Dx()/2, y).RGBA()
+				column[y] = float64(r >> 8)
+			}
+
+			width, height := squareLength(row), squareLength(column)
+			t.Logf("square is %.2f wide and %.2f high", width, height)
+
+			if width == 0 || math.Abs(width-height) > 0.5 {
+				t.Errorf("square is %.2f wide and %.2f high, want it square",
+					width, height)
+			}
+		})
+	}
+}

internal/imageprocessor/fit_outside_internal_test.go

@@ -60,3 +60,45 @@ func TestImageProcessor_RefusesFitOutsideAboveMaximum(t *testing.T) {
 		})
 	}
 }
+
+// TestImageProcessor_FitOutsideSideIsAtLeastOne verifies that FitOutside
+// keeps each side at 1 or more when it works both sides out again from the
+// larger scale. A side of 49 scaled to 1 is 49 times 1/49, which in floating
+// point is just under 1 and so rounded down to 0, a width libvips refuses.
+func TestImageProcessor_FitOutsideSideIsAtLeastOne(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name                    string
+		inputWidth, inputHeight int
+		size                    Size
+		wantWidth, wantHeight   int
+	}{
+		{"49x8192 at 0x100", 49, 8192, Size{Height: 100}, 1, 167},
+		{"49x49 at 1x1", 49, 49, Size{Width: 1, Height: 1}, 1, 1},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			input := createTestJPEG(t, tt.inputWidth, tt.inputHeight)
+
+			result, err := New(Params{}).Process(t.Context(),
+				bytes.NewReader(input),
+				&Request{Size: tt.size, Format: FormatJPEG, FitMode: FitOutside})
+			if err != nil {
+				t.Fatalf("Process() error = %v", err)
+			}
+
+			defer func() { _ = result.Content.Close() }()
+
+			t.Logf("Process() made %dx%d", result.Width, result.Height)
+
+			if result.Width != tt.wantWidth || result.Height != tt.wantHeight {
+				t.Errorf("Process() made %dx%d, want %dx%d",
+					result.Width, result.Height, tt.wantWidth, tt.wantHeight)
+			}
+		})
+	}
+}

internal/imageprocessor/imageprocessor.go

@@ -7,11 +7,11 @@ import (
 	"errors"
 	"fmt"
 	"io"
-	"runtime"
 	"sync"
 	"time"
 
 	"github.com/davidbyttow/govips/v2/vips"
+	"sneak.berlin/go/pixa/internal/config"
 )
 
 // vipsOnce ensures vips is initialized exactly once.
@@ -20,11 +20,10 @@ import (
 var vipsOnce sync.Once
 
 // initVips initializes libvips with quiet logging, one worker thread per
-// image and no operation cache. Process already works on one image per CPU
-// by default, so more threads per image would only compete for the CPUs.
-// Each request decodes different source bytes, so the operation cache
-// would rarely be hit and would hold memory outside MaxConcurrentProcessing;
-// repeated requests are served from pixa's disk cache instead.
+// image and no operation cache. Each request decodes different source
+// bytes, so the operation cache would rarely be hit and would hold memory
+// outside MaxConcurrentProcessing; repeated requests are served from
+// pixa's disk cache instead.
 func initVips() {
 	vipsOnce.Do(func() {
 		vips.LoggingSettings(nil, vips.LogLevelError)
@@ -179,7 +178,7 @@ type Params struct {
 	// If <= 0, DefaultMaxInputBytes is used.
 	MaxInputBytes int64
 	// MaxConcurrentProcessing is the most images processed at once.
-	// If <= 0, the number of CPUs Go uses (runtime.GOMAXPROCS(0)) is used.
+	// If <= 0, config.DefaultMaxConcurrentProcessing() is used.
 	MaxConcurrentProcessing int
 }
 
@@ -195,7 +194,7 @@ func New(params Params) *ImageProcessor {
 
 	maxConcurrentProcessing := params.MaxConcurrentProcessing
 	if maxConcurrentProcessing <= 0 {
-		maxConcurrentProcessing = runtime.GOMAXPROCS(0)
+		maxConcurrentProcessing = config.DefaultMaxConcurrentProcessing()
 	}
 
 	return &ImageProcessor{
@@ -312,8 +311,10 @@ func (p *ImageProcessor) Process(
 
 // targetDimensions calculates the output dimensions for a requested size,
 // scaling proportionally when only one dimension is given and keeping the
-// original dimensions when both are zero. A side scaled proportionally can
-// come out above MaxOutputDimension, which is ErrOutputTooLarge.
+// original dimensions when both are zero. A side scaled proportionally is
+// rounded down but kept at 1 or more, as for a thin image it would round
+// down to 0, a side of no pixels. It can come out above MaxOutputDimension,
+// which is ErrOutputTooLarge.
 func targetDimensions(size Size, origWidth, origHeight int) (int, int, error) {
 	width, height := size.Width, size.Height
 
@@ -323,10 +324,10 @@ func targetDimensions(size Size, origWidth, origHeight int) (int, int, error) {
 		return origWidth, origHeight, nil
 	case width == 0:
 		// Only height specified: calculate width proportionally
-		width = origWidth * height / origHeight
+		width = max(1, origWidth*height/origHeight)
 	case height == 0:
 		// Only width specified: calculate height proportionally
-		height = origHeight * width / origWidth
+		height = max(1, origHeight*width/origWidth)
 	}
 
 	if width > MaxOutputDimension || height > MaxOutputDimension {
@@ -476,17 +477,20 @@ func (p *ImageProcessor) resize(
 ) error {
 	switch fit {
 	case FitCover, "":
-		// Resize and crop to fill exact dimensions (default)
-		return img.Thumbnail(width, height, vips.InterestingCentre)
+		// Crop the centre and resize to fill exact dimensions (default)
+		return cropCentreAndResize(img, width, height)
 
 	case FitContain:
-		// Resize to fit within dimensions, maintaining aspect ratio
+		// Resize to fit within dimensions, maintaining aspect ratio. Scaled
+		// by the smaller scale, the short side of a thin image can round
+		// down to 0, which libvips refuses as a width, so each side is at
+		// least 1.
 		imgW, imgH := img.Width(), img.Height()
 		scaleW := float64(width) / float64(imgW)
 		scaleH := float64(height) / float64(imgH)
 		scale := min(scaleW, scaleH)
-		newW := int(float64(imgW) * scale)
-		newH := int(float64(imgH) * scale)
+		newW := max(1, int(float64(imgW)*scale))
+		newH := max(1, int(float64(imgH)*scale))
 
 		return img.Thumbnail(newW, newH, vips.InterestingNone)
 
@@ -504,19 +508,22 @@ func (p *ImageProcessor) resize(
 		scaleW := float64(width) / float64(imgW)
 		scaleH := float64(height) / float64(imgH)
 		scale := min(scaleW, scaleH)
-		newW := int(float64(imgW) * scale)
-		newH := int(float64(imgH) * scale)
+		newW := max(1, int(float64(imgW)*scale))
+		newH := max(1, int(float64(imgH)*scale))
 
 		return img.Thumbnail(newW, newH, vips.InterestingNone)
 
 	case FitOutside:
-		// Resize so smallest dimension fits, may exceed target on other dimension
+		// Resize so smallest dimension fits, may exceed target on other
+		// dimension. A side scaled to 1 can come out just under 1 in
+		// floating point, as 49 times 1/49 does, and round down to 0, which
+		// libvips refuses as a width, so each side is at least 1.
 		imgW, imgH := img.Width(), img.Height()
 		scaleW := float64(width) / float64(imgW)
 		scaleH := float64(height) / float64(imgH)
 		scale := max(scaleW, scaleH)
-		newW := int(float64(imgW) * scale)
-		newH := int(float64(imgH) * scale)
+		newW := max(1, int(float64(imgW)*scale))
+		newH := max(1, int(float64(imgH)*scale))
 
 		// The dimension that exceeds the target is held to the maximum too
 		if newW > MaxOutputDimension || newH > MaxOutputDimension {
@@ -531,6 +538,38 @@ func (p *ImageProcessor) resize(
 	}
 }
 
+// cropCentreAndResize scales img by the same amount on both sides, the
+// least that makes it cover width x height, and cuts the centre width x
+// height out of it, as libvips' thumbnail does with InterestingCentre.
+// thumbnail alone scales the whole image and copies the result into memory
+// before it cuts, and for a thin image that is far larger than the image or
+// the output: 8192x64 at 8192x8192 is 1048576x8192, about 24 GiB. So the
+// centre is cut from img first, widened to whole pixels of img, which adds
+// less than one pixel of img on each side, and thumbnail scales and cuts
+// only that.
+func cropCentreAndResize(img *vips.ImageRef, width, height int) error {
+	imgW, imgH := img.Width(), img.Height()
+
+	// An image wider than the requested proportions keeps its height and
+	// loses width down to imgH*width/height, any other keeps its width and
+	// loses height down to imgW*height/width. Half of what is lost comes
+	// off each side, rounded down to whole pixels, so the part kept holds
+	// all of the centre.
+	left, top := 0, 0
+	if imgW*height > imgH*width {
+		left = (imgW*height - imgH*width) / (2 * height) //nolint:mnd // each side
+	} else {
+		top = (imgH*width - imgW*height) / (2 * width) //nolint:mnd // each side
+	}
+
+	err := img.ExtractArea(left, top, imgW-2*left, imgH-2*top)
+	if err != nil {
+		return err
+	}
+
+	return img.Thumbnail(width, height, vips.InterestingCentre)
+}
+
 const defaultQuality = 85
 
 // encode encodes an image to the specified format. govips gives pixa no way

internal/imageprocessor/max_concurrent_processing_internal_test.go

@@ -115,14 +115,14 @@ func waitForEntries(t *testing.T, entered <-chan struct{}, count int) {
 	}
 }
 
-func TestNewDefaultsMaxConcurrentProcessingToCPUs(t *testing.T) {
+func TestNewDefaultsMaxConcurrentProcessingToHalfTheCPUs(t *testing.T) {
 	t.Parallel()
 
 	for _, limit := range []int{0, -1} {
 		proc := New(Params{MaxConcurrentProcessing: limit})
-		if got := cap(proc.processingSemaphore); got != runtime.GOMAXPROCS(0) {
-			t.Errorf("MaxConcurrentProcessing %d: %d slots, want %d, one per CPU",
-				limit, got, runtime.GOMAXPROCS(0))
+		if got := cap(proc.processingSemaphore); got != max(runtime.GOMAXPROCS(0)/2, 1) {
+			t.Errorf("MaxConcurrentProcessing %d: %d slots, want %d, half the CPUs",
+				limit, got, max(runtime.GOMAXPROCS(0)/2, 1))
 		}
 	}
 
@@ -132,6 +132,30 @@ func TestNewDefaultsMaxConcurrentProcessingToCPUs(t *testing.T) {
 	}
 }
 
+// TestNewDefaultIsHalfTheCPUsAndAtLeastOne checks that New, given no
+// MaxConcurrentProcessing, makes one slot for every two CPUs Go uses,
+// rounded down, and one slot when Go uses one CPU.
+//
+//nolint:paralleltest // it sets GOMAXPROCS, which other tests read
+func TestNewDefaultIsHalfTheCPUsAndAtLeastOne(t *testing.T) {
+	cpusBefore := runtime.GOMAXPROCS(0)
+
+	t.Cleanup(func() { runtime.GOMAXPROCS(cpusBefore) })
+
+	for _, tc := range []struct{ cpus, want int }{
+		{1, 1}, {2, 1}, {3, 1}, {8, 4},
+	} {
+		runtime.GOMAXPROCS(tc.cpus)
+
+		got := cap(New(Params{}).processingSemaphore)
+		t.Logf("GOMAXPROCS %d: %d slots", tc.cpus, got)
+
+		if got != tc.want {
+			t.Errorf("GOMAXPROCS %d: %d slots, want %d", tc.cpus, got, tc.want)
+		}
+	}
+}
+
 // TestProcessNeverExceedsMaxConcurrentProcessing starts more Process calls
 // than MaxConcurrentProcessing allows and holds the first ones inside
 // Process until the test lets them go. No more than the limit may be

internal/imgcache/service.go

@@ -53,7 +53,7 @@ type ServiceConfig struct {
 	// Allowlist is the list of hosts that don't require signatures
 	Allowlist []string
 	// MaxConcurrentProcessing is the most images processed at once; zero
-	// uses the image processor's default, one per CPU
+	// uses the image processor's default, half the CPUs
 	MaxConcurrentProcessing int
 	// Logger for logging
 	Logger *slog.Logger

internal/imgcache/urlparser.go

@@ -3,6 +3,7 @@ package imgcache
 import (
 	"errors"
 	"fmt"
+	"net/netip"
 	"net/url"
 	"regexp"
 	"strconv"
@@ -47,6 +48,17 @@ func ValidateDimension(name string, value int) error {
 var sizeFormatRegex = regexp.MustCompile(
 	`^(\d+)x(\d+)(?:\.(\w+))?$|^(orig)(?:\.(\w+))?$`)
 
+// percentEscapeRegex matches one percent-escape, such as "%2e"
+var percentEscapeRegex = regexp.MustCompile(`%[0-9A-Fa-f]{2}`)
+
+// hostRegex matches the forms the host of an image URL may take: a host name
+// or an IPv4 address (letters, digits, "-", "_" and "."), or an IPv6 address
+// in brackets (hex digits, ":" and "."), either one optionally followed by ":"
+// and a port, which may be empty. Its one group holds the text in brackets,
+// which parseImageComponents also checks is an IPv6 address.
+var hostRegex = regexp.MustCompile(
+	`^(?:[A-Za-z0-9_.-]+|\[([0-9A-Fa-f:.]+)\])(?::[0-9]*)?$`)
+
 // ParsedURL contains the parsed components of an image proxy URL.
 type ParsedURL struct {
 	// Host is the source origin host (e.g., "cdn.example.com")
@@ -61,9 +73,8 @@ type ParsedURL struct {
 	Format ImageFormat
 }
 
-// ParseImagePath parses the path captured by chi's wildcard:
-// <host>/<path>/<size>.<format>, or <host>/<path>/<size> for JPEG XL
-// This is the primary entry point when using chi routing.
+// ParseImagePath parses an image URL's path after /v1/image/, decoded once:
+// <host>/<path>/<size>.<format>, or <host>/<path>/<size> for JPEG XL.
 // Examples:
 //   - cdn.example.com/photos/cat.jpg/800x600.webp
 //   - cdn.example.com/photos/cat.jpg/0x0.jpeg
@@ -79,9 +90,10 @@ func ParseImagePath(path string) (*ParsedURL, error) {
 	return parseImageComponents(path)
 }
 
-// ParseImageURL parses a full URL path like /v1/image/<host>/<path>/<size>.<format>,
-// or /v1/image/<host>/<path>/<size> for JPEG XL
-// Use ParseImagePath instead when working with chi's wildcard capture.
+// ParseImageURL parses an image URL's path, decoded once as r.URL.Path holds
+// it: /v1/image/<host>/<path>/<size>.<format>, or /v1/image/<host>/<path>/<size>
+// for JPEG XL. A source query follows the source path after a "?", which the
+// URL writes as %3F.
 func ParseImageURL(urlPath string) (*ParsedURL, error) {
 	// Remove the /v1/image/ prefix
 	const prefix = "/v1/image/"
@@ -100,12 +112,6 @@ func ParseImageURL(urlPath string) (*ParsedURL, error) {
 // parseImageComponents parses <host>/<path>/<size>.<format>, or
 // <host>/<path>/<size> for JPEG XL.
 func parseImageComponents(remainder string) (*ParsedURL, error) {
-	// Check for path traversal before any other processing
-	err := checkPathTraversal(remainder)
-	if err != nil {
-		return nil, err
-	}
-
 	// Find the last path segment, which holds "size" or "size.format"
 	lastSlash := strings.LastIndex(remainder, "/")
 	if lastSlash == -1 {
@@ -144,10 +150,20 @@ func parseImageComponents(remainder string) (*ParsedURL, error) {
 		return nil, ErrMissingHost
 	}
 
-	// A URL reads what comes before "@" as a user name and password, and the
-	// rest as the host
-	if strings.Contains(host, "@") {
-		return nil, fmt.Errorf("%w: %q holds @", ErrInvalidHost, host)
+	// Only the forms hostRegex describes are accepted. A "?", "#" or "@" in
+	// the host would make Go's URL parser, which the allowlist check and the
+	// fetcher use, read a different host from the one allowlisted and cached
+	hostMatch := hostRegex.FindStringSubmatch(host)
+	if hostMatch == nil {
+		return nil, fmt.Errorf("%w: %q", ErrInvalidHost, host)
+	}
+
+	// Go's URL parser refuses brackets around anything but an IPv6 address
+	if inBrackets := hostMatch[1]; inBrackets != "" {
+		addr, err := netip.ParseAddr(inBrackets)
+		if err != nil || !addr.Is6() {
+			return nil, fmt.Errorf("%w: %q", ErrInvalidHost, host)
+		}
 	}
 
 	// Host names do not depend on letter case, so the allowlist, the upstream
@@ -155,12 +171,27 @@ func parseImageComponents(remainder string) (*ParsedURL, error) {
 	// host
 	host = strings.ToLower(host)
 
+	// Go's URL parser, which the fetcher uses, reads a "#" as the start of a
+	// fragment and drops the rest, so each text after it would be another
+	// spelling, cached under its own keys, of one upstream request
+	if strings.Contains(path, "#") {
+		return nil, fmt.Errorf(
+			`%w: the source path or query holds a "#"`, ErrInvalidPath)
+	}
+
 	// Extract query string if present in path
 	if qIndex := strings.Index(path, "?"); qIndex != -1 {
 		query = path[qIndex+1:]
 		path = path[:qIndex]
 	}
 
+	// The source query names no file on the upstream, so only the host and
+	// the source path are checked for path traversal
+	err = checkPathTraversal(host + path)
+	if err != nil {
+		return nil, err
+	}
+
 	// Ensure path starts with /
 	if !strings.HasPrefix(path, "/") {
 		path = "/" + path
@@ -186,12 +217,7 @@ func checkPathTraversal(path string) error {
 	// Decode multiple times to catch double-encoding
 	decoded := path
 	for range 3 {
-		newDecoded, err := url.PathUnescape(decoded)
-		if err != nil {
-			// Malformed encoding is suspicious
-			return ErrPathTraversal
-		}
-
+		newDecoded := decodePercentEscapes(decoded)
 		if newDecoded == decoded {
 			break
 		}
@@ -232,6 +258,18 @@ func checkPathTraversal(path string) error {
 	return nil
 }
 
+// decodePercentEscapes decodes every percent-escape in s, such as %2e, and
+// keeps a "%" that does not start one as it is, where url.PathUnescape would
+// refuse the whole string. A source path holding %25, a literal "%", has such
+// a "%" after one more decoding.
+func decodePercentEscapes(s string) string {
+	return percentEscapeRegex.ReplaceAllStringFunc(s, func(escape string) string {
+		decoded, _ := url.PathUnescape(escape)
+
+		return decoded
+	})
+}
+
 // parseSizeFormat parses strings like "800x600.webp", "orig.png" or "800x600"
 func parseSizeFormat(s string) (Size, ImageFormat, error) {
 	matches := sizeFormatRegex.FindStringSubmatch(s)

internal/imgcache/urlparser_internal_test.go

@@ -407,6 +407,71 @@ func TestParseImagePath_PathTraversal(t *testing.T) {
 	}
 }
 
+// TestParseImageURL_SourceURLHoldingPercent25 verifies that a source path and
+// a source query holding %25, the percent-escape of a literal "%", are
+// accepted as they are, although decoding them once more leaves a "%" that
+// does not start a percent-escape.
+func TestParseImageURL_SourceURLHoldingPercent25(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name  string
+		input string
+		want  *ParsedURL
+	}{
+		{
+			name:  "path",
+			input: "/v1/image/cdn.example.com/sale/50%25off.jpg/800x600.webp",
+			want: &ParsedURL{
+				Host: testHostCDN, Path: "/sale/50%25off.jpg",
+				Size: Size{Width: 800, Height: 600}, Format: FormatWebP,
+			},
+		},
+		{
+			name:  "query",
+			input: "/v1/image/cdn.example.com/photos/cat.jpg?discount=50%25/800x600.webp",
+			want: &ParsedURL{
+				Host: testHostCDN, Path: testPathCat, Query: "discount=50%25",
+				Size: Size{Width: 800, Height: 600}, Format: FormatWebP,
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			got, err := ParseImageURL(tt.input)
+			if err != nil {
+				t.Fatalf("ParseImageURL() unexpected error = %v", err)
+			}
+
+			assertParsedURL(t, got, tt.want)
+		})
+	}
+}
+
+// TestParseImageURL_DoubleEncodedTraversalNextToPercent verifies that a
+// double-encoded ".." is still refused when the path also holds a "%" that
+// does not start a percent-escape, either as written or after one more
+// decoding.
+func TestParseImageURL_DoubleEncodedTraversalNextToPercent(t *testing.T) {
+	t.Parallel()
+
+	for _, input := range []string{
+		"/v1/image/cdn.example.com/photos/%252e%252e/secret/50%25off.jpg/800x600.jpeg",
+		"/v1/image/cdn.example.com/photos/%252e%252e/secret/100%/800x600.jpeg",
+	} {
+		_, err := ParseImageURL(input)
+		t.Logf("ParseImageURL(%q) error = %v", input, err)
+
+		if !errors.Is(err, ErrPathTraversal) {
+			t.Errorf("ParseImageURL(%q) error = %v, want ErrPathTraversal",
+				input, err)
+		}
+	}
+}
+
 // errorIs checks if err matches target (handles wrapped errors).
 func errorIs(err, target error) bool {
 	if errors.Is(err, target) {

internal/signature/signature.go

@@ -126,31 +126,20 @@ func (s *Signer) GenerateSignedURL(
 		sizeStr = fmt.Sprintf("%dx%d", req.Width, req.Height)
 	}
 
-	// Build the path.
-	// When a source query is present, it is embedded as a path segment
-	// (e.g. /host/path?query/size.fmt) so that the URL parser can extract
-	// it from the last-slash split. The "?" inside a path segment is
-	// percent-encoded by clients but chi delivers it decoded, which is
-	// exactly what the URL parser expects.
-	var path string
+	// Build the path. A source query follows the source path after a "?".
+	// The image route reads the path decoded once, so the whole path is
+	// written in Go's own percent-encoding of a URL path, which writes "?"
+	// as %3F and "%" as %25, and leaves "/", ";", ",", "=" and "&" as they
+	// are.
+	sourcePathAndQuery := req.SourcePath
 	if req.SourceQuery != "" {
-		path = fmt.Sprintf("/v1/image/%s%s%%3F%s/%s.%s",
-			req.SourceHost,
-			req.SourcePath,
-			url.PathEscape(req.SourceQuery),
-			sizeStr,
-			req.Format,
-		)
-	} else {
-		path = fmt.Sprintf("/v1/image/%s%s/%s.%s",
-			req.SourceHost,
-			req.SourcePath,
-			sizeStr,
-			req.Format,
-		)
+		sourcePathAndQuery += "?" + req.SourceQuery
 	}
 
-	return path, sig, exp
+	unescapedPath := fmt.Sprintf("/v1/image/%s%s/%s.%s",
+		req.SourceHost, sourcePathAndQuery, sizeStr, req.Format)
+
+	return (&url.URL{Path: unescapedPath}).EscapedPath(), sig, exp
 }
 
 // buildSignatureData creates the string to be signed.

internal/signature/signature_test.go

@@ -475,6 +475,44 @@ func TestGenerateSignedURL_WithoutQueryString(t *testing.T) {
 	}
 }
 
+// TestGenerateSignedURL_ReadmeQueryExample checks the README's example of a
+// source URL with a query, the image at
+// https://cdn.example.com/img?url=https://origin.example.com/my%20cat.jpg: its
+// signature with the README's key, and the path GenerateSignedURL writes for
+// it, with the "?" written as %3F and the "%" as %25.
+func TestGenerateSignedURL_ReadmeQueryExample(t *testing.T) {
+	t.Parallel()
+
+	signer := signature.New("example-signing-key-for-documentation")
+
+	req := signature.Request{
+		SourceHost:  testHost,
+		SourcePath:  "/img",
+		SourceQuery: "url=https://origin.example.com/my%20cat.jpg",
+		Width:       800,
+		Height:      600,
+		Format:      testFormatWebP,
+		Quality:     85,
+		FitMode:     testFitCover,
+		Expires:     time.Unix(1704067200, 0),
+	}
+
+	const wantSig = "37aFa9GSVCZM1kRY9SzMOk2fOg_M7Wt5gKNR4xM-FYA="
+
+	gotSig := signer.Sign(&req)
+	if gotSig != wantSig {
+		t.Errorf("Sign() = %q, want %q", gotSig, wantSig)
+	}
+
+	const wantPath = "/v1/image/cdn.example.com" +
+		"/img%3Furl=https://origin.example.com/my%2520cat.jpg/800x600.webp"
+
+	gotPath, _, _ := signer.GenerateSignedURL(&req, time.Hour)
+	if gotPath != wantPath {
+		t.Errorf("GenerateSignedURL() path = %q, want %q", gotPath, wantPath)
+	}
+}
+
 func TestParseParams(t *testing.T) {
 	t.Parallel()