Documentation
¶
Overview ¶
Package service unifies how our HTTP services run to deduplicate code between different microservices. The common Service struct should be embedded into custom server implementations and it should be registered with a Server that implements the routes and handler functionality. The Service struct handles log initialization, the construction and management of the http Server, the construction and management of a gin Engine for multiplexing, and the liveness and readiness probes for Kubernetes.
Index ¶
- Variables
- type Initializer
- type Option
- type Preparer
- type Server
- func (s *Server) IsHealthy() bool
- func (s *Server) IsReady() bool
- func (s *Server) Register(service Service)
- func (s *Server) Serve() (err error)
- func (s *Server) SetHealth(health bool)
- func (s *Server) Shutdown(ctx context.Context) (err error)
- func (s *Server) StartTime() time.Time
- func (s *Server) URL() string
- type Service
- type Starter
Constants ¶
This section is empty.
Variables ¶
var (
ErrNoServiceRegistered = errors.New("no service has been registered with the server")
)
Functions ¶
This section is empty.
Types ¶
type Initializer ¶
type Initializer interface {
// Initialize is called before the server is in a live state and the server is not
// serving any requests (unhealthy, no liveness probes) and is the first possible
// entry point to the service interface. If an error is returned from Initialize,
// the server will not start at all.
Initialize() error
}
Initializer services want to do work before the server is able to serve liveness probes (e.g. there is no http server running at all). It is strongly recommended that services specify Setup() instead of Initialize() unless work is needed to done in a non-live state for some reason.
type Option ¶
type Option func(*options)
Option allows users to set optional arguments on the server when creating it.
func WithRouter ¶
func WithServer ¶
type Preparer ¶
type Preparer interface {
// Setup is called after initialize and after the server has started serving
// liveness probes (e.g. it is healthy but not ready). It is called prior to routes
// and is intended for more general setup and connection to databases and other
// resources. If an error is returned, the server will shutdown and will not proceed
// with its startup. Retry logic to delay readiness should be added to this method.
Setup() error
}
Preparer services want to do work before the server is started up such as connecting to databases or other external resources.
type Server ¶
Server implements common functionality for all service implementations that use Gin. Users should create a new server then register their service with the server in order to serve the server to respond to requests. After the server is created when the user calls its serve method, the server uses the registered service as it transitions through startup and shutdown states. Briefly those states are:
Initialize: called before the server is started (unhealthy, no liveness probes) Setup: called after the server is started but before routes are setup (healthy, not ready) Routes: called after setup and is intended to setup service routes (healthy, not ready) Started: called after the server is in a ready state (healthy, ready) Shutdown: called after the server is shutdown to cleanup the service (unhealthy, no liveness probes)
func (*Server) Shutdown ¶
Shutdown the server gracefully (usually called by OS signal) but can be called by other triggers or manually during the test.
type Service ¶
type Service interface {
// Routes is called once the server is up and running and is in a live state but
// before it is in a ready state. The intended use case of this method is for the
// Service to specify its own middleware, routes, and handlers on the router, which
// is the majority of what differentiates a service from the main server.
// If an error is returned, the error will shutdown the server and stop startup.
Routes(router *gin.Engine) error
// Stop is called after the http server has gracefully concluded serving and the
// service is in a not ready, not healthy state. This method should be used to
// clean up connections to databases, close resources properly, etc. Note that the
// context may have a deadline on it before the server is terminated.
// If an error is returned, the error will be reported to the caller of Serve().
Stop(ctx context.Context) error
}
Service specifies the methods that a service implementation for a specific microservice needs to implement in order to be registered with the http server. The simplest services only need to specify the Service interface in order to create a quickly working service!
type Starter ¶
type Starter interface {
// Started is called after the server is serving and ready, after the Routes method
// has been called. Errors returned from this function will cause the server to
// shutdown will will have the effect of calling the services Shutdown method as
// well. Any errors returned from shutdown or this method are returned as a
// multierror to report everything that happened in the error process. This method
// is generally used for logging or booting up background routines and is a good
// choice for work that needs to be done that is error prone but may not affect the
// service or the ability of the service to handle requests.
Started() error
}
Starter services want to do work (usually logging or booting up background routines) when the server is started up and ready.
Source Files