plugger

README

Go-Plugger

This package is a wrapper for a go-swagger which makes is plugable as just a server.

WARNING: This package is under development and is not yet ready for use!

Idea

The go-swagger generated server is designed to be a central part of the application. It isn't easy to say: "okay, lets switch from a hand-written server to a code-generated one". But that's a common case.

This package is't designed to make go-swagger server look like a standard net/http server, but makes it plugable as easy as possible.

TODO:

• Add middleware routing
• Add easy logging
• Add instrumentation support (tracing)
• Add instrumentation support (monitoring)
• Cover all with tests

Documentation

Index

• type API
• type Option
  • func WithAPIDefaults() Option
  • func WithAPIKeyAuthenticator(f func(string, string, security.TokenAuthentication) runtime.Authenticator) Option
  • func WithBasicAuthenticator(f func(security.UserPassAuthentication) runtime.Authenticator) Option
  • func WithBearerAuthenticator(f func(string, security.ScopedTokenAuthentication) runtime.Authenticator) Option
  • func WithBinProducer(p runtime.Producer) Option
  • func WithCleanupTimeout(t time.Duration) Option
  • func WithCommandLineOptionsGroups(g []swag.CommandLineOptionsGroup) Option
  • func WithConfiguredAPI() Option
  • func WithEnabledListeners(listeners []string) Option
  • func WithGracefulTimeout(t time.Duration) Option
  • func WithHTMLProducer(p runtime.Producer) Option
  • func WithHost(host string) Option
  • func WithJSONConsumer(c runtime.Consumer) Option
  • func WithJSONProducer(p runtime.Producer) Option
  • func WithKeepAlive(t time.Duration) Option
  • func WithListenLimit(limit int) Option
  • func WithLogger(f func(string, ...interface{})) Option
  • func WithMaxHeaderSize(size int) Option
  • func WithPort(port int) Option
  • func WithPreServerShutdown(f func()) Option
  • func WithReadTimeout(t time.Duration) Option
  • func WithServeError(f func(http.ResponseWriter, *http.Request, error)) Option
  • func WithServerDefaults() Option
  • func WithServerShutdown(f func()) Option
  • func WithSocketPath(path string) Option
  • func WithTLSCACertificate(cert string) Option
  • func WithTLSCertificate(cert string) Option
  • func WithTLSCertificateKey(cert string) Option
  • func WithTLSHost(host string) Option
  • func WithTLSKeepAlive(t time.Duration) Option
  • func WithTLSListenLimit(limit int) Option
  • func WithTLSPort(port int) Option
  • func WithTLSReadTimeout(t time.Duration) Option
  • func WithTLSWriteTimeout(t time.Duration) Option
  • func WithWriteTimeout(t time.Duration) Option
• type Plug
  • func NewPlug(srv Server, api API, opts ...Option) *Plug
  • func (p *Plug) Router() chi.Router
  • func (p *Plug) Serve() error
  • func (p *Plug) Shutdown() error
• type Server

Types

type API

type API interface {
	SetDefaultProduces(mediaType string)
	SetDefaultConsumes(mediaType string)
	SetSpec(spec *loads.Document)
	DefaultProduces() string
	DefaultConsumes() string
	Formats() strfmt.Registry
	RegisterFormat(name string, format strfmt.Format, validator strfmt.Validator)
	Validate() error
	ServeErrorFor(operationID string) func(http.ResponseWriter, *http.Request, error)
	AuthenticatorsFor(schemes map[string]spec.SecurityScheme) map[string]runtime.Authenticator
	Authorizer() runtime.Authorizer
	ConsumersFor(mediaTypes []string) map[string]runtime.Consumer
	ProducersFor(mediaTypes []string) map[string]runtime.Producer
	HandlerFor(method, path string) (http.Handler, bool)
	Context() *middleware.Context
	Serve(builder middleware.Builder) http.Handler
	Init()
	RegisterConsumer(mediaType string, consumer runtime.Consumer)
	RegisterProducer(mediaType string, producer runtime.Producer)
	AddMiddlewareFor(method, path string, builder middleware.Builder)
}

API is a set of functions of a swagger-generated API

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option is a parameter option that defines a server parameter

func WithAPIDefaults

func WithAPIDefaults() Option

WithAPIDefaults sets default values to API fields

func WithAPIKeyAuthenticator

func WithAPIKeyAuthenticator(
	f func(string, string, security.TokenAuthentication) runtime.Authenticator) Option

WithAPIKeyAuthenticator generates a runtime.Authenticator from the supplied token auth function. It has a default implementation in the security package, however you can replace it for your particular usage.

func WithBasicAuthenticator

func WithBasicAuthenticator(
	f func(security.UserPassAuthentication) runtime.Authenticator) Option

WithBasicAuthenticator generates a runtime.Authenticator from the supplied basic auth function. It has a default implementation in the security package, however you can replace it for your particular usage.

func WithBearerAuthenticator

func WithBearerAuthenticator(
	f func(string, security.ScopedTokenAuthentication) runtime.Authenticator) Option

WithBearerAuthenticator BearerAuthenticator generates a runtime.Authenticator from the supplied bearer token auth function. It has a default implementation in the security package, however you can replace it for your particular usage.

func WithBinProducer

func WithBinProducer(p runtime.Producer) Option

WithBinProducer BinProducer registers a producer for the following mime types:

• application/octet-stream

func WithCleanupTimeout

func WithCleanupTimeout(t time.Duration) Option

WithCleanupTimeout grace period for which to wait before killing idle connections

func WithCommandLineOptionsGroups

func WithCommandLineOptionsGroups(g []swag.CommandLineOptionsGroup) Option

WithCommandLineOptionsGroups Custom command line argument groups with their descriptions

func WithConfiguredAPI

func WithConfiguredAPI() Option

WithConfiguredAPI runs generated API configuration function of swagger server. Normally it runs functions defined in `configure_*.go` file, where you has to define your handlers and settings in a classic go-swagger generated server.

You may add this option if you want to setup some defaults defined there. But you don't need it if you set up the server configuration yourself using the Plugger

func WithEnabledListeners

func WithEnabledListeners(listeners []string) Option

WithEnabledListeners the listeners to enable, this can be repeated and defaults to the schemes in the swagger spec

func WithGracefulTimeout

func WithGracefulTimeout(t time.Duration) Option

WithGracefulTimeout grace period for which to wait before shutting down the server

func WithHTMLProducer

func WithHTMLProducer(p runtime.Producer) Option

WithHTMLProducer HTMLProducer registers a producer for the following mime types:

• text/html

func WithHost

func WithHost(host string) Option

WithHost the IP to listen on

func WithJSONConsumer

func WithJSONConsumer(c runtime.Consumer) Option

WithJSONConsumer JSONConsumer registers a consumer for the following mime types:

• application/json

func WithJSONProducer

func WithJSONProducer(p runtime.Producer) Option

WithJSONProducer JSONProducer registers a producer for the following mime types:

• application/json

func WithKeepAlive

func WithKeepAlive(t time.Duration) Option

WithKeepAlive sets the TCP keep-alive timeouts on accepted connections. It prunes dead TCP connections ( e.g. closing laptop mid-download)

func WithListenLimit

func WithListenLimit(limit int) Option

WithListenLimit limit the number of outstanding requests

func WithLogger

func WithLogger(f func(string, ...interface{})) Option

WithLogger User defined logger function

func WithMaxHeaderSize

func WithMaxHeaderSize(size int) Option

WithMaxHeaderSize 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.

func WithPort

func WithPort(port int) Option

WithPort the port to listen on for insecure connections, defaults to a random value

func WithPreServerShutdown

func WithPreServerShutdown(f func()) Option

WithPreServerShutdown PreServerShutdown is called before the HTTP(S) server is shutdown This allows for custom functions to get executed before the HTTP(S) server stops accepting traffic

func WithReadTimeout

func WithReadTimeout(t time.Duration) Option

WithReadTimeout maximum duration before timing out read of the request

func WithServeError

func WithServeError(f func(http.ResponseWriter, *http.Request, error)) Option

WithServeError ServeError is called when an error is received, there is a default handler but you can set your own with this

func WithServerDefaults

func WithServerDefaults() Option

WithServerDefaults sets default values to server fields

func WithServerShutdown

func WithServerShutdown(f func()) Option

WithServerShutdown ServerShutdown is called when the HTTP(S) server is shut down and done handling all active connections and does not accept connections any more

func WithSocketPath

func WithSocketPath(path string) Option

WithSocketPath the unix socket to listen on

func WithTLSCACertificate

func WithTLSCACertificate(cert string) Option

WithTLSCACertificate the certificate authority file to be used with mutual tls auth

func WithTLSCertificate

func WithTLSCertificate(cert string) Option

WithTLSCertificate the certificate to use for secure connections

func WithTLSCertificateKey

func WithTLSCertificateKey(cert string) Option

WithTLSCertificateKeyTLSCertificateKey the private key to use for secure connections

func WithTLSHost

func WithTLSHost(host string) Option

WithTLSHost the IP to listen on for tls

func WithTLSKeepAlive

func WithTLSKeepAlive(t time.Duration) Option

WithTLSKeepAlive sets the TCP keep-alive timeouts on accepted connections. It prunes dead TCP connections ( e.g. closing laptop mid-download)

func WithTLSListenLimit

func WithTLSListenLimit(limit int) Option

WithTLSListenLimit limit the number of outstanding requests

func WithTLSPort

func WithTLSPort(port int) Option

WithTLSPort the port to listen on for secure connections, defaults to a random value

func WithTLSReadTimeout

func WithTLSReadTimeout(t time.Duration) Option

WithTLSReadTimeout maximum duration before timing out read of the request

func WithTLSWriteTimeout

func WithTLSWriteTimeout(t time.Duration) Option

WithTLSWriteTimeout maximum duration before timing out write of the response

func WithWriteTimeout

func WithWriteTimeout(t time.Duration) Option

WithWriteTimeout maximum duration before timing out write of the response

type Plug

type Plug struct {
	// contains filtered or unexported fields
}

Plug is a Swagger API wrapper to make it plugable

func NewPlug

func NewPlug(srv Server, api API, opts ...Option) *Plug

NewPlug creates a new Swagger API plug

srv is a code-generated go-swagger server. api is a code-generated go-swagger api opts is a set of api or server options of your choice

Note that if you predefine any fields of the API or the Server, options will override them

You can also still use the server structure to parse command-line flags using "github.com/jessevdk/go-flags" library as go-swagger does

func (*Plug) Router

func (p *Plug) Router() chi.Router

Router returns a built-in router

Note that router is bound to the root address. So if you specified any basePath in the swagger.yml you have to provide a full path to the router. E.g. if you set basePath: /api the route should start with /api as well.

func (*Plug) Serve

func (p *Plug) Serve() error

Serve the API

func (*Plug) Shutdown

func (p *Plug) Shutdown() error

Shutdown server and clean up resources

type Server

type Server interface {
	ConfigureAPI()
	Logf(f string, args ...interface{})
	Fatalf(f string, args ...interface{})
	Serve() (err error)
	Listen() error
	Shutdown() error
	GetHandler() http.Handler
	SetHandler(handler http.Handler)
	UnixListener() (net.Listener, error)
	HTTPListener() (net.Listener, error)
	TLSListener() (net.Listener, error)
}

Server is a set of functions of a swagger-generated server