gateway

README

IPFS Gateway

A reference implementation of HTTP Gateway Specifications.

Documentation

• Go Documentation: https://pkg.go.dev/github.com/ipfs/go-libipfs/gateway
• Gateway Specification: https://github.com/ipfs/specs/tree/main/http-gateways#readme
• Types of HTTP Gateways: https://docs.ipfs.tech/how-to/address-ipfs-on-web/#http-gateways

Example

// Initialize your headers and apply the default headers.
headers := map[string][]string{}
gateway.AddAccessControlHeaders(headers)

conf := gateway.Config{
  Headers:  headers,
}

// Initialize a NodeAPI interface for both an online and offline versions.
// The offline version should not make any network request for missing content.
ipfs := ...

// Create http mux and setup path gateway handler.
mux := http.NewServeMux()
gwHandler := gateway.NewHandler(conf, ipfs)
mux.Handle("/ipfs/", gwHandler)
mux.Handle("/ipns/", gwHandler)

// Start the server on :8080 and voilá! You have a basic IPFS gateway running
// in http://localhost:8080.
_ = http.ListenAndServe(":8080", mux)

Documentation

Index

• func AddAccessControlHeaders(headers map[string][]string)
• func NewHandler(c Config, api API) http.Handler
• func ServeContent(w http.ResponseWriter, req *http.Request, name string, modtime time.Time, ...) (int, bool, error)
• func WithHostname(next http.Handler, api API, publicGateways map[string]*Specification, ...) http.HandlerFunc
• type API
• type Config
• type RequestContextKey
• type Specification

Functions

func AddAccessControlHeaders

func AddAccessControlHeaders(headers map[string][]string)

AddAccessControlHeaders adds default headers used for controlling cross-origin requests. This function adds several values to the Access-Control-Allow-Headers and Access-Control-Expose-Headers entries. If the Access-Control-Allow-Origin entry is missing a value of '*' is added, indicating that browsers should allow requesting code from any origin to access the resource. If the Access-Control-Allow-Methods entry is missing a value of 'GET' is added, indicating that browsers may use the GET method when issuing cross origin requests.

func NewHandler

func NewHandler(c Config, api API) http.Handler

NewHandler returns an http.Handler that can act as a gateway to IPFS content offlineApi is a version of the API that should not make network requests for missing data

func ServeContent

func ServeContent(w http.ResponseWriter, req *http.Request, name string, modtime time.Time, content io.ReadSeeker) (int, bool, error)

ServeContent replies to the request using the content in the provided ReadSeeker and returns the status code written and any error encountered during a write. It wraps http.ServeContent which takes care of If-None-Match+Etag, Content-Length and range requests.

func WithHostname

func WithHostname(next http.Handler, api API, publicGateways map[string]*Specification, noDNSLink bool) http.HandlerFunc

WithHostname is a middleware that can wrap an http.Handler in order to parse the Host header and translating it to the content path. This is useful for Subdomain and DNSLink gateways.

publicGateways configures the behavior of known public gateways. Each key is a fully qualified domain name (FQDN).

noDNSLink configures the gateway to _not_ perform DNS TXT record lookups in response to requests with values in `Host` HTTP header. This flag can be overridden per FQDN in publicGateways.

Types

type API

type API interface {
	// GetUnixFsNode returns a read-only handle to a file tree referenced by a path.
	GetUnixFsNode(context.Context, path.Resolved) (files.Node, error)

	// LsUnixFsDir returns the list of links in a directory.
	LsUnixFsDir(context.Context, path.Resolved) (<-chan iface.DirEntry, error)

	// GetBlock return a block from a certain CID.
	GetBlock(context.Context, cid.Cid) (blocks.Block, error)

	// GetIPNSRecord retrieves the best IPNS record for a given CID (libp2p-key)
	// from the routing system.
	GetIPNSRecord(context.Context, cid.Cid) ([]byte, error)

	// GetDNSLinkRecord returns the DNSLink TXT record for the provided FQDN.
	// Unlike ResolvePath, it does not perform recursive resolution. It only
	// checks for the existence of a DNSLink TXT record with path starting with
	// /ipfs/ or /ipns/ and returns the path as-is.
	GetDNSLinkRecord(context.Context, string) (path.Path, error)

	// IsCached returns whether or not the path exists locally.
	IsCached(context.Context, path.Path) bool

	// ResolvePath resolves the path using UnixFS resolver. If the path does not
	// exist due to a missing link, it should return an error of type:
	// https://pkg.go.dev/github.com/ipfs/go-path@v0.3.0/resolver#ErrNoLink
	ResolvePath(context.Context, path.Path) (path.Resolved, error)
}

API defines the minimal set of API services required for a gateway handler.

type Config

type Config struct {
	Headers map[string][]string
}

Config is the configuration used when creating a new gateway handler.

type RequestContextKey

type RequestContextKey string

const (
	DNSLinkHostnameKey RequestContextKey = "dnslink-hostname"
	GatewayHostnameKey RequestContextKey = "gw-hostname"
)

type Specification

type Specification struct {
	// Paths is explicit list of path prefixes that should be handled by
	// this gateway. Example: `["/ipfs", "/ipns"]`
	// Useful if you only want to support immutable `/ipfs`.
	Paths []string

	// UseSubdomains indicates whether or not this gateway uses subdomains
	// for IPFS resources instead of paths. That is: http://CID.ipfs.GATEWAY/...
	//
	// If this flag is set, any /ipns/$id and/or /ipfs/$id paths in Paths
	// will be permanently redirected to http://$id.[ipns|ipfs].$gateway/.
	//
	// We do not support using both paths and subdomains for a single domain
	// for security reasons (Origin isolation).
	UseSubdomains bool

	// NoDNSLink configures this gateway to _not_ resolve DNSLink for the
	// specific FQDN provided in `Host` HTTP header. Useful when you want to
	// explicitly allow or refuse hosting a single hostname. To refuse all
	// DNSLinks in `Host` processing, pass noDNSLink to `WithHostname` instead.
	// This flag overrides the global one.
	NoDNSLink bool

	// InlineDNSLink configures this gateway to always inline DNSLink names
	// (FQDN) into a single DNS label in order to interop with wildcard TLS certs
	// and Origin per CID isolation provided by rules like https://publicsuffix.org
	// This should be set to true if you use HTTPS.
	InlineDNSLink bool
}

Specification is the specification of an IPFS Public Gateway.