Skip to content

/routing/v1: add missing HTTP cache headers #466

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lidel merged 4 commits into from
Mar 22, 2024
Merged

/routing/v1: add missing HTTP cache headers #466

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
db6d950
routing: add missing response headers
hacdias Mar 7, 2024
d4eb5d5
Apply suggestions from code review
lidel Mar 18, 2024
415158f
chore: editorial clarifications
lidel Mar 22, 2024
814166d
define HTTP-date timestamp
lidel Mar 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 29 additions & 2 deletions src/routing/http-routing-v1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ description: >
Delegated routing is a mechanism for IPFS implementations to use for offloading
content routing, peer routing and naming to another process/server. This specification describes
an HTTP API for delegated routing of content, peers, and IPNS.
date: 2023-08-31
date: 2024-03-22
maturity: reliable
editors:
- name: Gus Eggert
Expand Down Expand Up @@ -71,6 +71,17 @@ This API uses a standard version prefix in the path, such as `/v1/...`. If a bac
- `404` (Not Found): must be returned if no matching records are found.
- `422` (Unprocessable Entity): request does not conform to schema or semantic constraints.

#### Response Headers

- `Content-Type`: the content type of this response, which MUST be `application/json` or `application/x-ndjson` (see [streaming](#streaming)).
- `Last-Modified`: an HTTP-date timestamp ([RFC9110, Section 5.6.7](https://www.rfc-editor.org/rfc/rfc9110#section-5.6.7)) of the resolution, allowing HTTP proxies and CDNs to support inexpensive update checks via `If-Modified-Since`
- `Cache-Control: public, max-age={ttl}, public, stale-while-revalidate={max-ttl}, stale-if-error={max-ttl}`: meaningful cache TTL returned with the response.
- The `max-age` SHOULD be shorter for responses whose resolution ended in no results (e.g. 15 seconds),
and longer for responses that have results (e.g. 5 minutes).
- Implementations SHOULD include `max-ttl`, set to the maximum cache window of the underlying routing system.
For example, if Amino DHT results are returned, `stale-while-revalidate` SHOULD be set to `172800` (48h, which at the time of writing this specification, is the provider record expiration window).
- `Vary: Accept`: allows intermediate caches to play nicely with the different possible content types.

#### Response Body

```json
Expand Down Expand Up @@ -108,6 +119,17 @@ represented as a CIDv1 encoded with `libp2p-key` codec.
- `404` (Not Found): must be returned if no matching records are found.
- `422` (Unprocessable Entity): request does not conform to schema or semantic constraints.

#### Response Headers

- `Content-Type`: the content type of this response, which MUST be `application/json` or `application/x-ndjson` (see [streaming](#streaming)).
- `Last-Modified`: an HTTP-date timestamp ([RFC9110, Section 5.6.7](https://www.rfc-editor.org/rfc/rfc9110#section-5.6.7)) of the resolution, allowing HTTP proxies and CDNs to support inexpensive update checks via `If-Modified-Since`
- `Cache-Control: public, max-age={ttl}, public, stale-while-revalidate={max-ttl}, stale-if-error={max-ttl}`: meaningful cache TTL returned with the response.
- When present, `ttl` SHOULD be shorter for responses whose resolution ended in no results (e.g. 15 seconds),
and longer for responses that have results (e.g. 5 minutes).
- Implementations SHOULD include `max-ttl`, set to the maximum cache window of the underlying routing system.
For example, if Amino DHT results are returned, `stale-while-revalidate` SHOULD be set to `172800` (48h, which at the time of writing this specification, is the provider record expiration window).
- `Vary: Accept`: allows intermediate caches to play nicely with the different possible content types.

#### Response Body

```json
Expand Down Expand Up @@ -148,7 +170,12 @@ Each object in the `Peers` list is a record conforming to the [Peer Schema](#pee
#### Response Headers

- `Etag`: a globally unique opaque string used for HTTP caching. MUST be derived from the protobuf record returned in the body.
- `Cache-Control: max-age={TTL}`: cache TTL returned with :ref[IPNS Record] that has `IpnsEntry.data[TTL] > 0`. When present, SHOULD match the TTL value from the record. When record was not found (HTTP 404) or has no TTL (value is `0`), implementation SHOULD default to `max-age=60`.
- `Cache-Control: public, max-age={ttl}, public, stale-while-revalidate={sig-ttl}, stale-if-error={sig-ttl}`: meaningful cache TTL returned with :ref[IPNS Record]
- The `max-age` value in seconds SHOULD match duration from `IpnsEntry.data[TTL]`, if present and bigger than `0`. Otherwise, implementation SHOULD default to `max-age=60`.
- Implementations SHOULD include `sig-ttl`, set to the remaining number of seconds the returned IPNS Record is valid.
- `Expires:`: an HTTP-date timestamp ([RFC9110, Section 5.6.7](https://www.rfc-editor.org/rfc/rfc9110#section-5.6.7)) when the validity of IPNS Record expires (if `ValidityType=0`, when signature expires)
- `Last-Modified`: an HTTP-date timestamp of when cacheable resolution occured: allows HTTP proxies and CDNs to support inexpensive update checks via `If-Modified-Since`
- `Vary: Accept`: allows intermediate caches to play nicely with the different possible content types.

#### Response Body

Expand Down