Version: v0.10.0 Latest Latest

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

Go to latest
Published: Mar 7, 2019 License: Apache-2.0, MIT Imports: 34 Imported by: 0



Package rest implements an IPFS Cluster API component. It provides a REST-ish API to interact with Cluster.

rest exposes the HTTP API in two ways. The first is through a regular HTTP(s) listener. The second is by tunneling HTTP through a libp2p stream (thus getting an encrypted channel without the need to setup TLS). Both ways can be used at the same time, or disabled.



View Source
const (
	DefaultHTTPListenAddr    = "/ip4/"
	DefaultReadTimeout       = 0
	DefaultReadHeaderTimeout = 5 * time.Second
	DefaultWriteTimeout      = 0
	DefaultIdleTimeout       = 120 * time.Second

These are the default values for Config


View Source
var (
	DefaultCORSAllowedOrigins = []string{"*"}
	DefaultCORSAllowedMethods = []string{
	// rs/cors this will set sensible defaults when empty:
	// {"Origin", "Accept", "Content-Type", "X-Requested-With"}
	DefaultCORSAllowedHeaders = []string{}
	DefaultCORSExposedHeaders = []string{
	DefaultCORSAllowCredentials = true
	DefaultCORSMaxAge           time.Duration // 0. Means always.

CORS defaults

View Source
var (
	// ErrNoEndpointEnabled is returned when the API is created but
	// no HTTPListenAddr, nor libp2p configuration fields, nor a libp2p
	// Host are provided.
	ErrNoEndpointsEnabled = errors.New("neither the libp2p nor the HTTP endpoints are enabled")

	// ErrHTTPEndpointNotEnabled is returned when trying to perform
	// operations that rely on the HTTPEndpoint but it is disabled.
	ErrHTTPEndpointNotEnabled = errors.New("the HTTP endpoint is not enabled")

Common errors

View Source
var (
	DefaultHeaders = map[string][]string{}

These are the default values for Config.


This section is empty.


type API

type API struct {
	// contains filtered or unexported fields

API implements an API and aims to provides a RESTful HTTP API for Cluster.

func NewAPI

func NewAPI(ctx context.Context, cfg *Config) (*API, error)

NewAPI creates a new REST API component with the given configuration.

func NewAPIWithHost

func NewAPIWithHost(ctx context.Context, cfg *Config, h host.Host) (*API, error)

NewAPIWithHost creates a new REST API component and enables the libp2p-http endpoint using the given Host, if not nil.

func (*API) HTTPAddress

func (api *API) HTTPAddress() (string, error)

HTTPAddress returns the HTTP(s) listening address in host:port format. Useful when configured to start on a random port (0). Returns error when the HTTP endpoint is not enabled.

func (*API) Host

func (api *API) Host() host.Host

Host returns the libp2p Host used by the API, if any. The result is either the host provided during initialization, a default Host created with options from the configuration object, or nil.

func (*API) SetClient

func (api *API) SetClient(c *rpc.Client)

SetClient makes the component ready to perform RPC requests.

func (*API) Shutdown

func (api *API) Shutdown(ctx context.Context) error

Shutdown stops any API listeners.

type Config

type Config struct {

	// Listen address for the HTTP REST API endpoint.
	HTTPListenAddr ma.Multiaddr

	// TLS configuration for the HTTP listener
	TLS *tls.Config

	// Maximum duration before timing out reading a full request
	ReadTimeout time.Duration

	// Maximum duration before timing out reading the headers of a request
	ReadHeaderTimeout time.Duration

	// Maximum duration before timing out write of the response
	WriteTimeout time.Duration

	// Server-side amount of time a Keep-Alive connection will be
	// kept idle before being reused
	IdleTimeout time.Duration

	// Listen address for the Libp2p REST API endpoint.
	Libp2pListenAddr ma.Multiaddr

	// ID and PrivateKey are used to create a libp2p host if we
	// want the API component to do it (not by default).
	ID         peer.ID
	PrivateKey crypto.PrivKey

	// BasicAuthCreds is a map of username-password pairs
	// which are authorized to use Basic Authentication
	BasicAuthCreds map[string]string

	// Headers provides customization for the headers returned
	// by the API on existing routes.
	Headers map[string][]string

	// CORS header management
	CORSAllowedOrigins   []string
	CORSAllowedMethods   []string
	CORSAllowedHeaders   []string
	CORSExposedHeaders   []string
	CORSAllowCredentials bool
	CORSMaxAge           time.Duration

	// Tracing flag used to skip tracing specific paths when not enabled.
	Tracing bool
	// contains filtered or unexported fields

Config is used to intialize the API object and allows to customize the behaviour of it. It implements the config.ComponentConfig interface.

func (*Config) ApplyEnvVars

func (cfg *Config) ApplyEnvVars() error

ApplyEnvVars fills in any Config fields found as environment variables.

func (*Config) ConfigKey

func (cfg *Config) ConfigKey() string

ConfigKey returns a human-friendly identifier for this type of Config.

func (*Config) Default

func (cfg *Config) Default() error

Default initializes this Config with working values.

func (*Config) LoadJSON

func (cfg *Config) LoadJSON(raw []byte) error

LoadJSON parses a raw JSON byte slice created by ToJSON() and sets the configuration fields accordingly.

func (*Config) ToJSON

func (cfg *Config) ToJSON() (raw []byte, err error)

ToJSON produce a human-friendly JSON representation of the Config object.

func (*Config) Validate

func (cfg *Config) Validate() error

Validate makes sure that all fields in this Config have working values, at least in appearance.


Path Synopsis
Package client provides a Go Client for the IPFS Cluster API provided by the "api/rest" component.
Package client provides a Go Client for the IPFS Cluster API provided by the "api/rest" component.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto