trustlessutils

package module
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Oct 14, 2025 License: Apache-2.0, MIT Imports: 12 Imported by: 12

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

Constants

This section is empty.

Variables

This section is empty.

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(order string) string

Etag produces a weak Etag suitable for use as an Etag HTTP response header. The order parameter should match the CAR order parameter from the ContentType.

A weak Etag is used because:

  • Different implementations may include different parameters in the hash
  • Streaming gateways cannot include resolved path segments (only root+path)
  • For non-static backends (such as Filecoin storage providers), DAG availability may change over time as new deals are added

func (Request) IpfsRoots added in v0.6.0 

func (r Request) IpfsRoots() string

IpfsRoots returns the CID or CIDs that should be included in the X-Ipfs-Roots response header. For streaming-first gateways that don't pre-resolve paths, this returns just the root CID for simple requests (no path), and an empty string for path requests since intermediate CIDs are not known ahead of time.

Implementations that are able to resolve the full path ahead of time may return a comma-separated list of all CIDs in the path and not use this method.

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.

Source Files

View all Source files

Directories

Path Synopsis
Package trustlesshttp provides a set of simple utilities and constants useful for clients and servers implementing the IPFS Trustless Gateway protocol.
 Package trustlesshttp provides a set of simple utilities and constants useful for clients and servers implementing the IPFS Trustless Gateway protocol.
Package testutil is a fork of some components of github.com/ipfs/go-graphsync/testutil in order to avoid networking dependencies imposed by Graphsync.
 Package testutil is a fork of some components of github.com/ipfs/go-graphsync/testutil in order to avoid networking dependencies imposed by Graphsync.
chaintypes
Package chaintypes is a fork of some components of github.com/ipfs/go-graphsync/testutil/chaintypes in order to avoid networking dependencies imposed by Graphsync.
 Package chaintypes is a fork of some components of github.com/ipfs/go-graphsync/testutil/chaintypes in order to avoid networking dependencies imposed by Graphsync.
Package traversal provides utilities that operate above the github.com/ipld/go-ipld-prime/traversal system to perform the kinds of traversals required by the IPFS Trustless Gateway protocol, which requires only limited subset of the full go-ipld-prime traversal system.
 Package traversal provides utilities that operate above the github.com/ipld/go-ipld-prime/traversal system to perform the kinds of traversals required by the IPFS Trustless Gateway protocol, which requires only limited subset of the full go-ipld-prime traversal system.
internal/testutil

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.