rest

Documentation

Overview

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.

Index

• Constants
• Variables
• type API
  • func NewAPI(ctx context.Context, cfg *Config) (*API, error)
  • func NewAPIWithHost(ctx context.Context, cfg *Config, h host.Host) (*API, error)
  • func (api *API) HTTPAddress() (string, error)
  • func (api *API) Host() host.Host
  • func (api *API) SetClient(c *rpc.Client)
  • func (api *API) Shutdown(ctx context.Context) error
• type Config
  • func (cfg *Config) ConfigKey() string
  • func (cfg *Config) Default() error
  • func (cfg *Config) LoadJSON(raw []byte) error
  • func (cfg *Config) ToJSON() (raw []byte, err error)
  • func (cfg *Config) Validate() error

Constants

const (
	DefaultHTTPListenAddr    = "/ip4/127.0.0.1/tcp/9094"
	DefaultReadTimeout       = 0
	DefaultReadHeaderTimeout = 5 * time.Second
	DefaultWriteTimeout      = 0
	DefaultIdleTimeout       = 120 * time.Second
)

These are the default values for Config

Variables

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

CORS defaults

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

var (
	DefaultHeaders = map[string][]string{}
)

These are the default values for Config.

Types

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 {
	config.Saver

	// 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) 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.