service

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 28, 2023 License: Apache-2.0 Imports: 14 Imported by: 0

README

service

The intention behind the service package is to allow a client to get a service up and running by passing in a configuration struct.

Supported features

  • readiness handler (can be required by k8s)
  • CORS - default configuration if enabled or supplied override configuration
  • Logging.
  • The default prometheus metrics endpoint.
  • Listening on HTTP or HTTPS.
  • Rate limiting.
  • Adding new handlers.
  • Adding new middleware.
  • Adding an auth handler.
API
//NewService will setup a new service based on the config and return this service.  
func NewService(cfg *Config) (*Service, error)

//Run will run the service in the foreground and exit when the HTTP server exits  
func (s *Service) Run() error
Types
//Config will hold the configuration of the service.  
type Config struct {  
  ListenAddress      string                   //Address in the format [host/ip]:port. Mandatory  
  LogLevel           string                   //INFO,FATAL,ERROR,WARN, DEBUG, TRACE  
  Cors               *CorsConfig              //Optional cors config  
  ReadinessCheck     bool                     //Set to true to add a readiness handler at /readiness.  
  Handlers           []Handler                //Array of handlers. N.B. At least one handler is required.  
  CertConfig         *ServerCertificateConfig //Optional TLS configuration  
  RateLimit          *RateLimitConfig         //Optional rate limiting config  
  MiddlewareHandlers []MiddlewareHandler      //Optional middleware handlers which will be run on every request  
  Metrics            bool                     //Optional. If true a prometheus metrics endpoint will be exposed at /metrics/  
  ErrorHandler       *MiddlewareHandler       //Optional. If true a handler will be added to the end of the chain.
}  
  
// Handler will hold all the callback handlers to be registered. N.B. gin will be used.
type Handler struct {
	Method          string                  // HTTP method or service.AnyMethod to support all limits.
	Path            string                  // The path the endpoint runs on.
	Group           string                  // Optional - specify a group (used to control which middlewares will run)
	Handler         func(c *gin.Context)    // The handler to be used.
	RateLimitConfig *HandlerRateLimitConfig // Optional rate limiting config specifically for the handler.
}
  
//MiddlewareHandler will hold all the middleware and whether
type MiddlewareHandler struct {
	Groups  []string             //Optional - what group should this middleware run on. Empty means the default route.
	Handler func(c *gin.Context) //The handler to be used.
}  
  
//ServerCertificateConfig holds detail of the certificate config to be used  
type ServerCertificateConfig struct {  
  CertificateFile string //The TLS certificate file.  
  KeyFile         string //The TLS private key file.  
}  
  
//RateLimitConfig specifies the rate limiting config
type RateLimitConfig struct {
	Groups []string //Optional - which group(s) should the rate limiting run on. Empty means the default route.
	Limit  int      //The number of requests allowed within the timeframe.
	Within int      //The timeframe(seconds) the requests are allowed in.
}

//CorsConfig specifies the CORS related config
type CorsConfig struct {
	Groups      []string     //Optional - which group(s) should the CORS config run on. Empty means the default route.
	Enabled     bool         //Whether CORS is enabled or not.
	OverrideCfg *cors.Config //Optional. This is only required if you do not want to use the default CORS configuration.
} 

// HandlerRateLimitConfig holds the rate limiting config fo a sepecific handler.
type HandlerRateLimitConfig struct {
	Limit  int // The number of requests allowed within the timeframe.
	Within int // The timeframe(seconds) the requests are allowed in.
}
  
//Service will be the actual structure returned.  
type Service struct {  
  *http.Server //Anonymous embedded struct to allow access to http server methods.  
  config *Config //The config.  
}
Notes
  • The cors config and the handlers are based on the gin framework : https://github.com/gin-gonic/gin.
  • Rate limiting is done by the library github.com/cnjack/throttle.
  • Rate limiting can be added to a handler or on a per group basis.
  • The group principle is based on Gin routergroups. The idea behind it is that not all middleware needs to run on all requests so the middleware in a group will only run against an endpoint in that group. This is applied to cors, rate limiting and any middleware in general.
  • See internal/examples/service/main.go for an example of how to use the service package to generate a service.

TODO: - Consider adding GRPC.

  • Consider adding GraphQL.
  • Flesh out more with logging.
  • Look at potentially not using gin (it does the work for you so not a high priority).

Documentation

Overview

Package service provides service-related facilities.

Index

Constants

View Source
const (
	// AnyMethod should be passed when a handler wants to support any HTTP method.
	AnyMethod = "Any"
	// ReadinessEndpoint is the default URL for a readiness endpoint.
	ReadinessEndpoint = "/readiness"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Config

type Config struct {
	ListenAddress      string                   // Address in the format [host/ip]:port. Mandatory.
	LogLevel           string                   // INFO,FATAL,ERROR,WARN, DEBUG, TRACE.
	Cors               *CorsConfig              // Optional cors config.
	ReadinessCheck     bool                     // Set to true to add a readiness handler at /readiness.
	Handlers           []Handler                // Array of handlers.
	CertConfig         *ServerCertificateConfig // Optional TLS configuration.
	RateLimit          *RateLimitConfig         // Optional rate limiting config.
	MiddlewareHandlers []MiddlewareHandler      // Optional middleware handlers which will be run on every request.
	Metrics            bool                     // Optional. If true add a prometheus endpoint.
	ErrorHandler       *MiddlewareHandler       // Optional. If true a handler will be added to the end of the chain.
}

Config will hold the configuration of the service.

type CorsConfig

type CorsConfig struct {
	Groups      []string     // Optional - which group(s) should the CORS config run on. Empty means the default route.
	Enabled     bool         // Whether CORS is enabled or not.
	OverrideCfg *cors.Config // Optional. Only required if you do not want to use the default CORS configuration.
}

CorsConfig specifies the CORS related config.

type Handler

type Handler struct {
	Method          string                  // HTTP method or service.AnyMethod to support all limits.
	Path            string                  // The path the endpoint runs on.
	Group           string                  // Optional - specify a group (used to control which middlewares will run)
	Handler         func(c *gin.Context)    // The handler to be used.
	RateLimitConfig *HandlerRateLimitConfig // Optional rate limiting config specifically for the handler.
}

Handler will hold all the callback handlers to be registered. N.B. gin will be used.

type HandlerRateLimitConfig added in v0.3.0

type HandlerRateLimitConfig struct {
	Limit  int // The number of requests allowed within the timeframe.
	Within int // The timeframe(seconds) the requests are allowed in.
}

HandlerRateLimitConfig holds the rate limiting config fo a sepecific handler.

type MiddlewareHandler

type MiddlewareHandler struct {
	Groups  []string             // Optional - what group should this middleware run on. Empty means the default route.
	Handler func(c *gin.Context) // The handler to be used.
}

MiddlewareHandler will hold a middleware handler and the groups on which it should be registered.

type RateLimitConfig

type RateLimitConfig struct {
	Groups []string // Optional - which group(s) should the rate limiting run on. Empty means the default route.
	Limit  int      // The number of requests allowed within the timeframe.
	Within int      // The timeframe(seconds) the requests are allowed in.
}

RateLimitConfig specifies the rate limiting config.

type ServerCertificateConfig

type ServerCertificateConfig struct {
	CertificateFile string // The TLS certificate file.
	KeyFile         string // The TLS private key file.
}

ServerCertificateConfig holds detail of the certificate config to be used.

type Service

type Service struct {
	*http.Server // Anonymous embedded struct to allow access to http server methods.
	// contains filtered or unexported fields
}

Service will be the actual structure returned.

func NewService

func NewService(cfg *Config) (*Service, error)

NewService will setup a new service based on the config and return this service.

func (*Service) Run

func (s *Service) Run() error

Run will run the service in the foreground and exit when the server exits.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL