common

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 NewAPI(ctx context.Context, cfg *Config, routes func(*rpc.Client) []Route) (*API, error)
  • func NewAPIWithHost(ctx context.Context, cfg *Config, h host.Host, ...) (*API, error)
  • 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 ApiVersion = "v0/"

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

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, routes func(*rpc.Client) []Route) (*API, error)

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

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

func (api *API) Context() context.Context

Context returns the API context

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

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

func (api *API) Headers() map[string][]string

Headers returns the configured Headers. Useful for testing.

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

func (api *API) ParseCidOrFail(w http.ResponseWriter, r *http.Request) types.Pin

ParseCidOrFail parses a Cid and returns it or makes the request fail.

func (*API) ParsePidOrFail

func (api *API) ParsePidOrFail(w http.ResponseWriter, r *http.Request) peer.ID

ParsePidOrFail parses a PID and returns it or makes the request fail.

func (*API) ParsePinPathOrFail

func (api *API) ParsePinPathOrFail(w http.ResponseWriter, r *http.Request) types.PinPath

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

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

SetClient makes the component ready to perform RPC requests.

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

func (api *API) SetKeepAlivesEnabled(b bool)

SetKeepAlivesEnabled controls the HTTP server Keep Alive settings. Useful for testing.

func (*API) Shutdown

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

Shutdown stops any API listeners.

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

func (cfg *Config) ApplyEnvVars() error

ApplyEnvVars fills in any Config fields found as environment variables.

func (*Config) CorsOptions

func (cfg *Config) CorsOptions() *cors.Options

CorsOptions returns cors.Options setup from the configured values.

func (*Config) GetHTTPLogPath

func (cfg *Config) GetHTTPLogPath() string

GetHTTPLogPath gets full path of the file where http logs should be saved.

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

func (cfg *Config) LogWriter() (io.Writer, error)

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

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 Route

type Route struct {
	Name        string
	Method      string
	Pattern     string
	HandlerFunc http.HandlerFunc
}

Route defines a REST endpoint supported by this API.

type StreamIterator

type StreamIterator func() (interface{}, bool, error)

StreamIterator is a function that returns the next item. It is used in StreamResponse.