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) stringdeprecated
- func ResponseContentTypeHeader(duplicates bool) stringdeprecated
- type ContentType
- 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 ¶
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 ¶
ParseUrlPath parses an incoming IPFS Trustless Gateway path of the form /ipfs/<cid>[/<path>] and returns the root CID and the path.
func RequestAcceptHeader
deprecated
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
deprecated
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 ¶ added in v0.2.0
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 ¶ added in v0.2.0
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 ¶ added in v0.4.0
func (ct ContentType) IsCar() bool
func (ContentType) IsRaw ¶ added in v0.4.0
func (ct ContentType) IsRaw() bool
func (ContentType) String ¶ added in v0.2.0
func (ct ContentType) String() string
func (ContentType) WithDuplicates ¶ added in v0.2.0
func (ct ContentType) WithDuplicates(duplicates bool) ContentType
WithDuplicates returns a new ContentType with the specified duplicates.
func (ContentType) WithMimeType ¶ added in v0.2.0
func (ct ContentType) WithMimeType(mime string) ContentType
WithMime returns a new ContentType with the specified mime type.
func (ContentType) WithOrder ¶ added in v0.2.0
func (ct ContentType) WithOrder(order ContentTypeOrder) ContentType
WithOrder returns a new ContentType with the specified order.
func (ContentType) WithQuality ¶ added in v0.2.0
func (ct ContentType) WithQuality(quality float32) ContentType
WithQuality returns a new ContentType with the specified quality.
type ContentTypeOrder ¶ added in v0.2.0
type ContentTypeOrder string
Source Files