trustlesshttp

Documentation

Overview

Package trustlesshttp provides a set of simple utilities and constants useful for clients and servers implementing the IPFS Trustless Gateway protocol.

Index

• Constants
• Variables
• func ParseByteRange(req *http.Request) (*trustlessutils.ByteRange, error)
• func ParseFilename(req *http.Request) (string, error)
• func ParseScope(req *http.Request) (trustlessutils.DagScope, error)
• func ParseUrlPath(urlPath string) (cid.Cid, datamodel.Path, error)
• func RequestAcceptHeader(duplicates bool) string
• func ResponseContentTypeHeader(duplicates bool) string
• type ContentType
  • func CheckFormat(req *http.Request) ([]ContentType, error)
  • func DefaultContentType() ContentType
  • func ParseAccept(acceptHeader string) []ContentType
  • func ParseContentType(contentTypeHeader string) (ContentType, bool)
  • func (ct ContentType) IsCar() bool
  • func (ct ContentType) IsRaw() bool
  • func (ct ContentType) String() string
  • func (ct ContentType) WithDuplicates(duplicates bool) ContentType
  • func (ct ContentType) WithMimeType(mime string) ContentType
  • func (ct ContentType) WithOrder(order ContentTypeOrder) ContentType
  • func (ct ContentType) WithQuality(quality float32) ContentType
• type ContentTypeOrder

Constants

const (
	MimeTypeCar                = "application/vnd.ipld.car"            // One of two acceptable MIME types
	MimeTypeRaw                = "application/vnd.ipld.raw"            // One of two acceptable MIME types
	MimeTypeCarVersion         = "1"                                   // We only accept version 1 of the CAR MIME type
	FormatParameterCar         = "car"                                 // One of two acceptable format parameter values
	FormatParameterRaw         = "raw"                                 // One of two acceptable format parameter values
	FilenameExtCar             = ".car"                                // The only valid filename extension
	ResponseCacheControlHeader = "public, max-age=29030400, immutable" // Magic cache control values
	DefaultIncludeDupes        = true                                  // The default value for an unspecified "dups" parameter.
	DefaultOrder               = ContentTypeOrderDfs                   // The default value for an unspecified "order" parameter.

	ContentTypeOrderDfs ContentTypeOrder = "dfs"
	ContentTypeOrderUnk ContentTypeOrder = "unk"
)

Variables

var (
	ErrPathNotFound = errors.New("not found")
	ErrBadCid       = errors.New("failed to parse root CID")
)

var (
	ResponseChunkDelimeter = []byte("0\r\n") // An http/1.1 chunk delimeter, used for specifying an early end to the response
)

Functions

func ParseByteRange

func ParseByteRange(req *http.Request) (*trustlessutils.ByteRange, error)

ParseByteRange returns the entity-bytes query parameter if one is set in the query string or nil if one is not set. An error is returned if an entity-bytes query string is not a valid byte range.

func ParseFilename

func ParseFilename(req *http.Request) (string, error)

ParseFilename returns the filename query parameter or an error if the filename extension is not ".car". Lassie only supports returning CAR data. See https://specs.ipfs.tech/http-gateways/path-gateway/#filename-request-query-parameter

func ParseScope

func ParseScope(req *http.Request) (trustlessutils.DagScope, error)

ParseScope returns the dag-scope query parameter or an error if the dag-scope parameter is not one of the supported values.

func ParseUrlPath

func ParseUrlPath(urlPath string) (cid.Cid, datamodel.Path, error)

ParseUrlPath parses an incoming IPFS Trustless Gateway path of the form /ipfs/<cid>[/<path>] and returns the root CID and the path.

func RequestAcceptHeader

func RequestAcceptHeader(duplicates bool) string

RequestAcceptHeader returns the value for the Accept header for a Trustless Gateway request which will vary depending on whether duplicates are included or not. Otherwise, the header is the same for all requests.

Deprecated: Use DefaultContentType().WithDuplicates(duplicates).String() instead.

func ResponseContentTypeHeader

func ResponseContentTypeHeader(duplicates bool) string

ResponseContentTypeHeader returns the value for the Content-Type header for a Trustless Gateway response which will vary depending on whether duplicates are included or not. Otherwise, the header is the same for all responses.

Deprecated: Use DefaultContentType().WithDuplicates(duplicates).String() instead.

Types

type ContentType

type ContentType struct {
	MimeType   string
	Order      ContentTypeOrder
	Duplicates bool
	Quality    float32
}

ContentType represents a Content-Type descriptor for use with the response Content-Type header or the request Accept header specifically for Trustless Gateway requests and responses.

func CheckFormat

func CheckFormat(req *http.Request) ([]ContentType, error)

CheckFormat validates that the data being requested is of a compatible content type. If the request is valid, a slice of ContentType descriptors is returned, in preference order. If the request is invalid, an error is returned.

We do this validation because the IPFS Path Gateway spec allows for additional response formats that the IPFS Trustless Gateway spec does not currently support, so we throw an error in the cases where the request is requesting one the unsupported response formats. IPFS Trustless Gateway only supports returning CAR, or raw block data.

The spec outlines that the requesting format can be provided via the Accept header or the format query parameter.

IPFS Trustless Gateway only allows the application/vnd.ipld.car and application/vnd.ipld.raw Accept headers https://specs.ipfs.tech/http-gateways/path-gateway/#accept-request-header

IPFS Trustless Gateway only allows the "car" and "raw" format query parameters https://specs.ipfs.tech/http-gateways/path-gateway/#format-request-query-parameter

func DefaultContentType

func DefaultContentType() ContentType

func ParseAccept

func ParseAccept(acceptHeader string) []ContentType

ParseAccept validates a request Accept header and returns whether or not duplicate blocks are allowed in the response.

This will operate the same as ParseContentType except that it is less strict with the format specifier, allowing for "application/*" and "*/*" as well as the standard "application/vnd.ipld.car" and "application/vnd.ipld.raw".

func ParseContentType

func ParseContentType(contentTypeHeader string) (ContentType, bool)

ParseContentType validates a response Content-Type header and returns a ContentType descriptor form and a boolean to indicate whether or not the header value was valid or not.

This will operate similar to ParseAccept except that it strictly only allows the "application/vnd.ipld.car" and "application/vnd.ipld.raw" Content-Types (and it won't accept comma separated list of content types).

func (ContentType) IsCar

func (ct ContentType) IsCar() bool

func (ContentType) IsRaw

func (ct ContentType) IsRaw() bool

func (ContentType) String

func (ct ContentType) String() string

func (ContentType) WithDuplicates

func (ct ContentType) WithDuplicates(duplicates bool) ContentType

WithDuplicates returns a new ContentType with the specified duplicates.

func (ContentType) WithMimeType

func (ct ContentType) WithMimeType(mime string) ContentType

WithMime returns a new ContentType with the specified mime type.

func (ContentType) WithOrder

func (ct ContentType) WithOrder(order ContentTypeOrder) ContentType

WithOrder returns a new ContentType with the specified order.

func (ContentType) WithQuality

func (ct ContentType) WithQuality(quality float32) ContentType

WithQuality returns a new ContentType with the specified quality.

type ContentTypeOrder

type ContentTypeOrder string