Documentation
¶
Overview ¶
Package common implements all the things that an IPFS Cluster API component must do, except the actual routes that it handles.
This is meant for re-use when implementing actual REST APIs by saving most of the efforts and automatically getting a lot of the setup and things like authentication handled.
The API exposes the routes 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.
This is used by rest and pinsvc packages.
Index ¶
- Constants
- Variables
- type API
- func (api *API) Context() context.Context
- func (api *API) GenerateTokenHandler(w http.ResponseWriter, r *http.Request)
- func (api *API) HTTPAddresses() ([]string, error)
- func (api *API) Headers() map[string][]string
- func (api *API) Host() host.Host
- func (api *API) ParseCidOrFail(w http.ResponseWriter, r *http.Request) types.Pin
- func (api *API) ParsePidOrFail(w http.ResponseWriter, r *http.Request) peer.ID
- func (api *API) ParsePinPathOrFail(w http.ResponseWriter, r *http.Request) types.PinPath
- func (api *API) SendResponse(w http.ResponseWriter, status int, err error, resp interface{})
- func (api *API) SetClient(c *rpc.Client)
- func (api *API) SetHeaders(w http.ResponseWriter)
- func (api *API) SetKeepAlivesEnabled(b bool)
- func (api *API) Shutdown(ctx context.Context) error
- func (api *API) StreamResponse(w http.ResponseWriter, next StreamIterator, errCh chan error)
- type Config
- func (cfg *Config) ApplyEnvVars() error
- func (cfg *Config) CorsOptions() *cors.Options
- func (cfg *Config) GetHTTPLogPath() string
- func (cfg *Config) LoadJSON(raw []byte) error
- func (cfg *Config) LogWriter() (io.Writer, error)
- func (cfg *Config) ToDisplayJSON() ([]byte, error)
- func (cfg *Config) ToJSON() (raw []byte, err error)
- func (cfg *Config) Validate() error
- type Route
- type StreamIterator
Constants ¶
const SetStatusAutomatically = -1
SetStatusAutomatically can be passed to SendResponse(), so that it will figure out which http status to set by itself.
const StreamChannelSize = 1024
StreamChannelSize is used to define buffer sizes for channels.
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
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 ¶
func NewAPIWithHost(ctx context.Context, cfg *Config, h host.Host, routes func(*rpc.Client) []Route) (*API, error)
NewAPIWithHost creates a new common API component and enables the libp2p-http endpoint using the given Host, if not nil.
func (*API) GenerateTokenHandler ¶
func (api *API) GenerateTokenHandler(w http.ResponseWriter, r *http.Request)
GenerateTokenHandler is a handle to obtain a new JWT token
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.
func (*API) ParseCidOrFail ¶
ParseCidOrFail parses a Cid and returns it or makes the request fail.
func (*API) ParsePidOrFail ¶
ParsePidOrFail parses a PID and returns it or makes the request fail.
func (*API) ParsePinPathOrFail ¶
ParsePinPathOrFail parses a pin path and returns it or makes the request fail.
func (*API) SendResponse ¶
func (api *API) SendResponse( w http.ResponseWriter, status int, err error, resp interface{}, )
SendResponse wraps all the logic for writing the response to a request: * Write configured headers * Write application/json content type * Write status: determined automatically if given "SetStatusAutomatically" * Write an error if there is or write the response if there is
func (*API) SetHeaders ¶
func (api *API) SetHeaders(w http.ResponseWriter)
SetHeaders sets all the headers that are common to all responses from this API. Called automatically from SendResponse().
func (*API) SetKeepAlivesEnabled ¶
SetKeepAlivesEnabled controls the HTTP server Keep Alive settings. Useful for testing.
func (*API) StreamResponse ¶
func (api *API) StreamResponse(w http.ResponseWriter, next StreamIterator, errCh chan error)
StreamResponse reads from an iterator and sends the response.
type Config ¶
type Config struct {
config.Saver
// These are meta-options and should be set by actual Config
// implementations as early as possible.
DefaultFunc func(*Config) error
ConfigKey string
EnvConfigKey string
Logger *logging.ZapEventLogger
RequestLogger *logging.ZapEventLogger
APIErrorFunc func(err error, status int) error
// Listen address for the HTTP REST API endpoint.
HTTPListenAddr []ma.Multiaddr
// TLS configuration for the HTTP listener
TLS *tls.Config
// pathSSLCertFile is a path to a certificate file used to secure the
// HTTP API endpoint. We track it so we can write it in the JSON.
PathSSLCertFile string
// pathSSLKeyFile is a path to the private key corresponding to the
// SSLKeyFile. We track it so we can write it in the JSON.
PathSSLKeyFile string
// 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
}
Config provides common API configuration values and allows to customize its behavior. It implements most of the config.ComponentConfig interface (except the Default() and ConfigKey() methods). Config should be embedded in a Config object that implements the missing methods and sets the meta options.
func (*Config) ApplyEnvVars ¶
ApplyEnvVars fills in any Config fields found as environment variables.
func (*Config) CorsOptions ¶
CorsOptions returns cors.Options setup from the configured values.
func (*Config) GetHTTPLogPath ¶
GetHTTPLogPath gets full path of the file where http logs should be saved.
func (*Config) LoadJSON ¶
LoadJSON parses a raw JSON byte slice created by ToJSON() and sets the configuration fields accordingly.
func (*Config) LogWriter ¶
LogWriter returns a writer to write logs to. If a log path is configured, it creates a file. Otherwise, uses the given logger.
func (*Config) ToDisplayJSON ¶
ToDisplayJSON returns JSON config as a string.
type Route ¶
type Route struct {
Name string
Method string
Pattern string
HandlerFunc http.HandlerFunc
}
Route defines a REST endpoint supported by this API.
type StreamIterator ¶
StreamIterator is a function that returns the next item. It is used in StreamResponse.
Source Files
Directories