DNSLink Gateway Specification

status: reliable
Editors
Marcin Rataj (Protocol Labs) GitHub
Thibault Meunier (Cloudflare) GitHub
History
Commit History
Feedback
GitHub ipfs/specs (pull requests, new issue, open issues)

DNSLink Gateway is an extension of [path-gateway] that enables hosting a specific content path under a specific DNS name.

This document describes the delta between [path-gateway] and this gateway type.

In short:

1. HTTP API

1.1 GET /[{path}][?{params}]

Downloads data at specified path under the content path for DNSLink name provided in Host header.

1.2 HEAD /[{path}][?{params}]

Same as GET, but does not return any payload.

2. HTTP Request

Below MUST be implemented in addition to "HTTP Request" of [path-gateway].

2.1 Request headers

2.1.1 Host (request header)

Defines the DNSLink name to RECURSIVELY resolve into an immutable /ipfs/{cid}/ prefix that should be prepended to the path before the final IPFS content path resolution is performed.

Implementations MUST ensure DNSLink resolution is safe and correct:

  • each DNSLink may include an additional path segment, which MUST be preserved
  • each DNSLink may point at other DNSLink, which means there MUST be a hard recursion limit (e.g. 32) and HTTP 400 Bad Request error MUST be returned when the limit is reached.

Example: resolving an advanced DNSLink chain

To illustrate, given DNSLink records:

  • _dnslink.a.example.com TXT record: dnslink=/ipns/b.example.net/path-b
  • _dnslink.b.example.net TXT record: dnslink=/ipfs/bafy…qy3k/path-c

HTTP client sends GET /path-a request with Host: a.example.com header which recursively resolves all DNSLinks and produces the final immutable content path:

  1. Host header + /path-a/ipns/a.example.net/path-a
  2. Resolving DNSlink at a.example.net replaces /ipns/a.example.net with /ipns/b.example.net/path-b
  3. Resolving DNSlink at b.example.net replaces /ipns/b.example.net with /ipfs/bafy…qy3k/path-c
  4. The immutable content path is /ipfs/bafy…qy3k/path-c/path-b/path-a

3. HTTP Response

Same as "HTTP Response" of [path-gateway].

4. Appendix: notes for implementers

4.1 Leveraging DNS for content routing

4.2 Redirects, single-page applications, and custom 404s

DNSLink Gateway implementations SHOULD include _redirects file support defined in [web-redirects-file].

A. References

[path-gateway]
Path Gateway Specification. Marcin Rataj; Adrian Lanzafame; Vasco Santos; Oli Evans; Henrique Dias. 2023-03-30. URL: https://specs.ipfs.tech/http-gateways/path-gateway/
[rfc2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[web-redirects-file]
Web _redirects File Specification. Justin Johnson; Marcin Rataj. 2023-01-28. URL: https://specs.ipfs.tech/http-gateways/web-redirects-file/