DNSLink Gateway Specification

status: reliable
History
Commit History
Feedback
GitHub ipfs/specs (inspect source, open issue)

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

[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

B. Acknowledgments

We gratefully acknowledge the following individuals for their valuable contributions, ranging from minor suggestions to major insights, which have shaped and improved this specification.

Editors
Marcin Rataj (Protocol Labs) GitHub
Thibault Meunier (Cloudflare) GitHub
5
  1. No bibliographic reference for key "path-gateway".
  2. No bibliographic reference for key "path-gateway".
  3. No bibliographic reference for key "path-gateway".
  4. No bibliographic reference for key "path-gateway".
  5. No bibliographic reference for key "web-redirects-file".