winter

README

winter

A Minimalist Mesh-Native Microservice Framework

Features

• Include opentelemetry-go
  • Support standard OTEL_ environment variables
  • Using zipkin as default exporter
  • Support TraceContext, Baggage and B3 propagation
  • Support otelhttp instrument
• Include prometheus/promhttp
  • Expose at /debug/metrics
• Built-in Readiness Check
  • Expose at /debug/ready
  • Component readiness registration with App#Check()
• Built-in Liveness Check
  • Expose at /debug/alive
  • Cascade Liveness Check failure from continuous Readiness Check failure
• Built-in debug/pprof
  • Expose at /debug/pprof
• Easy request binding
  • Unmarshal Header, Query, JSON Body and Form Body into any structure with json tag

Donation

See https://guoyk.xyz/donation

Credits

Guo Y.K., MIT License

Documentation

Index

• Constants
• func Bind[T any](c Context) (o T)
• func Halt(err error, opts ...HaltOption)
• func HaltString(s string, opts ...HaltOption)
• func JSONBodyFromError(err error) (m map[string]any)
• func NewHaltError(err error, opts ...HaltOption) error
• func StatusCodeFromError(err error) int
• type App
  • func New(opts ...Option) App
• type Context
• type HaltOption
  • func HaltWithBadRequest() HaltOption
  • func HaltWithExtra(k string, v any) HaltOption
  • func HaltWithExtras(m map[string]any) HaltOption
  • func HaltWithMessage(m string) HaltOption
  • func HaltWithStatusCode(code int) HaltOption
• type HandlerFunc
• type LifecycleFunc
• type MiddlewareFunc
• type Option
  • func WithConcurrency(c int) Option
  • func WithLivenessPath(s string) Option
  • func WithMetricsPath(s string) Option
  • func WithReadinessCascade(rc int) Option
  • func WithReadinessPath(s string) Option
  • func WithResponseLogging(d bool) Option
• type Registration
• type Registry
  • func NewRegistry() Registry

Constants

const (
	ContentTypeApplicationJSON = "application/json"
	ContentTypeTextPlain       = "text/plain"
	ContentTypeFormURLEncoded  = "application/x-www-form-urlencoded"
	ContentTypeMultipart       = "multipart/form-data"

	ContentTypeApplicationJSONUTF8 = "application/json; charset=utf-8"
	ContentTypeTextPlainUTF8       = "text/plain; charset=utf-8"

	DefaultReadinessPath = "/debug/ready"
	DefaultLivenessPath  = "/debug/alive"
	DefaultMetricsPath   = "/debug/metrics"
)

const (
	HaltExtraKeyMessage = "message"
)

Functions

func Bind

func Bind[T any](c Context) (o T)

Bind a generic version of [Context.Bind]

example:

	func actionValidate(c summer.Context) {
		args := summer.Bind[struct {
       		Tenant       string `json:"header_x_tenant"`
			Username     string `json:"username"`
			Age 		 int    `json:"age,string"`
		}](c)
        _ = args.Tenant
        _ = args.Username
        _ = args.Age
	}

func Halt

func Halt(err error, opts ...HaltOption)

Halt panic with NewHaltError

func HaltString

func HaltString(s string, opts ...HaltOption)

HaltString panic with NewHaltError and errors.New

func JSONBodyFromError

func JSONBodyFromError(err error) (m map[string]any)

JSONBodyFromError extract extras from previous created [HaltError]

func NewHaltError

func NewHaltError(err error, opts ...HaltOption) error

NewHaltError create a new [HaltError]

func StatusCodeFromError

func StatusCodeFromError(err error) int

StatusCodeFromError get status code from previous created [HaltError]

Types

type App

type App interface {
	// Handler inherit [http.Handler]
	http.Handler

	// Registry inherit [Registry]
	Registry

	// HandleFunc register an action function with given path pattern
	//
	// This function is similar with [http.ServeMux.HandleFunc]
	HandleFunc(pattern string, fn HandlerFunc)
}

App the main interface of [summer]

func New

func New(opts ...Option) App

New create an App with Option

type Context

type Context interface {
	// Context extend the [context.Context] interface by proxying to [http.Request.Context]
	context.Context

	// Inject inject underlying [context.Context]
	Inject(fn func(ctx context.Context) context.Context)

	// Req returns the underlying *http.Request
	Req() *http.Request

	// Header returns the headers of underlying [http.ResponseWriter]
	Header() http.Header

	// Bind unmarshal the request data into any struct with json tags
	//
	// HTTP header is prefixed with "header_"
	//
	// HTTP query is prefixed with "query_"
	//
	// both JSON and Form are supported
	Bind(data interface{})

	// Files returns the multipart file headers
	Files() map[string][]*multipart.FileHeader

	// Code set the response code, can be called multiple times
	Code(code int)

	// Body set the response body with content type, can be called multiple times
	Body(contentType string, buf []byte)

	// Text set the response body to plain text
	Text(s string)

	// JSON set the response body to json
	JSON(data interface{})

	// Perform actually perform the response
	// it is suggested to use in defer, recover() is included to recover from any panics
	Perform()
}

Context context of an incoming request and corresponding response writer

type HaltOption

type HaltOption func(h *haltError)

HaltOption configuration function for [HaltError]

func HaltWithBadRequest

func HaltWithBadRequest() HaltOption

HaltWithBadRequest alias to HaltWithStatusCode with http.StatusBadRequest

func HaltWithExtra

func HaltWithExtra(k string, v any) HaltOption

HaltWithExtra a HaltOption setting extras with a key-value

func HaltWithExtras

func HaltWithExtras(m map[string]any) HaltOption

HaltWithExtras a HaltOption setting extras with key-values

func HaltWithMessage

func HaltWithMessage(m string) HaltOption

HaltWithMessage a HaltOption overriding message key

func HaltWithStatusCode

func HaltWithStatusCode(code int) HaltOption

HaltWithStatusCode a HaltOption setting status code

type HandlerFunc

type HandlerFunc func(c Context)

HandlerFunc handler func with Context as argument

type LifecycleFunc

type LifecycleFunc func(ctx context.Context) (err error)

LifecycleFunc lifecycle function for component

type MiddlewareFunc

type MiddlewareFunc func(h HandlerFunc) HandlerFunc

MiddlewareFunc middleware function for component

type Option

type Option func(opts *options)

Option a function configuring App

func WithConcurrency

func WithConcurrency(c int) Option

WithConcurrency set maximum concurrent requests of App.

A value <= 0 means unlimited

func WithLivenessPath

func WithLivenessPath(s string) Option

WithLivenessPath set liveness path

func WithMetricsPath

func WithMetricsPath(s string) Option

WithMetricsPath set metrics path

func WithReadinessCascade

func WithReadinessCascade(rc int) Option

WithReadinessCascade set maximum continuous failed Readiness Checks after which Liveness CheckFunc start to fail.

Failing Liveness Checks could trigger a Pod restart.

A value <= 0 means disabled

func WithReadinessPath

func WithReadinessPath(s string) Option

WithReadinessPath set readiness check path

func WithResponseLogging

func WithResponseLogging(d bool) Option

WithResponseLogging set responseLogging

type Registration

type Registration interface {
	// Name returns name of registration
	Name() string

	// Startup set startup function
	Startup(fn LifecycleFunc) Registration

	// Check set check function
	Check(fn LifecycleFunc) Registration

	// Shutdown set shutdown function
	Shutdown(fn LifecycleFunc) Registration

	// Middleware set middleware function
	Middleware(fn MiddlewareFunc) Registration
}

Registration a component registration in Registry

type Registry

type Registry interface {
	// Component register a component
	//
	// In order of `startup`, `check` and `shutdown`
	Component(name string) Registration

	// Startup start all registered components
	Startup(ctx context.Context) (err error)

	// Shutdown shutdown all registered components
	Shutdown(ctx context.Context) (err error)

	// Check run all component checks
	Check(ctx context.Context, fn func(name string, err error))

	// Wrap wrap [HandlerFunc] with all registered component middlewares
	Wrap(h HandlerFunc) HandlerFunc
}

func NewRegistry

func NewRegistry() Registry