docs(compression): deprecate ContentEncoding, add CAFxX recipe (#447)

Mark negotiate.ContentEncoding deprecated — the runtime does not ship
compression. Add a runnable example under
docs/examples/middleware/compression/ showing composition with
github.com/CAFxX/httpcompression at the http.Handler level. The
example lives in its own go module (registered in go.work) so CAFxX
is not pulled into the root go.mod.

* closes #440

Signed-off-by: Frederic BIDON <fredbi@yahoo.com>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: fredbi

docs/examples/middleware/compression/README.md

@@ -0,0 +1,59 @@
+# Compression middleware example
+
+This example shows how to add transparent HTTP response compression
+(gzip, brotli, …) to a `go-openapi/runtime` server by wrapping the
+`http.Handler` returned by `middleware.Serve` with a standard
+ecosystem compression middleware.
+
+The runtime itself does not ship compression. Composition with an
+external middleware is the recommended approach; this example uses
+[`github.com/CAFxX/httpcompression`](https://github.com/CAFxX/httpcompression),
+which covers gzip + brotli + zstd + deflate with sensible defaults
+(content-type allowlist, minimum-size threshold, `Vary` / `ETag` /
+`Content-Length` handling).
+
+## Run
+
+```sh
+go run .
+```
+
+Then in another terminal:
+
+```sh
+# Plain (uncompressed) response.
+curl -i http://localhost:8080/api/greeting
+
+# Gzip-compressed response.
+curl -i -H 'Accept-Encoding: gzip' http://localhost:8080/api/greeting
+
+# Brotli-compressed response (DefaultAdapter enables brotli too).
+curl -i -H 'Accept-Encoding: br' --compressed http://localhost:8080/api/greeting
+```
+
+The compressed response carries `Content-Encoding: gzip` (or `br`),
+`Vary: Accept-Encoding`, and a transformed `Content-Length`. The
+`go-openapi/runtime` pipeline is unchanged — the compressor sits
+outside the API handler and operates on the final response bytes.
+
+## Layering
+
+The order of middlewares around the api handler matters:
+
+```text
+client ─► [ TLS / auth / rate-limit ] ─► [ compress ] ─► [ go-openapi api ] ─► handler
+```
+
+The compressor must wrap the api handler so it sees the complete
+response body before transport. Transport-level concerns (TLS
+termination, auth gating, rate limiting) typically wrap the
+compressor in turn.
+
+## Client-side
+
+`net/http`'s default transport auto-decodes `gzip` responses, but not
+`br` / `zstd` / `deflate`. Clients that need broader decoding can wrap
+their `http.RoundTripper` with a decoder; `github.com/klauspost/compress`
+provides primitives suitable for that purpose. The `go-openapi/runtime`
+client (`client.Runtime`) accepts a custom transport via its
+configuration, so the same pattern applies.

docs/examples/middleware/compression/go.mod

@@ -0,0 +1,38 @@
+module github.com/go-openapi/runtime/docs/examples/middleware/compression
+
+go 1.25.0
+
+require (
+	github.com/CAFxX/httpcompression v0.0.9
+	github.com/go-openapi/loads v0.23.3
+	github.com/go-openapi/runtime v0.30.0
+)
+
+require (
+	github.com/andybalholm/brotli v1.0.5 // indirect
+	github.com/go-openapi/analysis v0.25.0 // indirect
+	github.com/go-openapi/errors v0.22.7 // indirect
+	github.com/go-openapi/jsonpointer v0.22.5 // indirect
+	github.com/go-openapi/jsonreference v0.21.5 // indirect
+	github.com/go-openapi/runtime/server-middleware v0.30.0 // indirect
+	github.com/go-openapi/spec v0.22.4 // indirect
+	github.com/go-openapi/strfmt v0.26.2 // indirect
+	github.com/go-openapi/swag/conv v0.26.0 // indirect
+	github.com/go-openapi/swag/fileutils v0.26.0 // indirect
+	github.com/go-openapi/swag/jsonname v0.25.5 // indirect
+	github.com/go-openapi/swag/jsonutils v0.26.0 // indirect
+	github.com/go-openapi/swag/loading v0.25.5 // indirect
+	github.com/go-openapi/swag/mangling v0.25.5 // indirect
+	github.com/go-openapi/swag/stringutils v0.26.0 // indirect
+	github.com/go-openapi/swag/typeutils v0.26.0 // indirect
+	github.com/go-openapi/swag/yamlutils v0.25.5 // indirect
+	github.com/go-openapi/validate v0.25.2 // indirect
+	github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/klauspost/compress v1.16.7 // indirect
+	github.com/oklog/ulid/v2 v2.1.1 // indirect
+	go.yaml.in/yaml/v3 v3.0.4 // indirect
+	golang.org/x/net v0.53.0 // indirect
+	golang.org/x/sync v0.20.0 // indirect
+	golang.org/x/text v0.36.0 // indirect
+)

docs/examples/middleware/compression/go.sum

@@ -0,0 +1,90 @@
+github.com/CAFxX/httpcompression v0.0.9 h1:0ue2X8dOLEpxTm8tt+OdHcgA+gbDge0OqFQWGKSqgrg=
+github.com/CAFxX/httpcompression v0.0.9/go.mod h1:XX8oPZA+4IDcfZ0A71Hz0mZsv/YJOgYygkFhizVPilM=
+github.com/andybalholm/brotli v1.0.5 h1:8uQZIdzKmjc/iuPu7O2ioW48L81FgatrcpfFmiq/cCs=
+github.com/andybalholm/brotli v1.0.5/go.mod h1:fO7iG3H7G2nSZ7m0zPUDn85XEX2GTukHGRSepvi9Eig=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/go-openapi/analysis v0.25.0 h1:EnjAq1yO8wEO9HbPmY8vLPEIkdZuuFhCAKBPvCB7bCs=
+github.com/go-openapi/analysis v0.25.0/go.mod h1:5WFTRE43WLkPG9r9OtlMfqkkvUTYLVVCIxLlEpyF8kE=
+github.com/go-openapi/errors v0.22.7 h1:JLFBGC0Apwdzw3484MmBqspjPbwa2SHvpDm0u5aGhUA=
+github.com/go-openapi/errors v0.22.7/go.mod h1://QW6SD9OsWtH6gHllUCddOXDL0tk0ZGNYHwsw4sW3w=
+github.com/go-openapi/jsonpointer v0.22.5 h1:8on/0Yp4uTb9f4XvTrM2+1CPrV05QPZXu+rvu2o9jcA=
+github.com/go-openapi/jsonpointer v0.22.5/go.mod h1:gyUR3sCvGSWchA2sUBJGluYMbe1zazrYWIkWPjjMUY0=
+github.com/go-openapi/jsonreference v0.21.5 h1:6uCGVXU/aNF13AQNggxfysJ+5ZcU4nEAe+pJyVWRdiE=
+github.com/go-openapi/jsonreference v0.21.5/go.mod h1:u25Bw85sX4E2jzFodh1FOKMTZLcfifd1Q+iKKOUxExw=
+github.com/go-openapi/loads v0.23.3 h1:g5Xap1JfwKkUnZdn+S0L3SzBDpcTIYzZ5Qaag0YDkKQ=
+github.com/go-openapi/loads v0.23.3/go.mod h1:NOH07zLajXo8y55hom0omlHWDVVvCwBM/S+csCK8LqA=
+github.com/go-openapi/runtime v0.30.0 h1:1llnyZcqkjm77VhM4FPO1O1rt2SzLZIRPkZAY4wv4mw=
+github.com/go-openapi/runtime v0.30.0/go.mod h1:QtJGUq+1S0VWPP+LQldH6o4tcqGsjzTVjn/wIWEn9o4=
+github.com/go-openapi/runtime/server-middleware v0.30.0 h1:8rPoJ/xv7JL8BsovaqboKETlpWBArVh8n+0L/GyePog=
+github.com/go-openapi/runtime/server-middleware v0.30.0/go.mod h1:OYNT/TxNvB/VK5oe4htM2jDTwlEXuejVJmu0DVZfAMs=
+github.com/go-openapi/spec v0.22.4 h1:4pxGjipMKu0FzFiu/DPwN3CTBRlVM2yLf/YTWorYfDQ=
+github.com/go-openapi/spec v0.22.4/go.mod h1:WQ6Ai0VPWMZgMT4XySjlRIE6GP1bGQOtEThn3gcWLtQ=
+github.com/go-openapi/strfmt v0.26.2 h1:ysjheCh4i1rmFEo2LanhELDNucNzfWTZhUDKgWWPaFM=
+github.com/go-openapi/strfmt v0.26.2/go.mod h1:fXh1e449cyUn2NYuz+wb3wARBUdMl7qPEZwX00nqivY=
+github.com/go-openapi/swag/conv v0.26.0 h1:5yGGsPYI1ZCva93U0AoKi/iZrNhaJEjr324YVsiD89I=
+github.com/go-openapi/swag/conv v0.26.0/go.mod h1:tpAmIL7X58VPnHHiSO4uE3jBeRamGsFsfdDeDtb5ECE=
+github.com/go-openapi/swag/fileutils v0.26.0 h1:WJoPRvsA7QRiiWluowkLJa9jaYR7FCuxmDvnCgaRRxU=
+github.com/go-openapi/swag/fileutils v0.26.0/go.mod h1:0WDJ7lp67eNjPMO50wAWYlKvhOb6CQ37rzR7wrgI8Tc=
+github.com/go-openapi/swag/jsonname v0.25.5 h1:8p150i44rv/Drip4vWI3kGi9+4W9TdI3US3uUYSFhSo=
+github.com/go-openapi/swag/jsonname v0.25.5/go.mod h1:jNqqikyiAK56uS7n8sLkdaNY/uq6+D2m2LANat09pKU=
+github.com/go-openapi/swag/jsonutils v0.26.0 h1:FawFML2iAXsPqmERscuMPIHmFsoP1tOqWkxBaKNMsnA=
+github.com/go-openapi/swag/jsonutils v0.26.0/go.mod h1:2VmA0CJlyFqgawOaPI9psnjFDqzyivIqLYN34t9p91E=
+github.com/go-openapi/swag/jsonutils/fixtures_test v0.26.0 h1:apqeINu/ICHouqiRZbyFvuDge5jCmmLTqGQ9V95EaOM=
+github.com/go-openapi/swag/jsonutils/fixtures_test v0.26.0/go.mod h1:AyM6QT8uz5IdKxk5akv0y6u4QvcL9GWERt0Jx/F/R8Y=
+github.com/go-openapi/swag/loading v0.25.5 h1:odQ/umlIZ1ZVRteI6ckSrvP6e2w9UTF5qgNdemJHjuU=
+github.com/go-openapi/swag/loading v0.25.5/go.mod h1:I8A8RaaQ4DApxhPSWLNYWh9NvmX2YKMoB9nwvv6oW6g=
+github.com/go-openapi/swag/mangling v0.25.5 h1:hyrnvbQRS7vKePQPHHDso+k6CGn5ZBs5232UqWZmJZw=
+github.com/go-openapi/swag/mangling v0.25.5/go.mod h1:6hadXM/o312N/h98RwByLg088U61TPGiltQn71Iw0NY=
+github.com/go-openapi/swag/stringutils v0.26.0 h1:qZQngLxs5s7SLijc3N2ZO+fUq2o8LjuWAASSrJuh+xg=
+github.com/go-openapi/swag/stringutils v0.26.0/go.mod h1:sWn5uY+QIIspwPhvgnqJsH8xqFT2ZbYcvbcFanRyhFE=
+github.com/go-openapi/swag/typeutils v0.26.0 h1:2kdEwdiNWy+JJdOvu5MA2IIg2SylWAFuuyQIKYybfq4=
+github.com/go-openapi/swag/typeutils v0.26.0/go.mod h1:oovDuIUvTrEHVMqWilQzKzV4YlSKgyZmFh7AlfABNVE=
+github.com/go-openapi/swag/yamlutils v0.25.5 h1:kASCIS+oIeoc55j28T4o8KwlV2S4ZLPT6G0iq2SSbVQ=
+github.com/go-openapi/swag/yamlutils v0.25.5/go.mod h1:Gek1/SjjfbYvM+Iq4QGwa/2lEXde9n2j4a3wI3pNuOQ=
+github.com/go-openapi/testify/enable/yaml/v2 v2.5.0 h1:3hZD1fwydvCx/cc1R2uYNQirHqf2s6lqpKV3FcNTURA=
+github.com/go-openapi/testify/enable/yaml/v2 v2.5.0/go.mod h1:TvDZKBH7ZbMaF3EqH2AwTvNQCmzyZq8K1agRjf1B+Nk=
+github.com/go-openapi/testify/v2 v2.5.0 h1:UOCr63aAsMIDydZbZGqo5Ev01D4eydItRbekDuZMJLw=
+github.com/go-openapi/testify/v2 v2.5.0/go.mod h1:SgsVHtfooshd0tublTtJ50FPKhujf47YRqauXXOUxfw=
+github.com/go-openapi/validate v0.25.2 h1:12NsfLAwGegqbGWr2CnvT65X/Q2USJipmJ9b7xDJZz0=
+github.com/go-openapi/validate v0.25.2/go.mod h1:Pgl1LpPPGFnZ+ys4/hTlDiRYQdI1ocKypgE+8Q8BLfY=
+github.com/go-viper/mapstructure/v2 v2.5.0 h1:vM5IJoUAy3d7zRSVtIwQgBj7BiWtMPfmPEgAXnvj1Ro=
+github.com/go-viper/mapstructure/v2 v2.5.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM=
+github.com/google/brotli/go/cbrotli v0.0.0-20230829110029-ed738e842d2f h1:jopqB+UTSdJGEJT8tEqYyE29zN91fi2827oLET8tl7k=
+github.com/google/brotli/go/cbrotli v0.0.0-20230829110029-ed738e842d2f/go.mod h1:nOPhAkwVliJdNTkj3gXpljmWhjc4wCaVqbMJcPKWP4s=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/klauspost/compress v1.16.7 h1:2mk3MPGNzKyxErAw8YaohYh69+pa4sIQSC0fPGCFR9I=
+github.com/klauspost/compress v1.16.7/go.mod h1:ntbaceVETuRiXiv4DpjP66DpAtAGkEQskQzEyD//IeE=
+github.com/klauspost/pgzip v1.2.6/go.mod h1:Ch1tH69qFZu15pkjo5kYi6mth2Zzwzt50oCQKQE9RUs=
+github.com/oklog/ulid/v2 v2.1.1 h1:suPZ4ARWLOJLegGFiZZ1dFAkqzhMjL3J1TzI+5wHz8s=
+github.com/oklog/ulid/v2 v2.1.1/go.mod h1:rcEKHmBBKfef9DhnvX7y1HZBYxjXb0cP5ExxNsTT1QQ=
+github.com/pborman/getopt v0.0.0-20170112200414-7148bc3a4c30/go.mod h1:85jBQOZwpVEaDAr341tbn15RS4fCAsIst0qp7i8ex1o=
+github.com/pierrec/lz4/v4 v4.1.18 h1:xaKrnTkyoqfh1YItXl56+6KJNVYWlEEPuAQW9xsplYQ=
+github.com/pierrec/lz4/v4 v4.1.18/go.mod h1:gZWDp/Ze/IJXGXf23ltt2EXimqmTUXEy0GFuRQyBid4=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+github.com/ulikunitz/xz v0.5.11/go.mod h1:nbz6k7qbPmH4IRqmfOplQw/tblSgqTqBwxkY0oWt/14=
+github.com/valyala/gozstd v1.20.1 h1:xPnnnvjmaDDitMFfDxmQ4vpx0+3CdTg2o3lALvXTU/g=
+github.com/valyala/gozstd v1.20.1/go.mod h1:y5Ew47GLlP37EkTB+B4s7r6A5rdaeB7ftbl9zoYiIPQ=
+go.yaml.in/yaml/v3 v3.0.4 h1:tfq32ie2Jv2UxXFdLJdh3jXuOzWiL1fo0bu/FbuKpbc=
+go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+golang.org/x/net v0.53.0 h1:d+qAbo5L0orcWAr0a9JweQpjXF19LMXJE8Ey7hwOdUA=
+golang.org/x/net v0.53.0/go.mod h1:JvMuJH7rrdiCfbeHoo3fCQU24Lf5JJwT9W3sJFulfgs=
+golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
+golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/text v0.36.0 h1:JfKh3XmcRPqZPKevfXVpI1wXPTqbkE5f7JA92a55Yxg=
+golang.org/x/text v0.36.0/go.mod h1:NIdBknypM8iqVmPiuco0Dh6P5Jcdk8lJL0CUebqK164=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

docs/examples/middleware/compression/main.go

@@ -0,0 +1,131 @@
+// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
+// SPDX-License-Identifier: Apache-2.0
+
+// Package main shows how to add transparent response compression
+// (gzip, brotli, etc.) to a go-openapi server by wrapping the
+// http.Handler returned by middleware.Serve with the CAFxX
+// httpcompression adapter.
+//
+// The runtime does not ship compression itself; this example is a
+// recipe for composing the existing ecosystem with the go-openapi
+// pipeline. See server-middleware/negotiate.ContentEncoding (now
+// deprecated) for context.
+//
+// Run:
+//
+//	go run .
+//	curl -sH 'Accept-Encoding: gzip' -i http://localhost:8080/api/greeting | head
+package main
+
+import (
+	"encoding/json"
+	"log"
+	"net/http"
+	"time"
+
+	httpcompression "github.com/CAFxX/httpcompression"
+
+	"github.com/go-openapi/loads"
+	"github.com/go-openapi/runtime"
+	"github.com/go-openapi/runtime/middleware"
+	"github.com/go-openapi/runtime/middleware/untyped"
+)
+
+const (
+	// greetingPayloadKeys keeps the response body comfortably above
+	// the compression middleware's MinSize threshold so the example
+	// actually exercises the compressor instead of falling through.
+	greetingPayloadKeys = 32
+
+	listenAddress     = ":8080"
+	readHeaderTimeout = 5 * time.Second
+)
+
+const swaggerSpec = `{
+  "swagger": "2.0",
+  "info": {"title": "Compression Demo", "version": "1.0"},
+  "basePath": "/api",
+  "consumes": ["application/json"],
+  "produces": ["application/json"],
+  "paths": {
+    "/greeting": {
+      "get": {
+        "operationId": "greeting",
+        "responses": {
+          "200": {
+            "description": "a greeting payload large enough to be worth compressing",
+            "schema": {"type": "object"}
+          }
+        }
+      }
+    }
+  }
+}`
+
+// greeting returns a payload large enough to clear the compression
+// middleware's default minimum-size threshold (CAFxX defaults to
+// DefaultMinSize = 200 bytes — payloads below that are left
+// uncompressed because the wire overhead would outweigh the win).
+var greeting = runtime.OperationHandlerFunc(func(_ any) (any, error) {
+	greetings := make(map[string]string, greetingPayloadKeys)
+	for i := range greetingPayloadKeys {
+		greetings[encodeKey(i)] = "Hello from go-openapi! Compression makes this body smaller on the wire."
+	}
+	return greetings, nil
+})
+
+func encodeKey(i int) string {
+	return "greeting_" + string(rune('a'+i%26))
+}
+
+func newAPI() (http.Handler, error) {
+	spec, err := loads.Analyzed(json.RawMessage(swaggerSpec), "")
+	if err != nil {
+		return nil, err
+	}
+	api := untyped.NewAPI(spec)
+	api.RegisterOperation("get", "/greeting", greeting)
+	return middleware.Serve(spec, api), nil
+}
+
+func main() {
+	apiHandler, err := newAPI()
+	if err != nil {
+		log.Fatalf("build api: %v", err)
+	}
+
+	// DefaultAdapter wires gzip + brotli encoders with sane defaults:
+	// content-type allowlist, minimum-size threshold, Vary and
+	// Content-Length handling, ETag suffixing for cacheability.
+	//
+	// Use Adapter (without "Default") for explicit codec + threshold
+	// control:
+	//
+	//   compress, err := httpcompression.Adapter(
+	//       httpcompression.GzipCompressionLevel(6),
+	//       httpcompression.BrotliCompressionLevel(4),
+	//       httpcompression.MinSize(512),
+	//       httpcompression.ContentTypes([]string{"application/json"}, false),
+	//   )
+	compress, err := httpcompression.DefaultAdapter()
+	if err != nil {
+		log.Fatalf("compression adapter: %v", err)
+	}
+
+	// Wrap the go-openapi handler. The order matters:
+	//   - the compressor must be OUTSIDE the api pipeline so it sees
+	//     the final response bytes;
+	//   - any TLS / auth / rate-limiting middleware typically wraps
+	//     the compressor (i.e. compressor sits between application
+	//     code and transport-level middleware).
+	mux := http.NewServeMux()
+	mux.Handle("/", compress(apiHandler))
+
+	log.Printf("listening on %s", listenAddress)
+	srv := &http.Server{
+		Addr:              listenAddress,
+		Handler:           mux,
+		ReadHeaderTimeout: readHeaderTimeout,
+	}
+	log.Fatal(srv.ListenAndServe())
+}

go.work

@@ -1,6 +1,7 @@
 use (
 	.
 	./client-middleware/opentracing
+	./docs/examples/middleware/compression
 	./server-middleware
 )
 

server-middleware/negotiate/negotiate.go

@@ -89,6 +89,16 @@ func WithMatchSuffix(enable bool) Option {
 //
 // Encoding tokens have no parameters, so this function is unaffected by
 // the v0.30 parameter-honouring change to [ContentType].
+//
+// Deprecated: ContentEncoding negotiation is not used by the components
+// of this project.
+//
+// This historical addition has never been associated with proper
+// compression middleware and is thus half a feature.
+// The runtime does not ship compression.
+// Use github.com/CAFxX/httpcompression or github.com/klauspost/compress/gzhttp
+// at the http.Handler level, or github.com/klauspost/compress/* for client
+// transport wrapping. See docs/examples/middleware for a recipe.
 func ContentEncoding(r *http.Request, offers []string) string {
 	bestOffer := "identity"
 	bestQ := -1.0