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 ¶
const ( DefaultReadTimeout = 0 DefaultReadHeaderTimeout = 5 * time.Second DefaultWriteTimeout = 0 DefaultIdleTimeout = 120 * time.Second DefaultMaxHeaderBytes = minMaxHeaderBytes )
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 DefaultHTTPListenAddrs = []string{
"/ip4/127.0.0.1/tcp/9094",
}
DefaultHTTPListenAddrs contains default listen addresses for the HTTP API.
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 NewAPIWithHost ¶
NewAPIWithHost creates a new REST API component and enables the libp2p-http endpoint using the given Host, if not nil.
func (*API) HTTPAddresses ¶
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 ¶
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.
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 ¶
ApplyEnvVars fills in any Config fields found as environment variables.
func (*Config) LoadJSON ¶
LoadJSON parses a raw JSON byte slice created by ToJSON() and sets the configuration fields accordingly.
func (*Config) ToDisplayJSON ¶
ToDisplayJSON returns JSON config as a string.
Source Files
Directories