ipfs-cluster: github.com/ipfs/ipfs-cluster/api/rest Index | Files | Directories

package rest

import "github.com/ipfs/ipfs-cluster/api/rest"

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.


Package Files

config.go restapi.go


const (
    DefaultReadTimeout       = 0
    DefaultReadHeaderTimeout = 5 * time.Second
    DefaultWriteTimeout      = 0
    DefaultIdleTimeout       = 120 * time.Second
    DefaultMaxHeaderBytes    = minMaxHeaderBytes

These are the default values for Config


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

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 DefaultHTTPListenAddrs = []string{

DefaultHTTPListenAddrs contains default listen addresses for the HTTP API.

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

These are the default values for Config.

type API Uses

type API struct {
    // contains filtered or unexported fields

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

func NewAPI Uses

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

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

func NewAPIWithHost Uses

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) HTTPAddresses Uses

func (api *API) HTTPAddresses() ([]string, error)

HTTPAddresses 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 Uses

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 Uses

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

SetClient makes the component ready to perform RPC requests.

func (*API) Shutdown Uses

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

Shutdown stops any API listeners.

type Config Uses

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

    // Maximum cumulative size of HTTP request headers in bytes
    // accepted by the server
    MaxHeaderBytes int

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

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

    // HTTPLogFile is path of the file that would save HTTP API logs. If this
    // path is empty, HTTP logs would be sent to standard output. This path
    // should either be absolute or relative to cluster base directory. Its
    // default value is empty.
    HTTPLogFile 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 Uses

func (cfg *Config) ApplyEnvVars() error

ApplyEnvVars fills in any Config fields found as environment variables.

func (*Config) ConfigKey Uses

func (cfg *Config) ConfigKey() string

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

func (*Config) Default Uses

func (cfg *Config) Default() error

Default initializes this Config with working values.

func (*Config) LoadJSON Uses

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) ToDisplayJSON Uses

func (cfg *Config) ToDisplayJSON() ([]byte, error)

ToDisplayJSON returns JSON config as a string.

func (*Config) ToJSON Uses

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

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

func (*Config) Validate Uses

func (cfg *Config) Validate() error

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


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

Package rest imports 42 packages (graph) and is imported by 1 packages. Updated 2020-10-24. Refresh now. Tools for package owners.