diff --git a/src/http-gateways/path-gateway.md b/src/http-gateways/path-gateway.md index 5088728c..e61aa944 100644 --- a/src/http-gateways/path-gateway.md +++ b/src/http-gateways/path-gateway.md @@ -113,7 +113,7 @@ All request headers are optional. ### `If-None-Match` (request header) -Used for HTTP caching. +Optional, used for HTTP caching. Enables advanced cache control based on `Etag`, allowing client and server to skip data transfer if previously downloaded @@ -123,6 +123,22 @@ The Gateway MUST compare Etag values sent in `If-None-Match` with `Etag` that would be sent with response. Positive match MUST return HTTP status code 304 (Not Modified), without any payload. +### `If-Modified-Since` (request header) + +Optional, used for HTTP caching of mutable resources. + +Enables advanced cache control based on `Last-Modified`, +allowing client and server to skip data transfer if previously downloaded +payload did not change. + +The Gateway SHOULD compare HTTP-date value sent in `If-Modified-Since` with `Last-Modified` that +would be sent with response. Positive match MUST return HTTP status code 304 +(Not Modified), without any payload. + +While `Last-Modified` SHOULD be implemented by the gateway itself, +implementation and handling of this header MAY be delegated to a third-party +HTTP software such as CDN, reverse proxy, or load-balancer. + ### `Cache-Control` (request header) Used for HTTP caching. @@ -272,6 +288,12 @@ Indicates permanent redirection. The new, canonical URL is returned in the [`Location`](#location-response-header) header. +### `304` Not Modified + +Indicates indicates that there is no need to retransmit the requested resources. + +See: [`Last-Modified`](#last-modified-response-header). + ### `400` Bad Request A generic client error returned when it is not possible to return a better one @@ -397,33 +419,23 @@ Returned directive depends on requested content path and format: TXT record. - Implementations MAY place an upper bound on any TTL received, as noted in Section 8 of :cite[rfc2181]. - - If TTL value is unknown, implementations SHOULD not send a `Cache-Control` - - No matter if TTL value is known or not, implementations SHOULD always - send a [`Last-Modified`](#last-modified-response-header) header with the timestamp of the record resolution. + - Implementations MAY also place an lower bound of 1 minute to avoid excessive lookups. + - If TTL value is unknown, implementations MAY not send a `Cache-Control` + but SHOULD send [`Last-Modified`](#last-modified-response-header) header. ### `Last-Modified` (response header) -Optional, used as additional hint for HTTP caching. - -Returning this header depends on the information available: - -- The header can be returned with `/ipns/` responses when the gateway - implementation knows the exact time a mutable pointer was updated by the - publisher. - -- When only TTL is known, [`Cache-Control`](#cache-control-response-header) - should be used instead. +Used for HTTP caching, SHOULD be returned with mutable responses. -- Legacy implementations set this header to the current timestamp when reading - TTL on `/ipns/` content paths was not available. This hint was used by web - browsers in a process called "Calculating Heuristic Freshness" - (Section 4.2.2 of :cite[rfc9111]). Each browser - uses different heuristic, making this an inferior, non-deterministic caching - strategy. +An HTTP-date timestamp ([RFC9110, Section +5.6.7](https://www.rfc-editor.org/rfc/rfc9110#section-5.6.7)) indicating when +the resolution of requested content path occured, allowing HTTP proxies and CDNs +to support inexpensive update checks via `If-Modified-Since`. -- New implementations should not return this header if TTL is not known; - providing a static expiration window in `Cache-Control` is easier to reason - about than cache expiration based on the fuzzy “heuristic freshness”. +When `Cache-Control` is not present, `Last-Modified` value also acts as a hint +for web browsers in a process called "Calculating Heuristic Freshness" +(Section 4.2.2 of :cite[rfc9111]). Each browser uses different heuristic, +making this an inferior, non-deterministic caching strategy. ### `Content-Type` (response header) diff --git a/src/http-gateways/trustless-gateway.md b/src/http-gateways/trustless-gateway.md index 71ae1f30..f8349050 100644 --- a/src/http-gateways/trustless-gateway.md +++ b/src/http-gateways/trustless-gateway.md @@ -65,6 +65,8 @@ Same as in :cite[path-gateway], but with limited number of supported response ty ## Request Headers +For HTTP Caching, follow `Cache-Control`, `If-Modified-Since`, and `If-None-Match` from :cite[path-gateway]. + ### `Accept` (request header) A Client SHOULD send this HTTP header to leverage content type negotiation @@ -189,6 +191,8 @@ Below MUST be implemented **in addition** to "HTTP Response" of :cite[path-gatew ## Response Headers +For HTTP Caching, follow `Cache-Control`, `Last-Modified`, and `Etag` from :cite[path-gateway]. + ### `Content-Type` (response header) MUST be returned and include additional format-specific parameters when possible.