ufx

README

uFx

A minimalist mesh-native microservice framework with Fx

Credits

GUO YANKE, MIT License

Documentation

Index

• Constants
• Variables
• func Bind[T any](c Context) (o T)
• func ProvideConfFromYAMLFile(name string) fx.Option
• func ProvideEmptyConf() fx.Option
• func SetupOTEL() (err error)
• type CheckerFunc
• type Conf
  • func (c Conf) Bind(data interface{}, keys ...string) (err error)
• type Context
• type HandlerFunc
• type Prober
  • func NewProber(params ProberParams) Prober
• type ProberParams
  • func ProberParamsFromConf(conf Conf) (params ProberParams, err error)
• type Router
  • func NewRouter(opts RouterParams) Router
• type RouterParams
  • func RouterParamsFromConf(conf Conf) (params RouterParams, err error)
• type Server
  • func NewServer(opts ServerOptions) Server
• type ServerOptions
• type ServerParams
  • func ServerParamsFromConf(conf Conf) (opts ServerParams, err error)

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"
)

Variables

var Module = fx.Module(
	"ufx",
	fx.Provide(
		ProberParamsFromConf,
		RouterParamsFromConf,
		ServerParamsFromConf,
		NewProber,
		NewRouter,
		NewServer,
	),
	fx.Invoke(SetupOTEL),
	fx.Invoke(func(Server) {}),
)

Functions

func Bind

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

Bind a generic version of [Context.Bind]

demo:

	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 ProvideConfFromYAMLFile

func ProvideConfFromYAMLFile(name string) fx.Option

ProvideConfFromYAMLFile provides a Conf from a YAML file

func ProvideEmptyConf

func ProvideEmptyConf() fx.Option

ProvideEmptyConf provides an empty Conf

func SetupOTEL

func SetupOTEL() (err error)

SetupOTEL setup opentelemetry

Types

type CheckerFunc

type CheckerFunc func(ctx context.Context) error

type Conf

type Conf map[string]any

Conf is the configuration type

func (Conf) Bind

func (c Conf) Bind(data interface{}, keys ...string) (err error)

Bind binds the configuration to the given data structure, supports json tags

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 HandlerFunc

type HandlerFunc func(c Context)

HandlerFunc handler func with Context as argument

type Prober

type Prober interface {
	// CheckLiveness check liveness
	CheckLiveness() bool

	// CheckReadiness check readiness
	CheckReadiness(ctx context.Context) (s string, failed bool)

	// AddChecker add checker
	AddChecker(name string, fn CheckerFunc)
}

Prober is a check prober

func NewProber

func NewProber(params ProberParams) Prober

type ProberParams

type ProberParams struct {
	Readiness struct {
		Cascade int `json:"cascade" default:"5" validate:"min=1"`
	} `json:"readiness"`
}

func ProberParamsFromConf

func ProberParamsFromConf(conf Conf) (params ProberParams, err error)

type Router

type Router interface {
	http.Handler

	HandleFS(root string, f fs.FS)

	HandleFunc(pattern string, fn HandlerFunc)
}

Router router interface

func NewRouter

func NewRouter(opts RouterParams) Router

type RouterParams

type RouterParams struct {
	Concurrency int `json:"concurrency" default:"128" validate:"min=1"`
	Logging     struct {
		Response bool `json:"response"`
		Request  bool `json:"request"`
	} `json:"logging"`
}

func RouterParamsFromConf

func RouterParamsFromConf(conf Conf) (params RouterParams, err error)

type Server

type Server interface {
	// Handler inherit [http.Handler]
	http.Handler
}

Server the main interface of [summer]

func NewServer

func NewServer(opts ServerOptions) Server

NewServer create an Server with [Option]

type ServerOptions

type ServerOptions struct {
	fx.In
	fx.Lifecycle

	ServerParams
	Prober
	Router
}

type ServerParams

type ServerParams struct {
	Listen string `json:"listen" default:":8080" validate:"required"`

	Path struct {
		Readiness string `json:"readiness" default:"/debug/ready" validate:"required"`
		Liveness  string `json:"liveness" default:"/debug/alive" validate:"required"`
		Metrics   string `json:"metrics" default:"/debug/metrics" validate:"required"`
	} `json:"path"`

	Delay struct {
		Start time.Duration `json:"start" default:"3s"`
		Stop  time.Duration `json:"stop" default:"3s"`
	} `json:"delay"`
}

ServerParams params

func ServerParamsFromConf

func ServerParamsFromConf(conf Conf) (opts ServerParams, err error)

ServerParamsFromConf create ServerParams from flag.FlagSet