api

Documentation

Overview

Package api implements a type used for creating the Benthos HTTP API.

Index

• func DocsMarkdown() ([]byte, error)
• func EndpointCaveats() string
• func GetMuxRoute(gMux *mux.Router, path string) *mux.Route
• func Spec() docs.FieldSpecs
• type Config
  • func FromParsed(pConf *docs.ParsedConfig) (conf Config, err error)
  • func NewConfig() Config
• type Dynamic
  • func NewDynamic() *Dynamic
  • func (d *Dynamic) HandleCRUD(w http.ResponseWriter, r *http.Request)
  • func (d *Dynamic) HandleList(w http.ResponseWriter, r *http.Request)
  • func (d *Dynamic) HandleUptime(w http.ResponseWriter, r *http.Request)
  • func (d *Dynamic) OnDelete(onDelete func(ctx context.Context, id string) error)
  • func (d *Dynamic) OnUpdate(onUpdate func(ctx context.Context, id string, conf []byte) error)
  • func (d *Dynamic) Started(id string, config []byte)
  • func (d *Dynamic) Stopped(id string)
• type OptFunc
  • func OptWithMiddleware(m func(http.Handler) http.Handler) OptFunc
  • func OptWithTLS(tls *tls.Config) OptFunc
• type Type
  • func New(version string, dateBuilt string, conf Config, wholeConf any, log log.Modular, ...) (*Type, error)
  • func (t *Type) Handler() http.Handler
  • func (t *Type) ListenAndServe() error
  • func (t *Type) RegisterEndpoint(path, desc string, handlerFunc http.HandlerFunc)
  • func (t *Type) Shutdown(ctx context.Context) error

Functions

func DocsMarkdown

func DocsMarkdown() ([]byte, error)

DocsMarkdown returns a markdown document for the http documentation.

func EndpointCaveats

func EndpointCaveats() string

EndpointCaveats is a documentation section for HTTP components that explains some of the caveats in registering endpoints due to their non-deterministic ordering and lack of explicit path terminators.

func GetMuxRoute

func GetMuxRoute(gMux *mux.Router, path string) *mux.Route

GetMuxRoute returns a *mux.Route (the result of calling .Path or .PathPrefix on the provided router), where in cases where the path ends in a slash it will be treated as a prefix. This isn't ideal but it's as close as we can realistically get to the http.ServeMux behaviour with added path variables.

NOTE: Eventually we can move back to http.ServeMux once https://github.com/golang/go/issues/61410 is available, and that'll allow us to make all paths explicit.

func Spec

func Spec() docs.FieldSpecs

Spec returns a field spec for the API configuration fields.

Types

type Config

type Config struct {
	Address        string                     `json:"address" yaml:"address"`
	Enabled        bool                       `json:"enabled" yaml:"enabled"`
	RootPath       string                     `json:"root_path" yaml:"root_path"`
	DebugEndpoints bool                       `json:"debug_endpoints" yaml:"debug_endpoints"`
	CertFile       string                     `json:"cert_file" yaml:"cert_file"`
	KeyFile        string                     `json:"key_file" yaml:"key_file"`
	CORS           httpserver.CORSConfig      `json:"cors" yaml:"cors"`
	BasicAuth      httpserver.BasicAuthConfig `json:"basic_auth" yaml:"basic_auth"`
}

Config contains the configuration fields for the Benthos API.

func FromParsed

func FromParsed(pConf *docs.ParsedConfig) (conf Config, err error)

func NewConfig

func NewConfig() Config

NewConfig creates a new API config with default values.

type Dynamic

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

Dynamic is a type for exposing CRUD operations on dynamic broker configurations as an HTTP interface. Events can be registered for listening to configuration changes, and these events should be forwarded to the dynamic broker.

func NewDynamic

func NewDynamic() *Dynamic

NewDynamic creates a new Dynamic API type.

func (*Dynamic) HandleCRUD

func (d *Dynamic) HandleCRUD(w http.ResponseWriter, r *http.Request)

HandleCRUD is an http.HandleFunc for performing CRUD operations on dynamic components by their ids.

func (*Dynamic) HandleList

func (d *Dynamic) HandleList(w http.ResponseWriter, r *http.Request)

HandleList is an http.HandleFunc for returning maps of active dynamic components by their id to uptime.

func (*Dynamic) HandleUptime

func (d *Dynamic) HandleUptime(w http.ResponseWriter, r *http.Request)

func (*Dynamic) OnDelete

func (d *Dynamic) OnDelete(onDelete func(ctx context.Context, id string) error)

OnDelete registers a func to handle CRUD events where a request wants to remove a dynamic configuration. An error should be returned if the component failed to close.

func (*Dynamic) OnUpdate

func (d *Dynamic) OnUpdate(onUpdate func(ctx context.Context, id string, conf []byte) error)

OnUpdate registers a func to handle CRUD events where a request wants to set a new value for a dynamic configuration. An error should be returned if the configuration is invalid or the component failed.

func (*Dynamic) Started

func (d *Dynamic) Started(id string, config []byte)

Started should be called whenever an active dynamic component has started with a new configuration. A normalised form of the configuration should be provided and will be delivered to clients that query the component contents.

func (*Dynamic) Stopped

func (d *Dynamic) Stopped(id string)

Stopped should be called whenever an active dynamic component has closed, whether by naturally winding down or from a request.

type OptFunc

type OptFunc func(t *Type)

OptFunc applies an option to an API type during construction.

func OptWithMiddleware

func OptWithMiddleware(m func(http.Handler) http.Handler) OptFunc

OptWithMiddleware adds an HTTP middleware to the Benthos API.

func OptWithTLS

func OptWithTLS(tls *tls.Config) OptFunc

OptWithTLS replaces the tls options of the HTTP server.

type Type

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

Type implements the Benthos HTTP API.

func New

func New(
	version string,
	dateBuilt string,
	conf Config,
	wholeConf any,
	log log.Modular,
	stats metrics.Type,
	opts ...OptFunc,
) (*Type, error)

New creates a new Benthos HTTP API.

func (*Type) Handler

func (t *Type) Handler() http.Handler

Handler returns the underlying http.Hander where paths are registered.

func (*Type) ListenAndServe

func (t *Type) ListenAndServe() error

ListenAndServe launches the API and blocks until the server closes or fails.

func (*Type) RegisterEndpoint

func (t *Type) RegisterEndpoint(path, desc string, handlerFunc http.HandlerFunc)

RegisterEndpoint registers a http.HandlerFunc under a path with a description that will be displayed under the /endpoints path.

func (*Type) Shutdown

func (t *Type) Shutdown(ctx context.Context) error

Shutdown attempts to close the http server.