summer

README

summer

A Minimalist Mesh-Native Microservice Framework for Golang

Core Concept

By using generics, summer allows you to use the basic summer.Context, or create your own Context type, without changing programming paradigm.

Features

• Support opentelemetry-go
  • Support standard OTEL_ environment variables
  • Using zipkin as default exporter
  • Support TraceContext, Baggage and B3 propagation
  • Support otelhttp instrument
• Support prometheus/promhttp
  • Expose at /debug/metrics
• Support Readiness Check
  • Expose at /debug/ready
  • Component readiness registration with App#Check()
• Support Liveness Check
  • Expose at /debug/alive
  • Cascade Liveness Check failure from continuous Readiness Check failure
• Support debug/pprof
  • Expose at /debug/pprof
• Bind request data
  • Unmarshal header, query, json body and form body into any structure with json tag

Setup Tracing

OpenTelemetry setup is left to end-user

Example:

package summer

import (
	"github.com/guoyk93/rg"
	"go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp"
	"go.opentelemetry.io/contrib/propagators/b3"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/exporters/zipkin"
	"go.opentelemetry.io/otel/propagation"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
	"net/http"
)

// BootTracing setup OpenTelemetry tracing best practice
func BootTracing() {
	otel.SetTracerProvider(sdktrace.NewTracerProvider(
		sdktrace.WithBatcher(rg.Must(zipkin.New(""))),
	))
	otel.SetTextMapPropagator(
		propagation.NewCompositeTextMapPropagator(
			propagation.TraceContext{},
			propagation.Baggage{},
			b3.New(b3.WithInjectEncoding(b3.B3MultipleHeader|b3.B3SingleHeader)),
		),
	)
	// re-initialize otelhttp.DefaultClient and http.DefaultClient
	otelhttp.DefaultClient = &http.Client{
		Transport: otelhttp.NewTransport(http.DefaultTransport),
	}
	http.DefaultClient = otelhttp.DefaultClient
}

Donation

See https://guoyk.xyz/donation

Credits

Guo Y.K., MIT License

Documentation

Index

• Constants
• func Bind[T any](c Context) (o T)
• func BodyFromError(err error) (m map[string]any)
• func Halt(err error, opts ...HaltOption)
• func HaltString(s string, opts ...HaltOption)
• func NewHaltError(err error, opts ...HaltOption) error
• func StatusCodeFromError(err error) int
• type App
  • func Basic(opts ...Option) App[Context]
  • func New[T Context](cf ContextFactory[T], opts ...Option) App[T]
• type Context
  • func BasicContext(rw http.ResponseWriter, req *http.Request) Context
• type ContextFactory
• 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 InjectFunc
• type LifecycleFunc
• 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
• type Registration
• type Registry
  • func NewRegistry() Registry

Constants

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

	ContentTypeApplicationJSONUTF8 = "application/json; charset=utf-8"
	ContentTypeTextPlainUTF8       = "text/plain; charset=utf-8"
	ContentTypeFormURLEncodedUTF8  = "application/x-www-form-urlencoded; 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 BodyFromError

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

BodyFromError extract extras from previous created [HaltError]

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 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[T Context] 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[T])
}

App the main interface of summer

func Basic

func Basic(opts ...Option) App[Context]

Basic create an App with vanilla Context and additional Option

func New

func New[T Context](cf ContextFactory[T], opts ...Option) App[T]

New create an App with a custom ContextFactory and additional 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
	// Res returns the underlying http.ResponseWriter
	Res() http.ResponseWriter

	// 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{})

	// 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 the most basic context of a incoming request and corresponding response

func BasicContext

func BasicContext(rw http.ResponseWriter, req *http.Request) Context

BasicContext context factory creating a basic Context implementation

type ContextFactory

type ContextFactory[T Context] func(rw http.ResponseWriter, req *http.Request) T

ContextFactory factory function for creating an extended Context

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[T Context] func(ctx T)

HandlerFunc handler func with Context as argument

type InjectFunc

type InjectFunc func(ctx context.Context, c Context) context.Context

InjectFunc inject function for component

type LifecycleFunc

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

LifecycleFunc lifecycle 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

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

	// Inject set inject function
	Inject(fn InjectFunc) Registration
}

Registration a 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)

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

	// Inject execute all inject funcs with [Context]
	Inject(c Context)

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

func NewRegistry

func NewRegistry() Registry