rest

README

HTTPmux

The REST Plugin is a infrastructure Plugin which allows app plugins to handle HTTP requests (see the following diagram) 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 an HTTP request multiplexer from the gorilla/mux package to register the HTTP handlers by the specified URL path.
3. HTPP 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 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"
}

Documentation

Overview

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

Index

• Constants
• func ListenAndServeHTTP(config Config, handler http.Handler) (httpServer io.Closer, err error)
• type Config
• type Deps
• type HTTPHandlers
• type ListenAndServe
• type Plugin
  • func FromExistingServer(listenAndServe ListenAndServe) *Plugin
  • func (plugin *Plugin) AfterInit() (err error)
  • func (plugin *Plugin) Close() error
  • func (plugin *Plugin) Init() (err error)
  • func (plugin *Plugin) RegisterHTTPHandler(path string, handler func(formatter *render.Render) http.HandlerFunc, ...) *mux.Route

Constants

const (
	// DefaultHTTPPort is used during HTTP server startup unless different port was configured
	DefaultHTTPPort = "9191"
)

Functions

func ListenAndServeHTTP

func ListenAndServeHTTP(config Config, handler http.Handler) (httpServer io.Closer, err error)

ListenAndServeHTTP start http server

Types

type Config

type Config struct {
	// Endpoint is a 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
}

Config is a configuration for HTTP server

type Deps

type Deps struct {
	localdeps.PluginLogDeps // inject

	// Used to simplify if not whole config needs to be configured
	HTTPport string //inject optionally

}

Deps is here to group injected dependencies of plugin to not mix with other plugin fields.

type HTTPHandlers

type HTTPHandlers interface {
	// RegisterHTTPHandler propagates to Gorilla mux
	RegisterHTTPHandler(path string,
		handler func(formatter *render.Render) http.HandlerFunc,
		methods ...string) *mux.Route
}

HTTPHandlers is an interface that is useful for other plugins that need to register HTTP Handlers. Use this interface as type for the field in terms of dependency injection.

type ListenAndServe

type ListenAndServe func(config Config, handler http.Handler) (
	httpServer io.Closer, err error)

ListenAndServe is a function that used Config & Handler to handle HTTP Requests. It return instance of io.Closer to close the HTTP Server during cleanup.

type Plugin

type Plugin struct {
	Deps
	// contains filtered or unexported fields
}

Plugin implements the Plugin interface.

func FromExistingServer

func FromExistingServer(listenAndServe ListenAndServe) *Plugin

FromExistingServer is used mainly for testing purpose

Example:

   httpmux.FromExistingServer(mock.SetHandler)
	  mock.NewRequest("GET", "/v1/a", nil)

func (*Plugin) AfterInit

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

AfterInit starts the HTTP server

func (*Plugin) Close

func (plugin *Plugin) Close() error

Close cleans up the resources

func (*Plugin) Init

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

Init is entry point called by Agent Core - It prepares Gorilla MUX HTTP Router - registers grpc transport

func (*Plugin) RegisterHTTPHandler

func (plugin *Plugin) RegisterHTTPHandler(path string,
	handler func(formatter *render.Render) http.HandlerFunc,
	methods ...string) *mux.Route

RegisterHTTPHandler propagates to Gorilla mux