rest

README

HTTPmux

The REST Plugin is a infrastructure Plugin which allows app plugins to handle HTTP requests (see the diagram below) in this sequence:

1. httpmux starts the HTTP server in its own goroutine
2. Plugins register their handlers with REST Plugin. To service HTTP requests, a plugin must first implement a handler function and register it at a given URL path using the RegisterHTTPHandler method. REST Plugin uses an HTTP request multiplexer from the gorilla/mux package to register the HTTP handlers by the specified URL path.
3. HTTP server routes HTTP requests to their respective registered handlers using the gorilla/mux multiplexer.

Configuration

• the server's port can be defined using commandline flag http-port or via the environment variable HTTP_PORT.

Example

The following example demonstrates the usage of the REST Plugin plugin API:

// httpExampleHandler returns a very simple HTTP request handler.
func httpExampleHandler(formatter *render.Render) http.HandlerFunc {

    // An example HTTP request handler which prints out attributes of 
    // a trivial Go structure in JSON format.
    return func(w http.ResponseWriter, req *http.Request) {
        formatter.JSON(w, http.StatusOK, struct{ Example string }{"This is an example"})
    }
}

// Register our HTTP request handler as a GET method serving at 
// the URL path "/example".
httpmux.RegisterHTTPHandler("/example", httpExampleHandler, "GET")

Once the handler is registered with REST Plugin and the agent is running, you can use curl to verify that it is operating properly:

$ curl -X GET http://localhost:9191/example
{
  "Example": "This is an example"
}

Security

REST plugin allows to optionally configure following security features:

• server certificate (HTTPS)
• Basic HTTP Authentication - username & password
• client certificates

All of them are disabled by default and can be enabled by config file:

endpoint: 127.0.0.1:9292
server-cert-file: server.crt
server-key-file: server.key
client-cert-files:
  - "ca.crt"
client-basic-auth:
  - "user:pass"
  - "foo:bar"

If server-cert-file and server-key-file are defined the server requires HTTPS instead of HTTP for all its endpoints.

client-cert-files the list of the root certificate authorities that server uses to validate client certificates. If the list is not empty only client who provide a valid certificate is allowed to access the server.

client-basic-auth allows to define user password pairs that are allowed to access the server. The config option defines a static list of allowed user. If the list is not empty default staticAuthenticator is instantiated. Alternatively, you can implement custom authenticator and inject it into the plugin (e.g.: if you want to read credentials from ETCD).

Example

In order to generated self-signed certificates you can use the following commands:

#generate key for "Our Certificate Authority"
openssl genrsa -out ca.key 2048

#generate certificate for CA
openssl req -new -nodes -x509 -key ca.key -out ca.crt  -subj '/CN=CA'

#generate certificate for the server assume that server will be accessed by 127.0.0.1
openssl genrsa -out server.key 2048
openssl req -new -key server.key -out server.csr -subj '/CN=127.0.0.1'
openssl x509 -req -extensions client_server_ssl -extfile openssl_ext.conf -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt

#generate client certificate
openssl genrsa -out client.key 2048
openssl req -new -key client.key -out client.csr -subj '/CN=client'
openssl x509 -req -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out client.crt -days 360

Once the security features are enabled, the endpoint can be accessed by the following commands:

• HTTPS where ca.pem is a certificate authority where server certificate should be validated (in case of self-signed certificates)

  curl --cacert ca.crt  https://127.0.0.1:9292/log/list
  

• HTTPS + client cert where client.crt is a valid client certificate.

  curl --cacert ca.crt  --cert client.crt --key client.key  https://127.0.0.1:9292/log/list
  

• HTTPS + basic auth where user:pass is a valid username password pair.

  curl --cacert ca.crt  -u user:pass  https://127.0.0.1:9292/log/list
  

• HTTPS + client cert + basic auth

  curl --cacert ca.crt  --cert client.crt --key client.key -u user:pass  https://127.0.0.1:9292/log/list
  

Documentation

Overview

Package rest implements the HTTP server through which plugins can expose their REST APIs to the outside world.

Index

• Constants
• Variables
• func DeclareHTTPPortFlag(pluginName infra.PluginName, defaultPortOpts ...uint)
• func FixConfig(cfg *Config)
• func ListenAndServe(config Config, handler http.Handler) (srv *http.Server, err error)
• func PluginConfig(pluginCfg config.PluginConfig, cfg *Config, pluginName infra.PluginName) error
• type BasicHTTPAuthenticator
• type Config
  • func DefaultConfig() *Config
  • func (cfg *Config) GetPort() int
  • func (cfg *Config) UseHTTPS() bool
• type Deps
• type HTTPHandlers
• type HandlerProvider
• type Option
  • func UseAuthenticator(a BasicHTTPAuthenticator) Option
  • func UseConf(conf Config) Option
  • func UseDeps(cb func(*Deps)) Option
• type Plugin
  • func NewPlugin(opts ...Option) *Plugin
  • func (p *Plugin) AfterInit() (err error)
  • func (p *Plugin) Close() error
  • func (p *Plugin) GetPort() int
  • func (p *Plugin) Init() (err error)
  • func (p *Plugin) RegisterHTTPHandler(path string, provider HandlerProvider, methods ...string) *mux.Route

Constants

const (
	// DefaultHost is a host used by default
	DefaultHost = "0.0.0.0"
	// DefaultHTTPPort is a port used by default
	DefaultHTTPPort = "9191"
	// DefaultEndpoint 0.0.0.0:9191
	DefaultEndpoint = DefaultHost + ":" + DefaultHTTPPort
)

Variables

var DefaultPlugin = *NewPlugin()

DefaultPlugin is a default instance of Plugin.

Functions

func DeclareHTTPPortFlag

func DeclareHTTPPortFlag(pluginName infra.PluginName, defaultPortOpts ...uint)

DeclareHTTPPortFlag declares http port (with usage & default value) a flag for a particular plugin name

func FixConfig

func FixConfig(cfg *Config)

FixConfig fill default values for empty fields

func ListenAndServe

func ListenAndServe(config Config, handler http.Handler) (srv *http.Server, err error)

ListenAndServe starts a http server.

func PluginConfig

func PluginConfig(pluginCfg config.PluginConfig, cfg *Config, pluginName infra.PluginName) error

PluginConfig tries : - to load flag <plugin-name>-port and then FixConfig() just in case - alternatively <plugin-name>-config and then FixConfig() just in case - alternatively DefaultConfig()

Types

type BasicHTTPAuthenticator

type BasicHTTPAuthenticator interface {
	// Authenticate returns true if user is authenticated successfully, false otherwise.
	Authenticate(user string, pass string) bool
}

BasicHTTPAuthenticator is a delegate that implements basic HTTP authentication

type Config

type Config struct {
	// Endpoint is an address of HTTP server
	Endpoint string

	// ReadTimeout is the maximum duration for reading the entire
	// request, including the body.
	//
	// Because ReadTimeout does not let Handlers make per-request
	// decisions on each request body's acceptable deadline or
	// upload rate, most users will prefer to use
	// ReadHeaderTimeout. It is valid to use them both.
	ReadTimeout time.Duration

	// ReadHeaderTimeout is the amount of time allowed to read
	// request headers. The connection's read deadline is reset
	// after reading the headers and the Handler can decide what
	// is considered too slow for the body.
	ReadHeaderTimeout time.Duration

	// WriteTimeout is the maximum duration before timing out
	// writes of the response. It is reset whenever a new
	// request's header is read. Like ReadTimeout, it does not
	// let Handlers make decisions on a per-request basis.
	WriteTimeout time.Duration

	// IdleTimeout is the maximum amount of time to wait for the
	// next request when keep-alives are enabled. If IdleTimeout
	// is zero, the value of ReadTimeout is used. If both are
	// zero, there is no timeout.
	IdleTimeout time.Duration

	// MaxHeaderBytes controls the maximum number of bytes the
	// server will read parsing the request header's keys and
	// values, including the request line. It does not limit the
	// size of the request body.
	// If zero, DefaultMaxHeaderBytes is used.
	MaxHeaderBytes int

	// ServerCertfile is path to the server certificate. If the certificate and corresponding
	// key (see config item below) is defined server uses HTTPS instead of HTTP.
	ServerCertfile string `json:"server-cert-file"`

	// ServerKeyfile is path to the server key file.
	ServerKeyfile string `json:"server-key-file"`

	// ClientBasicAuth is a slice of credentials in form "username:password"
	// used for basic HTTP authentication. If defined only authenticated users are allowed
	// to access the server.
	ClientBasicAuth []string `json:"client-basic-auth"`

	// ClientCerts is a slice of the root certificate authorities
	// that servers uses to verify a client certificate
	ClientCerts []string `json:"client-cert-files"`
}

Config is a configuration for HTTP server It is meant to be extended with security (TLS...)

func DefaultConfig

func DefaultConfig() *Config

DefaultConfig returns new instance of config with default endpoint

func (*Config) GetPort

func (cfg *Config) GetPort() int

GetPort parses suffix from endpoint & returns integer after last ":" (otherwise it returns 0)

func (*Config) UseHTTPS

func (cfg *Config) UseHTTPS() bool

UseHTTPS returns true if server certificate and key is defined.

type Deps

type Deps struct {
	infra.PluginDeps

	// Authenticator can be injected in a flavor inject method.
	// If there is no authenticator injected and config contains
	// user password, the default staticAuthenticator is instantiated.
	// By default the authenticator is disabled.
	Authenticator BasicHTTPAuthenticator //inject
}

Deps lists the dependencies of the Rest plugin.

type HTTPHandlers

type HTTPHandlers interface {
	// RegisterHTTPHandler propagates to Gorilla mux
	RegisterHTTPHandler(path string, provider HandlerProvider, methods ...string) *mux.Route

	// GetPort returns configured port number (for debugging purposes)
	GetPort() int
}

HTTPHandlers defines the API exposed by the REST plugin. Use this interface to declare dependency on the REST functionality, i.e.:

type Deps struct {
    HTTP rest.HTTPHandlers // inject plugin implementing RegisterHTTPHandler
    // other dependencies ...
}

type HandlerProvider

type HandlerProvider func(formatter *render.Render) http.HandlerFunc

HandlerProvider is a function used for registering handlers via HTTPHandlers

type Option

type Option func(*Plugin)

Option is a function that can be used in NewPlugin to customize Plugin.

func UseAuthenticator

func UseAuthenticator(a BasicHTTPAuthenticator) Option

UseAuthenticator returns an Option which sets HTTP Authenticator.

func UseConf

func UseConf(conf Config) Option

UseConf returns Option which injects a particular configuration.

func UseDeps

func UseDeps(cb func(*Deps)) Option

UseDeps returns Option that can inject custom dependencies.

type Plugin

type Plugin struct {
	Deps

	*Config
	// contains filtered or unexported fields
}

Plugin struct holds all plugin-related data.

func NewPlugin

func NewPlugin(opts ...Option) *Plugin

NewPlugin creates a new Plugin with the provided Options.

func (*Plugin) AfterInit

func (p *Plugin) AfterInit() (err error)

AfterInit starts the HTTP server.

func (*Plugin) Close

func (p *Plugin) Close() error

Close stops the HTTP server.

func (*Plugin) GetPort

func (p *Plugin) GetPort() int

GetPort returns plugin configuration port

func (*Plugin) Init

func (p *Plugin) Init() (err error)

Init is the plugin entry point called by Agent Core - It prepares Gorilla MUX HTTP Router

func (*Plugin) RegisterHTTPHandler

func (p *Plugin) RegisterHTTPHandler(path string, provider HandlerProvider, methods ...string) *mux.Route

RegisterHTTPHandler registers HTTP <handler> at the given <path>.