gateway

package
v0.0.0-...-c0cc0bc Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 30, 2024 License: Apache-2.0, MIT Imports: 70 Imported by: 0

README

IPFS Gateway

A reference implementation of HTTP Gateway Specifications.

Documentation

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

Constants

This section is empty.

Variables

View Source 
var (
	ErrInternalServerError = NewErrorResponseForCode(http.StatusInternalServerError)
	ErrGatewayTimeout      = NewErrorResponseForCode(http.StatusGatewayTimeout)
	ErrBadGateway          = NewErrorResponseForCode(http.StatusBadGateway)
	ErrServiceUnavailable  = NewErrorResponseForCode(http.StatusServiceUnavailable)
	ErrTooManyRequests     = NewErrorResponseForCode(http.StatusTooManyRequests)
)

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 NewDNSResolver 

func NewDNSResolver(resolvers map[string]string, dohOpts ...doh.Option) (*madns.Resolver, error)

NewDNSResolver creates a new DNS resolver based on the default resolvers and the provided resolvers.

The argument 'resolvers' is a map of FQDNs to URLs for custom DNS resolution. URLs starting with `https://` indicate DoH endpoints. Support for other resolver types may be added in the future. 

https://en.wikipedia.org/wiki/Fully_qualified_domain_name
https://en.wikipedia.org/wiki/DNS_over_HTTPS

Example: - Custom resolver for ENS: `eth.` → `https://eth.link/dns-query` - Override the default OS resolver: `.` → `https://doh.applied-privacy.net/query`

func NewHandler 

func NewHandler(c Config, api IPFSBackend) 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 IPFSBackend, 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 BlockGatewayOption 

type BlockGatewayOption func(gwOptions *gwOptions) error

func WithNameSystem 

func WithNameSystem(ns namesys.NameSystem) BlockGatewayOption

WithNameSystem sets the name system to use for the gateway. If not set it will use a default DNSLink resolver along with any configured ValueStore

func WithValueStore 

func WithValueStore(vs routing.ValueStore) BlockGatewayOption

WithValueStore sets the ValueStore to use for the gateway

type BlocksGateway 

type BlocksGateway struct {
	// contains filtered or unexported fields
}

func NewBlocksGateway 

func NewBlocksGateway(blockService blockservice.BlockService, opts ...BlockGatewayOption) (*BlocksGateway, error)

func (*BlocksGateway) Get 

func (api *BlocksGateway) Get(ctx context.Context, path ImmutablePath, ranges ...ByteRange) (ContentPathMetadata, *GetResponse, error)

func (*BlocksGateway) GetAll 

func (api *BlocksGateway) GetAll(ctx context.Context, path ImmutablePath) (ContentPathMetadata, files.Node, error)

func (*BlocksGateway) GetBlock 

func (api *BlocksGateway) GetBlock(ctx context.Context, path ImmutablePath) (ContentPathMetadata, files.File, error)

func (*BlocksGateway) GetCAR 

func (api *BlocksGateway) GetCAR(ctx context.Context, path ImmutablePath) (ContentPathMetadata, io.ReadCloser, <-chan error, error)

func (*BlocksGateway) GetDNSLinkRecord 

func (api *BlocksGateway) GetDNSLinkRecord(ctx context.Context, hostname string) (ifacepath.Path, error)

func (*BlocksGateway) GetIPNSRecord 

func (api *BlocksGateway) GetIPNSRecord(ctx context.Context, c cid.Cid) ([]byte, error)

func (*BlocksGateway) Head 

func (api *BlocksGateway) Head(ctx context.Context, path ImmutablePath) (ContentPathMetadata, files.Node, error)

func (*BlocksGateway) IsCached 

func (api *BlocksGateway) IsCached(ctx context.Context, p ifacepath.Path) bool

func (*BlocksGateway) ResolveMutable 

func (api *BlocksGateway) ResolveMutable(ctx context.Context, p ifacepath.Path) (ImmutablePath, error)

func (*BlocksGateway) ResolvePath 

func (api *BlocksGateway) ResolvePath(ctx context.Context, path ImmutablePath) (ContentPathMetadata, error)

type ByteRange 

type ByteRange struct {
	From uint64
	To   *int64
}

ByteRange describes a range request within a UnixFS file. From and To mostly follow HTTP Byte Range Request semantics. From >= 0 and To = nil: Get the file (From, Length) From >= 0 and To >= 0: Get the range (From, To) From >= 0 and To <0: Get the range (From, Length - To)

type Config 

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

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

type ContentPathMetadata 

type ContentPathMetadata struct {
	PathSegmentRoots []cid.Cid
	LastSegment      path.Resolved
	ContentType      string // Only used for UnixFS requests
}

type ErrorResponse 

type ErrorResponse struct {
	StatusCode int
	Err        error
}

Custom type for collecting error details to be handled by `webError`. When an error of this type is returned to the gateway handler, the StatusCode will be used for the response status.

func NewErrorResponse 

func NewErrorResponse(err error, statusCode int) *ErrorResponse

func NewErrorResponseForCode 

func NewErrorResponseForCode(statusCode int) *ErrorResponse

func (*ErrorResponse) Error 

func (e *ErrorResponse) Error() string

func (*ErrorResponse) Is 

func (e *ErrorResponse) Is(err error) bool

func (*ErrorResponse) Unwrap 

func (e *ErrorResponse) Unwrap() error

type ErrorRetryAfter 

type ErrorRetryAfter struct {
	Err        error
	RetryAfter time.Duration
}

func NewErrorRetryAfter 

func NewErrorRetryAfter(err error, retryAfter time.Duration) *ErrorRetryAfter

NewErrorWithRetryAfter wraps any error in RetryAfter hint that gets passed to HTTP clients in Retry-After HTTP header.

func (*ErrorRetryAfter) Error 

func (e *ErrorRetryAfter) Error() string

func (*ErrorRetryAfter) HTTPHeaderValue 

func (e *ErrorRetryAfter) HTTPHeaderValue() string

HTTPHeaderValue returns the Retry-After header value as a string, representing the number of seconds to wait before making a new request, rounded to the nearest second. This function follows the Retry-After header definition as specified in RFC 9110.

func (*ErrorRetryAfter) Humanized 

func (e *ErrorRetryAfter) Humanized() string

func (*ErrorRetryAfter) Is 

func (e *ErrorRetryAfter) Is(err error) bool

func (*ErrorRetryAfter) RoundSeconds 

func (e *ErrorRetryAfter) RoundSeconds() time.Duration

func (*ErrorRetryAfter) Unwrap 

func (e *ErrorRetryAfter) Unwrap() error

type GetResponse 

type GetResponse struct {
	// contains filtered or unexported fields
}

func NewGetResponseFromDirectoryListing 

func NewGetResponseFromDirectoryListing(dagSize uint64, entries <-chan unixfs.LinkResult) *GetResponse

func NewGetResponseFromFile 

func NewGetResponseFromFile(file files.File) *GetResponse

type IPFSBackend 

type IPFSBackend interface {

	// Get returns a GetResponse with UnixFS file, directory or a block in IPLD
	// format e.g., (DAG-)CBOR/JSON.
	//
	// Returned Directories are preferably a minimum info required for enumeration: Name, Size, and Cid.
	//
	// Optional ranges follow [HTTP Byte Ranges] notation and can be used for
	// pre-fetching specific sections of a file or a block.
	//
	// Range notes:
	//   - Generating response to a range request may require additional data
	//     beyond the passed ranges (e.g. a single byte range from the middle of a
	//     file will still need magic bytes from the very beginning for content
	//     type sniffing).
	//   - A range request for a directory currently holds no semantic meaning.
	//
	// [HTTP Byte Ranges]: https://httpwg.org/specs/rfc9110.html#rfc.section.14.1.2
	Get(context.Context, ImmutablePath, ...ByteRange) (ContentPathMetadata, *GetResponse, error)

	// GetAll returns a UnixFS file or directory depending on what the path is that has been requested. Directories should
	// include all content recursively.
	GetAll(context.Context, ImmutablePath) (ContentPathMetadata, files.Node, error)

	// GetBlock returns a single block of data
	GetBlock(context.Context, ImmutablePath) (ContentPathMetadata, files.File, error)

	// Head returns a file or directory depending on what the path is that has been requested.
	// For UnixFS files should return a file which has the correct file size and either returns the ContentType in ContentPathMetadata or
	// enough data (e.g. 3kiB) such that the content type can be determined by sniffing.
	// For all other data types returning just size information is sufficient
	// TODO: give function more explicit return types
	Head(context.Context, ImmutablePath) (ContentPathMetadata, files.Node, error)

	// 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:
	// NewErrorResponse(fmt.Errorf("no link named %q under %s", name, cid), http.StatusNotFound)
	ResolvePath(context.Context, ImmutablePath) (ContentPathMetadata, error)

	// GetCAR returns a CAR file for the given immutable path
	// Returns an initial error if there was an issue before the CAR streaming begins as well as a channel with a single
	// that may contain a single error for if any errors occur during the streaming. If there was an initial error the
	// error channel is nil
	// TODO: Make this function signature better
	GetCAR(context.Context, ImmutablePath) (ContentPathMetadata, io.ReadCloser, <-chan error, error)

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

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

	// ResolveMutable takes a mutable path and resolves it into an immutable one. This means recursively resolving any
	// DNSLink or IPNS records.
	//
	// For example, given a mapping from `/ipns/dnslink.tld -> /ipns/ipns-id/mydirectory` and `/ipns/ipns-id` to
	// `/ipfs/some-cid`, the result of passing `/ipns/dnslink.tld/myfile` would be `/ipfs/some-cid/mydirectory/myfile`.
	ResolveMutable(context.Context, path.Path) (ImmutablePath, 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)
}

IPFSBackend is the required set of functionality used to implement the IPFS HTTP Gateway specification. To signal error types to the gateway code (so that not everything is a HTTP 500) return an error wrapped with NewErrorResponse. There are also some existing error types that the gateway code knows how to handle (e.g. context.DeadlineExceeded and various IPLD pathing related errors).

type ImmutablePath 

type ImmutablePath struct {
	// contains filtered or unexported fields
}

TODO: Is this what we want for ImmutablePath?

func NewImmutablePath 

func NewImmutablePath(p path.Path) (ImmutablePath, error)

func (ImmutablePath) IsValid 

func (i ImmutablePath) IsValid() error

func (ImmutablePath) Mutable 

func (i ImmutablePath) Mutable() bool

func (ImmutablePath) Namespace 

func (i ImmutablePath) Namespace() string

func (ImmutablePath) String 

func (i ImmutablePath) String() string

type RequestContextKey 

type RequestContextKey string
const (
	DNSLinkHostnameKey RequestContextKey = "dnslink-hostname"
	GatewayHostnameKey RequestContextKey = "gw-hostname"
	ContentPathKey     RequestContextKey = "content-path"
)

type Specification 

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

	// UseSubdomains indicates whether or not this gateway uses subdomains
	// for btfs resources instead of paths. That is: http://CID.btfs.GATEWAY/...
	//
	// If this flag is set, any /btns/$id and/or /btfs/$id paths in Paths
	// will be permanently redirected to http://$id.[btns|btfs].$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 btfs Public Gateway.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.