encode

Encodes responses using the configured encoding(s). A typical use for encoding is compression.

Syntax

encode [<matcher>] [<formats...>] {
	# encoding formats
	gzip [<level>]
	zstd [<level>]
	
	minimum_length <length>

	match <inline_response_matcher>
}

• <formats...> is the list of encoding formats to enable. If multiple encodings are enabled, the encoding is chosen based the request's Accept-Encoding header; if the client has no strong preference (q-factor), then the first supported encoding is used. If omitted, zstd (preferred) and gzip are enabled by default.

• gzip enables Gzip compression, optionally at a specified level.

• zstd enables Zstandard compression, optionally at a specified level (possible values = default, fastest, better, best). The default compression level is roughly equivalent to the default Zstandard mode (level 3).

• minimum_length the minimum number of bytes a response should have to be encoded (default: 512). Server-sent events responses (Content-Type: text/event-stream) and responses with the Incremental: ?1 header field (RFC 10036) are not held back to reach this threshold: their headers are sent to the client immediately, and the body is streamed as it is written.

• match is a response matcher. Only matching responses are encoded. The default looks like this:

  match {
  	header Content-Type application/atom+xml*
  	header Content-Type application/eot*
  	header Content-Type application/font*
  	header Content-Type application/geo+json*
  	header Content-Type application/graphql+json*
  	header Content-Type application/javascript*
  	header Content-Type application/json*
  	header Content-Type application/ld+json*
  	header Content-Type application/manifest+json*
  	header Content-Type application/opentype*
  	header Content-Type application/otf*
  	header Content-Type application/rss+xml*
  	header Content-Type application/truetype*
  	header Content-Type application/ttf*
  	header Content-Type application/vnd.api+json*
  	header Content-Type application/vnd.ms-fontobject*
  	header Content-Type application/wasm*
  	header Content-Type application/x-httpd-cgi*
  	header Content-Type application/x-javascript*
  	header Content-Type application/x-opentype*
  	header Content-Type application/x-otf*
  	header Content-Type application/x-perl*
  	header Content-Type application/x-protobuf*
  	header Content-Type application/x-ttf*
  	header Content-Type application/xhtml+xml*
  	header Content-Type application/xml*
  	header Content-Type font/*
  	header Content-Type image/svg+xml*
  	header Content-Type image/vnd.microsoft.icon*
  	header Content-Type image/x-icon*
  	header Content-Type multipart/bag*
  	header Content-Type multipart/mixed*
  	header Content-Type text/*
  }
  

Responses that already have a Content-Encoding, or whose Cache-Control header contains no-transform, are not encoded. A no-transform directive in the request is ignored, since it is addressed to intermediaries. Prior to v2.11.8, it disabled encoding too. To restore that, use a matcher: @transformable not header Cache-Control *no-transform* then encode @transformable.

Responses that are eligible for encoding always get Vary: Accept-Encoding, even when sent uncompressed because the client doesn't accept any enabled encoding, so that shared caches store the variants separately.

Encoded responses have no Content-Length or Accept-Ranges, so clients can't make range requests for them. A strong ETag gets the encoding appended (e.g. "abc" becomes "abc-gzip"), so each encoding has a distinct tag; the suffix is stripped from If-None-Match before the request is passed on, so conditional requests still work.

Examples

Enable Gzip compression:

encode gzip

Enable Zstandard and Gzip compression (with Zstandard implicitly preferred, since it is first):

encode zstd gzip

As this is the default value, the previous configuration is strictly equivalent to:

encode

And in a full site, compressing static files served by file_server:

example.com {
	root /srv
	encode
	file_server
}