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.

Index

Package Files

config.go restapi.go

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 (
    // 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{
        "Access-Control-Allow-Headers": []string{"X-Requested-With", "Range"},
        "Access-Control-Allow-Methods": []string{"GET"},
        "Access-Control-Allow-Origin":  []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(cfg *Config) (*API, error)

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

func NewAPIWithHost Uses

func NewAPIWithHost(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 Uses

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 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() error

Shutdown stops any API listeners.

type Config Uses

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. By default it sets a CORS policy.
    Headers map[string][]string
    // 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 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) 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.

Directories

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

Package rest imports 30 packages (graph). Updated 2019-01-12. Refresh now. Tools for package owners.