trustlessutils

README

go-trustless-utils

Go(lang) utilities for the IPFS Trustless Gateway HTTP protocol

API

https://pkg.go.dev/github.com/ipld/go-trustless-utils

Examples

For example use see:

• Lassie - an IPFS retrieval client that supports the Trustless Gateway protocol for retrieval and also as a server when running in daemon mode.
• Frisbii - a minimal IPLD data provider (server) for the IPFS network using the Trustless Gateway protocol.

License

Apache-2.0/MIT © Protocol Labs

Documentation

Overview

go-trustless-utils is a set of utilities for working with the IPFS Trustless Gateway protocol as defined at

https://specs.ipfs.tech/http-gateways/trustless-gateway/

The utilities contained here should be useful for building server and client implementations of the protocol.

Index

• func PathEscape(path string) string
• type ByteRange
  • func ParseByteRange(s string) (ByteRange, error)
  • func (br *ByteRange) IsDefault() bool
  • func (br *ByteRange) String() string
• type DagScope
  • func ParseDagScope(s string) (DagScope, error)
  • func (ds DagScope) TerminalSelectorSpec() builder.SelectorSpec
• type Request
  • func (r Request) Etag() string
  • func (r Request) Selector() datamodel.Node
  • func (r Request) UrlPath() (string, error)

Functions

func PathEscape

func PathEscape(path string) string

PathEscape both cleans an IPLD path and URL escapes it so that it can be used in a URL path.

Types

type ByteRange

type ByteRange struct {
	From int64
	To   *int64 // To is a pointer to represent "*" as nil
}

ByteRange is used to represent the "entity-bytes" parameter of the IPFS Trustless Gateway protocol.

func ParseByteRange

func ParseByteRange(s string) (ByteRange, error)

ParseByteRange parses a string form of a ByteRange into a ByteRange. It can be used to parse an "entity-bytes" parameter from a URL.

func (*ByteRange) IsDefault

func (br *ByteRange) IsDefault() bool

IsDefault is roughly equivalent to the range matching [0:*]

func (*ByteRange) String

func (br *ByteRange) String() string

String will produce a string form of the ByteRange suitable for use in a URL and parsable by ParseByteRange.

type DagScope

type DagScope string

DagScope is used to represent the "dag-scope" parameter of the IPFS Trustless Gateway protocol.

const (
	DagScopeAll    DagScope = "all"
	DagScopeEntity DagScope = "entity"
	DagScopeBlock  DagScope = "block"
)

func ParseDagScope

func ParseDagScope(s string) (DagScope, error)

ParseDagScope parses a string form of a DagScope into a DagScope.

func (DagScope) TerminalSelectorSpec

func (ds DagScope) TerminalSelectorSpec() builder.SelectorSpec

TerminalSelectorSpec returns the IPLD selector spec that should be used for the terminal of the given DagScope.

type Request

type Request struct {
	// Root is the root CID to fetch.
	Root cid.Cid

	// Path is the optional path within the DAG to fetch.
	Path string

	// Scope describes the scope of the DAG to fetch. If the Selector parameter
	// is not set, Scope and Path will be used to construct a selector.
	Scope DagScope

	// Bytes is the optional byte range within the DAG to fetch. If not set
	// the default byte range will fetch the entire file.
	Bytes *ByteRange

	// Duplicates is a flag that indicates whether duplicate blocks should be
	// stored into the LinkSystem where they occur in the traversal.
	Duplicates bool
}

Request describes the parameters of an IPFS Trustless Gateway request. It is intended to be immutable.

func (Request) Etag

func (r Request) Etag() string

Etag produces a string suitable for use as an Etag in an HTTP response for this Request.

func (Request) Selector

func (r Request) Selector() datamodel.Node

Selector generates an IPLD selector for this Request.

Note that only Path, Scope and Bytes are used to generate a selector; so a construction such as the following may be used to easily generate a Trustless Gateway, UnixFS compatible selector:

Request{Path: path, Scope: scope, Bytes: byteRange}.Selector()

func (Request) UrlPath

func (r Request) UrlPath() (string, error)

UrlPath returns a URL path and query string valid with the Trusted HTTP Gateway spec by combining the Path and the Scope of this request.

The returned value includes a URL escaped form of the originally requested path.