3. The Alt-Svc HTTP Header Field
An HTTP(S) origin server can advertise the availability of alternative services to clients by adding an Alt-Svc header field to responses.
Alt-Svc = clear / 1#alt-value
clear = %s"clear"; "clear", case-sensitive
alt-value = alternative *( OWS ";" OWS parameter )
alternative = protocol-id "=" alt-authority
protocol-id = token ; percent-encoded ALPN protocol name
alt-authority = quoted-string ; containing [ uri-host ] ":" port
parameter = token "=" ( token / quoted-string )
The field value consists either of a list of values, each of which indicates one alternative service, or the keyword "clear".
A field value containing the special value "clear" indicates that the origin requests all alternatives for that origin to be invalidated (including those specified in the same response, in case of an invalid reply containing both "clear" and alternative services).
ALPN protocol names are octet sequences with no additional constraints on format. Octets not allowed in tokens ([RFC7230], Section 3.2.6) MUST be percent-encoded as per Section 2.1 of [RFC3986]. Consequently, the octet representing the percent character "%" (hex 25) MUST be percent-encoded as well.
In order to have precisely one way to represent any ALPN protocol name, the following additional constraints apply:
- Octets in the ALPN protocol name MUST NOT be percent-encoded if they are valid token characters except "%", and
- When using percent-encoding, uppercase hex digits MUST be used.
With these constraints, recipients can apply simple string comparison to match protocol identifiers.
The "alt-authority" component consists of an OPTIONAL uri-host ("host" in Section 3.2.2 of [RFC3986]), a colon (":"), and a port number.
For example:
Alt-Svc: h2=":8000"
This indicates the "h2" protocol ([RFC7540]) on the same host using the indicated port 8000.
An example involving a change of host:
Alt-Svc: h2="new.example.org:80"
This indicates the "h2" protocol on the host "new.example.org", running on port 80. Note that the "quoted-string" syntax needs to be used because ":" is not an allowed character in "token".
Examples for protocol name escaping:
| ALPN protocol name | protocol-id | Note |
|---|---|---|
| h2 | h2 | No escaping needed |
| w=x:y#z | w%3Dx%3Ay#z | "=" and ":" escaped |
| x%y | x%25y | "%" needs escaping |
Alt-Svc MAY occur in any HTTP response message, regardless of the status code. Note that recipients of Alt-Svc can ignore the header field (and are required to in some situations; see Sections 2.1 and 6).
The Alt-Svc field value can have multiple values:
Alt-Svc: h2="alt.example.com:8000", h2=":443"
When multiple values are present, the order of the values reflects the server's preference (with the first value being the most preferred alternative).
The value(s) advertised by Alt-Svc can be used by clients to open a new connection to an alternative service. Subsequent requests can start using this new connection immediately or can continue using the existing connection while the new connection is created.
When using HTTP/2 ([RFC7540]), servers SHOULD instead send an ALTSVC frame (Section 4). A single ALTSVC frame can be sent for a connection; a new frame is not needed for every request. Note that, despite this recommendation, Alt-Svc header fields remain valid in responses delivered over HTTP/2.
Each "alt-value" is followed by an OPTIONAL semicolon-separated list of additional parameters, each such "parameter" comprising a name and a value.
This specification defines two parameters: "ma" and "persist", defined in Section 3.1. Unknown parameters MUST be ignored. That is, the values (alt-value) they appear in MUST be processed as if the unknown parameter was not present.
New parameters can be defined in extension specifications (see Section 7.3 for registration details).
Note that all field elements that allow "quoted-string" syntax MUST be processed as per Section 3.2.6 of [RFC7230].
3.1. Caching Alt-Svc Header Field Values
When an alternative service is advertised using Alt-Svc, it is considered fresh for 24 hours from generation of the message. This can be modified with the "ma" (max-age) parameter.
Syntax:
ma = delta-seconds; see [RFC7234], Section 1.2.1
The delta-seconds value indicates the number of seconds since the response was generated for which the alternative service is considered fresh.
Alt-Svc: h2=":443"; ma=3600
See Section 4.2.3 of [RFC7234] for details on determining the response age.
For example, a response:
HTTP/1.1 200 OK
Content-Type: text/html
Cache-Control: max-age=600
Age: 30
Alt-Svc: h2=":8000"; ma=60
indicates that an alternative service is available and usable for the next 60 seconds. However, the response has already been cached for 30 seconds (as per the Age header field value); therefore, the alternative service is only fresh for the 30 seconds from when this response was received, minus estimated transit time.
Note that the freshness lifetime for HTTP caching (here, 600 seconds) does not affect caching of Alt-Svc values.
When an Alt-Svc response header field is received from an origin, its value invalidates and replaces all cached alternative services for that origin.
By default, cached alternative services will be cleared when the client detects a network change. Alternative services that are intended to be longer lived (such as those that are not specific to the client access network) can carry the "persist" parameter with a value "1" as a hint that the service is potentially useful beyond a network configuration change.
Syntax:
persist = "1"
For example:
Alt-Svc: h2=":443"; ma=2592000; persist=1
This specification only defines a single value for "persist". Clients MUST ignore "persist" parameters with values other than "1".
See Section 2.2 for general requirements on caching alternative services.