rest

Documentation

Index

• Variables
• type Middleware
  • func ToMiddleware(handler func(next http.Handler) http.Handler) Middleware
• type MiddlewaresConf
• type PrivateKeyConf
• type RestConf
• type Route
  • func WithMiddleware(middleware Middleware, rs ...Route) []Route
  • func WithMiddlewares(ms []Middleware, rs ...Route) []Route
• type RouteOption
  • func WithJwt(secret string) RouteOption
  • func WithJwtTransition(secret, prevSecret string) RouteOption
  • func WithMaxBytes(maxBytes int64) RouteOption
  • func WithPrefix(group string) RouteOption
  • func WithPriority() RouteOption
  • func WithSignature(signature SignatureConf) RouteOption
  • func WithTimeout(timeout time.Duration) RouteOption
• type RunOption
  • func WithChain(chn chain.Chain) RunOption
  • func WithCors(origin ...string) RunOption
  • func WithCustomCors(middlewareFn func(header http.Header), notAllowedFn func(http.ResponseWriter), ...) RunOption
  • func WithNotAllowedHandler(handler http.Handler) RunOption
  • func WithNotFoundHandler(handler http.Handler) RunOption
  • func WithRouter(router httpx.Router) RunOption
  • func WithTLSConfig(cfg *tls.Config) RunOption
  • func WithUnauthorizedCallback(callback handler.UnauthorizedCallback) RunOption
  • func WithUnsignedCallback(callback handler.UnsignedCallback) RunOption
• type Server
  • func MustNewServer(c RestConf, opts ...RunOption) *Server
  • func NewServer(c RestConf, opts ...RunOption) (*Server, error)
  • func (s *Server) AddRoute(r Route, opts ...RouteOption)
  • func (s *Server) AddRoutes(rs []Route, opts ...RouteOption)
  • func (s *Server) PrintRoutes()
  • func (s *Server) Routes() []Route
  • func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (s *Server) Start()
  • func (s *Server) Stop()
  • func (s *Server) Use(middleware Middleware)
• type SignatureConf

Variables

var ErrSignatureConfig = errors.New("bad config for Signature")

ErrSignatureConfig is an error that indicates bad config for signature.

Types

type Middleware

type Middleware func(next http.HandlerFunc) http.HandlerFunc

Middleware defines the middleware method.

func ToMiddleware

func ToMiddleware(handler func(next http.Handler) http.Handler) Middleware

ToMiddleware converts the given handler to a Middleware.

type MiddlewaresConf

type MiddlewaresConf struct {
	Trace      bool `json:",default=true"`
	Log        bool `json:",default=true"`
	Prometheus bool `json:",default=true"`
	MaxConns   bool `json:",default=true"`
	Breaker    bool `json:",default=true"`
	Shedding   bool `json:",default=true"`
	Timeout    bool `json:",default=true"`
	Recover    bool `json:",default=true"`
	Metrics    bool `json:",default=true"`
	MaxBytes   bool `json:",default=true"`
	Gunzip     bool `json:",default=true"`
}

MiddlewaresConf is the config of middlewares.

type PrivateKeyConf

type PrivateKeyConf struct {
	Fingerprint string
	KeyFile     string
}

A PrivateKeyConf is a private key config.

type RestConf

type RestConf struct {
	service.ServiceConf
	Host     string `json:",default=0.0.0.0"`
	Port     int
	CertFile string `json:",optional"`
	KeyFile  string `json:",optional"`
	Verbose  bool   `json:",optional"`
	MaxConns int    `json:",default=10000"`
	MaxBytes int64  `json:",default=1048576"`
	// milliseconds
	Timeout      int64         `json:",default=3000"`
	CpuThreshold int64         `json:",default=900,range=[0:1000]"`
	Signature    SignatureConf `json:",optional"`
	// There are default values for all the items in Middlewares.
	Middlewares MiddlewaresConf
}

A RestConf is a http service config. Why not name it as Conf, because we need to consider usage like:

type Config struct {
   zrpc.RpcConf
   rest.RestConf
}

if with the name Conf, there will be two Conf inside Config.

type Route

type Route struct {
	Method  string
	Path    string
	Handler http.HandlerFunc
}

A Route is a http route.

func WithMiddleware

func WithMiddleware(middleware Middleware, rs ...Route) []Route

WithMiddleware adds given middleware to given route.

func WithMiddlewares

func WithMiddlewares(ms []Middleware, rs ...Route) []Route

WithMiddlewares adds given middlewares to given routes.

type RouteOption

type RouteOption func(r *featuredRoutes)

RouteOption defines the method to customize a featured route.

func WithJwt

func WithJwt(secret string) RouteOption

WithJwt returns a func to enable jwt authentication in given route.

func WithJwtTransition

func WithJwtTransition(secret, prevSecret string) RouteOption

WithJwtTransition returns a func to enable jwt authentication as well as jwt secret transition. Which means old and new jwt secrets work together for a period.

func WithMaxBytes

func WithMaxBytes(maxBytes int64) RouteOption

WithMaxBytes returns a RouteOption to set maxBytes with the given value.

func WithPrefix

func WithPrefix(group string) RouteOption

WithPrefix adds group as a prefix to the route paths.

func WithPriority

func WithPriority() RouteOption

WithPriority returns a RunOption with priority.

func WithSignature

func WithSignature(signature SignatureConf) RouteOption

WithSignature returns a RouteOption to enable signature verification.

func WithTimeout

func WithTimeout(timeout time.Duration) RouteOption

WithTimeout returns a RouteOption to set timeout with given value.

type RunOption

type RunOption func(*Server)

RunOption defines the method to customize a Server.

func WithChain

func WithChain(chn chain.Chain) RunOption

WithChain returns a RunOption that uses the given chain to replace the default chain. JWT auth middleware and the middlewares that added by svr.Use() will be appended.

func WithCors

func WithCors(origin ...string) RunOption

WithCors returns a func to enable CORS for given origin, or default to all origins (*).

func WithCustomCors

func WithCustomCors(middlewareFn func(header http.Header), notAllowedFn func(http.ResponseWriter),
	origin ...string) RunOption

WithCustomCors returns a func to enable CORS for given origin, or default to all origins (*), fn lets caller customizing the response.

func WithNotAllowedHandler

func WithNotAllowedHandler(handler http.Handler) RunOption

WithNotAllowedHandler returns a RunOption with not allowed handler set to given handler.

func WithNotFoundHandler

func WithNotFoundHandler(handler http.Handler) RunOption

WithNotFoundHandler returns a RunOption with not found handler set to given handler.

func WithRouter

func WithRouter(router httpx.Router) RunOption

WithRouter returns a RunOption that make server run with given router.

func WithTLSConfig

func WithTLSConfig(cfg *tls.Config) RunOption

WithTLSConfig returns a RunOption that with given tls config.

func WithUnauthorizedCallback

func WithUnauthorizedCallback(callback handler.UnauthorizedCallback) RunOption

WithUnauthorizedCallback returns a RunOption that with given unauthorized callback set.

func WithUnsignedCallback

func WithUnsignedCallback(callback handler.UnsignedCallback) RunOption

WithUnsignedCallback returns a RunOption that with given unsigned callback set.

type Server

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

A Server is a http server.

func MustNewServer

func MustNewServer(c RestConf, opts ...RunOption) *Server

MustNewServer returns a server with given config of c and options defined in opts. Be aware that later RunOption might overwrite previous one that write the same option. The process will exit if error occurs.

func NewServer

func NewServer(c RestConf, opts ...RunOption) (*Server, error)

NewServer returns a server with given config of c and options defined in opts. Be aware that later RunOption might overwrite previous one that write the same option.

func (*Server) AddRoute

func (s *Server) AddRoute(r Route, opts ...RouteOption)

AddRoute adds given route into the Server.

func (*Server) AddRoutes

func (s *Server) AddRoutes(rs []Route, opts ...RouteOption)

AddRoutes add given routes into the Server.

func (*Server) PrintRoutes

func (s *Server) PrintRoutes()

PrintRoutes prints the added routes to stdout.

func (*Server) Routes

func (s *Server) Routes() []Route

Routes returns the HTTP routers that registered in the server.

func (*Server) ServeHTTP

func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP is for test purpose, allow developer to do a unit test with all defined router without starting an HTTP Server.

For example:

server := MustNewServer(...)
server.addRoute(...) // router a
server.addRoute(...) // router b
server.addRoute(...) // router c

r, _ := http.NewRequest(...)
w := httptest.NewRecorder(...)
server.ServeHTTP(w, r)
// verify the response

func (*Server) Start

func (s *Server) Start()

Start starts the Server. Graceful shutdown is enabled by default. Use proc.SetTimeToForceQuit to customize the graceful shutdown period.

func (*Server) Stop

func (s *Server) Stop()

Stop stops the Server.

func (*Server) Use

func (s *Server) Use(middleware Middleware)

Use adds the given middleware in the Server.

type SignatureConf

type SignatureConf struct {
	Strict      bool          `json:",default=false"`
	Expiry      time.Duration `json:",default=1h"`
	PrivateKeys []PrivateKeyConf
}

A SignatureConf is a signature config.