service

package
v0.12.5 Latest Latest
Warning

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

Go to latest
Published: Jan 25, 2024 License: BSD-3-Clause Imports: 14 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
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 WithMode

func WithMode(mode string) Option

func WithRouter

func WithRouter(router *gin.Engine) Option

func WithServer

func WithServer(srv *http.Server) Option

func WithTLS added in v0.10.0

func WithTLS(conf *tls.Config) Option

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

type Server struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

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 New

func New(addr string, opts ...Option) *Server

func (*Server) IsHealthy

func (s *Server) IsHealthy() bool

IsHealthy returns whether the status probe is healthy or not.

func (*Server) IsReady

func (s *Server) IsReady() bool

IsReady returns whether the status probe is ready or not.

func (*Server) Register

func (s *Server) Register(service Service)

func (*Server) Serve

func (s *Server) Serve() (err error)

Serve API requests while listening on the specified bind address.

func (*Server) SetHealth

func (s *Server) SetHealth(health bool)

SetHealth is used by tests to set the health of the server

func (*Server) Shutdown

func (s *Server) Shutdown(ctx context.Context) (err error)

Shutdown the server gracefully (usually called by OS signal) but can be called by other triggers or manually during the test.

func (*Server) StartTime

func (s *Server) StartTime() time.Time

StartTime returns the time that the server started.

func (*Server) URL

func (s *Server) URL() string

URL returns the URL of the server determined by the socket addr.

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.

Jump to

Keyboard shortcuts

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