rest

Documentation

Index

• Variables
• type Middleware
  • func ToMiddleware(handler func(next http.Handler) http.Handler) Middleware
• 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 interface{}) RouteOption
  • func WithJwtTransition(secret interface{}, prevSecret interface{}) 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 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) 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 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"`
}

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 interface{}) RouteOption

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

func WithJwtTransition

func WithJwtTransition(secret interface{}, prevSecret interface{}) 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 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) 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.