api

Documentation

Overview

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

Index

• func DocsMarkdown() ([]byte, error)
• func Spec() docs.FieldSpecs
• type Config
  • 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) 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 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 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) 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.