versionware

Documentation

Overview

Package versionware provides routing and middleware for building versioned HTTP services.

Index

• Constants
• func DefaultVersionError(w http.ResponseWriter, r *http.Request, status int, err error)
• type Handler
  • func NewHandler(vhs ...VersionHandler) *Handler
  • func (h *Handler) HandleErrors(errFunc VersionErrorHandler)
  • func (h *Handler) Resolve(requested vervet.Version) (*vervet.Version, http.Handler, error)
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, req *http.Request)
• type Validator
  • func NewValidator(config *ValidatorConfig, docs ...*openapi3.T) (*Validator, error)
  • func (v *Validator) Middleware(h http.Handler) http.Handler
• type ValidatorConfig
• type VersionErrorHandler
• type VersionHandler

Examples

• Handler

Constants

const (
	// HeaderSnykVersionRequested is a response header acknowledging the API
	// version that was requested.
	HeaderSnykVersionRequested = "snyk-version-requested"

	// HeaderSnykVersionServed is a response header indicating the actual API
	// version that was matched and served the response.
	HeaderSnykVersionServed = "snyk-version-served"
)

Functions

func DefaultVersionError

func DefaultVersionError(w http.ResponseWriter, r *http.Request, status int, err error)

DefaultVersionError provides a basic implementation of VersionErrorHandler that uses http.Error.

Types

type Handler

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

Handler is a multiplexing http.Handler that dispatches requests based on the version query parameter according to vervet's API version matching rules.

Example

h := versionware.NewHandler([]versionware.VersionHandler{{
	Version: vervet.MustParseVersion("2021-10-01"),
	Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if _, err := w.Write([]byte("oct")); err != nil {
			panic(err)
		}
	}),
}, {
	Version: vervet.MustParseVersion("2021-11-01"),
	Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if _, err := w.Write([]byte("nov")); err != nil {
			panic(err)
		}
	}),
}, {
	Version: vervet.MustParseVersion("2021-09-01"),
	Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if _, err := w.Write([]byte("sept")); err != nil {
			panic(err)
		}
	}),
}}...)

s := httptest.NewServer(h)
defer s.Close()

resp, err := s.Client().Get(s.URL + "?version=2021-10-31")
if err != nil {
	panic(err)
}
defer resp.Body.Close()
respBody, err := io.ReadAll(resp.Body)
if err != nil {
	panic(err)
}

fmt.Print(string(respBody))

Output:

oct

func NewHandler

func NewHandler(vhs ...VersionHandler) *Handler

NewHandler returns a new Handler instance, which handles versioned requests with the matching version handler.

func (*Handler) HandleErrors

func (h *Handler) HandleErrors(errFunc VersionErrorHandler)

HandleErrors changes the default error handler to the provided function. It may be used to control the format of versioning error responses.

func (*Handler) Resolve

func (h *Handler) Resolve(requested vervet.Version) (*vervet.Version, http.Handler, error)

Resolve returns the resolved version and its associated http.Handler for the requested version.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP implements http.Handler with the handler matching the version query parameter on the request. If no matching version is found, responds 404.

type Validator

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

Validator provides versioned OpenAPI validation middleware for HTTP requests and responses.

func NewValidator

func NewValidator(config *ValidatorConfig, docs ...*openapi3.T) (*Validator, error)

NewValidator returns a new validation middleware, which validates versioned requests according to the given OpenAPI spec versions. For configuration defaults, a nil config may be used.

func (*Validator) Middleware

func (v *Validator) Middleware(h http.Handler) http.Handler

Middleware returns an http.Handler which wraps the given handler with request and response validation according to the requested API version.

type ValidatorConfig

type ValidatorConfig struct {
	// ServerURL overrides the server URLs in the given OpenAPI specs to match
	// the URL of requests reaching the backend service. If unset, requests
	// must match the servers defined in OpenAPI specs.
	ServerURL string

	// VersionError is called on any error that occurs when trying to resolve the
	// API version.
	VersionError VersionErrorHandler

	// Options further configure the request and response validation. See
	// https://pkg.go.dev/github.com/getkin/kin-openapi/openapi3filter#ValidatorOption
	// for available options.
	Options []openapi3filter.ValidatorOption
}

ValidatorConfig defines how a new Validator may be configured.

type VersionErrorHandler

type VersionErrorHandler func(w http.ResponseWriter, r *http.Request, status int, err error)

VersionErrorHandler defines a function which handles versioning error responses in requests.

type VersionHandler

type VersionHandler struct {
	Version vervet.Version
	Handler http.Handler
}

VersionHandler expresses a pairing of Version and http.Handler.