rest

package
v0.0.0-...-a52a6fd Latest Latest
Warning

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

Go to latest
Published: Dec 1, 2020 License: Apache-2.0, MIT, Apache-2.0, + 1 more Imports: 42 Imported by: 0

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

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

These are the default values for Config

Variables

View Source
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

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 DefaultHTTPListenAddrs = []string{
	"/ip4/127.0.0.1/tcp/9094",
}

DefaultHTTPListenAddrs contains default listen addresses for the HTTP API.

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

These are the default values for Config.

Functions

This section is empty.

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

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

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

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

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

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

ToDisplayJSON returns JSON config as a string.

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.

type Person

type Person struct {
	Id   int    `json:"id"`
	Name string `json:name`
}

Directories

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
y or Y : Canonical URL