rest

Documentation

Overview

Package rest supports creating RESTful applications.

Index

• func Builder[T Configer](f func(context.Context, T) (*Api, error)) bedrock.AppBuilder[T]
• func DefaultConfig() config.Source
• func Run[T Configer](r io.Reader, f func(context.Context, T) (*Api, error), opts ...RunOption)
• func WithDefaultConfig(r io.Reader) config.Source
• type Api
  • func NewApi(title, version string, opts ...RouterOption) *Api
  • func (api *Api) Route(method, pattern string, op Operation) error
  • func (api *Api) ServeHTTP(w http.ResponseWriter, req *http.Request)
• type Config
  • func (c Config) HttpServer(ctx context.Context, h http.Handler) (*http.Server, error)
  • func (c Config) Listener(ctx context.Context) (net.Listener, error)
• type Configer
• type HttpServerProvider
• type ListenerProvider
• type Operation
• type RouterOption
  • func Liveness(m health.Monitor) RouterOption
  • func MethodNotAllowed(h http.Handler) RouterOption
  • func NotFound(h http.Handler) RouterOption
  • func Readiness(m health.Monitor) RouterOption
• type RouterOptions
• type RunOption
  • func LogHandler(h slog.Handler) RunOption
• type RunOptions

Functions

func Builder

func Builder[T Configer](f func(context.Context, T) (*Api, error)) bedrock.AppBuilder[T]

Builder initializes a bedrock.AppBuilder for your Api.

func DefaultConfig

func DefaultConfig() config.Source

DefaultConfig is the default config.Source which aligns with the Config type.

func Run

func Run[T Configer](r io.Reader, f func(context.Context, T) (*Api, error), opts ...RunOption)

Run begins by reading, parsing and unmarshaling your custom config into the type T. Then it calls the providing function to initialize your Api implementation. Once it has the Api implementation, it begins serving the Api over HTTP. Various middlewares are applied at different stages for your convenience. Some middlewares include, automattic panic recovery, OTel SDK initialization and shutdown, and OS signal based shutdown.

func WithDefaultConfig

func WithDefaultConfig(r io.Reader) config.Source

WithDefaultConfig extends the config.Source returned by DefaultConfig to include values from the given io.Reader. The io.Reader can provide custom values, as well as, override default values.

Types

type Api

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

Api is a OpenAPI compliant http.Handler.

Api provides a set of standard features: - OpenAPI schema as JSON at "/openapi.json" - Liveness endpoint at "/health/liveness" - Readiness endpoint at "/health/readiness" - Standardized NotFound behaviour - Standardized MethodNotAllowed behaviour

func NewApi

func NewApi(title, version string, opts ...RouterOption) *Api

NewApi initializes a Api.

func (*Api) Route

func (api *Api) Route(method, pattern string, op Operation) error

Route will configure any request matching method and pattern to be handled by the provided Operation. It will also register the Operation with an underlying OpenAPI 3.0 schema.

func (*Api) ServeHTTP

func (api *Api) ServeHTTP(w http.ResponseWriter, req *http.Request)

ServeHTTP implements the http.Handler interface.

type Config

type Config struct {
	humus.Config `config:",squash"`

	OpenApi struct {
		Title   string `config:"title"`
		Version string `config:"version"`
	} `config:"openapi"`

	HTTP struct {
		Port uint `config:"port"`
	} `config:"http"`
}

Config is the default config which can be easily embedded into a more custom app specific config.

func (Config) HttpServer

func (c Config) HttpServer(ctx context.Context, h http.Handler) (*http.Server, error)

HttpServer implements the Configer interface.

func (Config) Listener

func (c Config) Listener(ctx context.Context) (net.Listener, error)

Listener implements the Configer interface.

type Configer

type Configer interface {
	appbuilder.OTelInitializer
	ListenerProvider
	HttpServerProvider
}

Configer is leveraged to constrain the custom config type into supporting specific initialization behaviour required by Run.

type HttpServerProvider

type HttpServerProvider interface {
	HttpServer(context.Context, http.Handler) (*http.Server, error)
}

HttpServerProvider initializes a http.Server.

type ListenerProvider

type ListenerProvider interface {
	Listener(context.Context) (net.Listener, error)
}

ListenerProvider initializes a net.Listener.

type Operation

type Operation interface {
	http.Handler

	Spec() (openapi3.Operation, error)
}

Operation extends the http.Handler interface by forcing any implementation to also provided a OpenAPI 3.0 representation of its operation.

type RouterOption

type RouterOption interface {
	ApplyRouterOption(*RouterOptions)
}

RouterOption sets values on [MuxOptions].

func Liveness

func Liveness(m health.Monitor) RouterOption

Liveness will register the given health.Monitor to be used for reporting when the entire application needs to be restarted.

See [Liveness, Readiness, and Startup Probes](https://kubernetes.io/docs/concepts/configuration/liveness-readiness-startup-probes/) for more details.

func MethodNotAllowed

func MethodNotAllowed(h http.Handler) RouterOption

MethodNotAllowed

func NotFound

func NotFound(h http.Handler) RouterOption

NotFound

func Readiness

func Readiness(m health.Monitor) RouterOption

Readiness will register the given health.Monitor to be used for reporting when the application is ready for to start accepting traffic.

An example usage of this is to tie the health.Monitor to any backend client circuit breakers. When one of the circuit breakers moves to an OPEN state your application can quickly notify upstream component(s) (e.g. load balancer) that no requests should be sent to it since they'll just fail anyways due to the circuit being OPEN.

See [Liveness, Readiness, and Startup Probes](https://kubernetes.io/docs/concepts/configuration/liveness-readiness-startup-probes/) for more details.

type RouterOptions

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

RouterOptions represents configurable values for a [Mux].

type RunOption

type RunOption interface {
	ApplyRunOption(*RunOptions)
}

RunOption sets a value on RunOptions.

func LogHandler

func LogHandler(h slog.Handler) RunOption

LogHandler overrides the default slog.Handler used for logging any error encountered while building or running the Api.

type RunOptions

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

RunOptions are used for configuring the running of a Api.