servekit

README

The servkit helps to build APIs.

Is a set of well-tested (or not well 🤭) reusable components to speedup day-to-day development of HTTP and gRPC APIs.

Docs

The code should be very straightforward to read, but you always can check the go docs.

On the shoulders of giants

• github.com/VictoriaMetrics/metric
• github.com/mattn/go-sqlite3
• github.com/go-chi/chi

Contributing guidelines

You can find our guidelines here.

License

MIT License

Documentation

Index

• type Error
  • func (e Error) Error() string
• type GRPCEndpointRegistrator
• type Listener
• type ListenerGRPC
  • func NewListenerGRPC(addr string, options ...OptionGRPC[grpcConfig]) (*ListenerGRPC, error)
  • func (l *ListenerGRPC) Mount(handlers ...GRPCEndpointRegistrator)
  • func (l *ListenerGRPC) Serve(ctx context.Context) error
• type ListenerHTTP
  • func NewListenerHTTP(addr string, options ...OptionHTTP[httpConfig]) (*ListenerHTTP, error)
  • func (l *ListenerHTTP) Mount(route string, handler http.Handler, middlewares ...midkit.Middleware)
  • func (l *ListenerHTTP) Serve(ctx context.Context) error
• type OptionGRPC
  • func WithStreamInterceptors(interceptors ...midkit.StreamInterceptor) OptionGRPC[grpcConfig]
  • func WithUnaryInterceptors(interceptors ...midkit.UnaryInterceptor) OptionGRPC[grpcConfig]
• type OptionHTTP
  • func HTTPServerIdleTimeout(t time.Duration) OptionHTTP[httpTimeoutsConfig]
  • func HTTPServerReadHeaderTimeout(t time.Duration) OptionHTTP[httpTimeoutsConfig]
  • func HTTPServerReadTimeout(t time.Duration) OptionHTTP[httpTimeoutsConfig]
  • func HTTPServerWriteTimeout(t time.Duration) OptionHTTP[httpTimeoutsConfig]
  • func HealthCheckAccessLog(enable bool) OptionHTTP[healthConfig]
  • func HealthCheckMetricsForEndpoint(enable bool) OptionHTTP[healthConfig]
  • func HealthCheckRoute(route string) OptionHTTP[healthConfig]
  • func HealthChecker(checker hc.HealthChecker) OptionHTTP[healthConfig]
  • func MetricsAccessLog(enable bool) OptionHTTP[metricsConfig]
  • func MetricsMetricsForEndpoint(enable bool) OptionHTTP[metricsConfig]
  • func MetricsRoute(route string) OptionHTTP[metricsConfig]
  • func WithCORS(options ...OptionHTTP[corsConfig]) OptionHTTP[httpConfig]
  • func WithGlobalMiddlewares(middlewares ...midkit.Middleware) OptionHTTP[httpConfig]
  • func WithHTTPServerTimeouts(options ...OptionHTTP[httpTimeoutsConfig]) OptionHTTP[httpConfig]
  • func WithHealthCheck(options ...OptionHTTP[healthConfig]) OptionHTTP[httpConfig]
  • func WithLogger(logger *slog.Logger) OptionHTTP[httpConfig]
  • func WithMetrics(options ...OptionHTTP[metricsConfig]) OptionHTTP[httpConfig]
  • func WithProfiler(cfg pprofConfig) OptionHTTP[httpConfig]
  • func WithTLS(cert, key string) OptionHTTP[httpConfig]
• type Server
  • func NewServer(logger *slog.Logger) *Server
  • func (s *Server) RegisterListener(name string, listener Listener)
  • func (s *Server) Serve(ctx context.Context) error

Types

type Error

type Error string

Error represents a package level error. Implements builtin error interface.

const (
	// ErrGracefullyShutdown represents an error message
	// indicating the failure to gracefully shut down a listener.
	ErrGracefullyShutdown Error = "shut down listener gracefully"

	// ErrCertPathRequired represents an error message
	// indicating that a certificate file path is required.
	ErrCertPathRequired Error = "certificate file path is required"

	// ErrPrivateKeyPathRequired represents an error message
	// indicating that a private key file path is required.
	ErrPrivateKeyPathRequired Error = "private key file path is required"
)

func (Error) Error

func (e Error) Error() string

type GRPCEndpointRegistrator

type GRPCEndpointRegistrator interface {
	Mount(server *grpc.Server)
}

GRPCEndpointRegistrator abstracts a mechanics of registering the gRPC service in the gRPC server.

type Listener

type Listener interface {
	// Serve runs the listener, handling incoming requests. It takes a context as an argument
	// and returns an error if an error occurs while serving requests.
	Serve(ctx context.Context) error
}

Listener is an interface that represents a listener which can serve requests. It requires the implementation of the Serve method that takes a context and returns an error.

type ListenerGRPC

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

ListenerGRPC represents a struct that encapsulates a gRPC server listener.

func NewListenerGRPC

func NewListenerGRPC(addr string, options ...OptionGRPC[grpcConfig]) (*ListenerGRPC, error)

NewListenerGRPC creates a new ListenerGRPC instance by creating a gRPC listener using a given address. It applies all the options to a default `applyOptionsGRPC` instance and sets the server options with the provided unary and stream interceptors. Finally, it returns the ListenerGRPC instance and potential error.

func (*ListenerGRPC) Mount

func (l *ListenerGRPC) Mount(handlers ...GRPCEndpointRegistrator)

Mount the given handlers to the listener gRPC server.

func (*ListenerGRPC) Serve

func (l *ListenerGRPC) Serve(ctx context.Context) error

type ListenerHTTP

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

func NewListenerHTTP

func NewListenerHTTP(addr string, options ...OptionHTTP[httpConfig]) (*ListenerHTTP, error)

NewListenerHTTP creates a new ListenerHTTP with the specified address and options. The options parameter is a variadic argument that accepts functions of type OptionHTTP. The ListenerHTTP instance is returned, which can be used to mount routes and start serving requests.

func (*ListenerHTTP) Mount

func (l *ListenerHTTP) Mount(route string, handler http.Handler, middlewares ...midkit.Middleware)

func (*ListenerHTTP) Serve

func (l *ListenerHTTP) Serve(ctx context.Context) error

type OptionGRPC

type OptionGRPC[T grpcConfig] func(o *T)

OptionGRPC implements functional options pattern for the ListenerGRPC type. Represents a function which receive a pointer to the generic struct that represents a part of ListenerGRPC configuration and changes it default values to the given ones.

See the applyOptionsGRPC function to understand the configuration behaviour. OptionGRPC functions should only be passed to ListenerGRPC constructor function NewListenerGRPC.

func WithStreamInterceptors

func WithStreamInterceptors(interceptors ...midkit.StreamInterceptor) OptionGRPC[grpcConfig]

WithStreamInterceptors is a function that takes a variable number of StreamInterceptor functions and returns an OptionGRPC[grpcConfig]. This function is used to add StreamInterceptors to the streamInterceptors field of the grpcConfig struct.

func WithUnaryInterceptors

func WithUnaryInterceptors(interceptors ...midkit.UnaryInterceptor) OptionGRPC[grpcConfig]

WithUnaryInterceptors is a function that takes a variable number of UnaryInterceptor functions and returns an OptionGRPC[grpcConfig]. This function is used to add UnaryInterceptors to the unaryInterceptors field of the grpcConfig struct.

type OptionHTTP

type OptionHTTP[T httpConfig | httpTimeoutsConfig | healthConfig | metricsConfig | corsConfig | pprofConfig] func(o *T)

OptionHTTP implements functional options pattern for the ListenerHTTP type. Represents a function which receive a pointer to the generic struct that represents a part of ListenerHTTP configuration and changes it default values to the given ones.

See the applyOptionsHTTP function to understand the configuration behaviour. OptionHTTP functions should only be passed to ListenerHTTP constructor function NewListenerHTTP.

func HTTPServerIdleTimeout

func HTTPServerIdleTimeout(t time.Duration) OptionHTTP[httpTimeoutsConfig]

HTTPServerIdleTimeout sets the http.Server IdleTimeout.

func HTTPServerReadHeaderTimeout

func HTTPServerReadHeaderTimeout(t time.Duration) OptionHTTP[httpTimeoutsConfig]

HTTPServerReadHeaderTimeout sets the http.Server ReadHeaderTimeout.

func HTTPServerReadTimeout

func HTTPServerReadTimeout(t time.Duration) OptionHTTP[httpTimeoutsConfig]

HTTPServerReadTimeout sets the http.Server ReadTimeout.

func HTTPServerWriteTimeout

func HTTPServerWriteTimeout(t time.Duration) OptionHTTP[httpTimeoutsConfig]

HTTPServerWriteTimeout sets the http.Server WriteTimeout.

func HealthCheckAccessLog

func HealthCheckAccessLog(enable bool) OptionHTTP[healthConfig]

HealthCheckAccessLog represents an optional function for WithHealthCheck function. If passed to the WithHealthCheck, will set the ServerSettings.health.accessLogsEnabled to true.

func HealthCheckMetricsForEndpoint

func HealthCheckMetricsForEndpoint(enable bool) OptionHTTP[healthConfig]

HealthCheckMetricsForEndpoint represents an optional function for WithHealthCheck function. If passed to the WithHealthCheck, will set the ServerSettings.health.metricsForEndpointEnabled to true.

func HealthCheckRoute

func HealthCheckRoute(route string) OptionHTTP[healthConfig]

HealthCheckRoute represents an optional function for WithHealthCheck function. If passed to the WithHealthCheck, will set the ServerSettings.health.route.

func HealthChecker

func HealthChecker(checker hc.HealthChecker) OptionHTTP[healthConfig]

HealthChecker represents an optional function for WithHealthCheck function. If passed to the WithHealthCheck, will set the ServerSettings.health.healthChecker.

func MetricsAccessLog

func MetricsAccessLog(enable bool) OptionHTTP[metricsConfig]

MetricsAccessLog represents an optional function for WithMetrics function. If passed to the WithMetrics, will set the ServerSettings.health.accessLogsEnabled to true.

func MetricsMetricsForEndpoint

func MetricsMetricsForEndpoint(enable bool) OptionHTTP[metricsConfig]

MetricsMetricsForEndpoint represents an optional function for WithMetrics function. If passed to the WithMetrics, will set the ServerSettings.health.metricsForEndpointEnabled to true.

func MetricsRoute

func MetricsRoute(route string) OptionHTTP[metricsConfig]

MetricsRoute represents an optional function for WithMetrics function. If passed to the WithMetrics, will set the ServerSettings.health.route.

func WithCORS

func WithCORS(options ...OptionHTTP[corsConfig]) OptionHTTP[httpConfig]

WithCORS configures the CORS httpConfig for Houston API routes.

func WithGlobalMiddlewares

func WithGlobalMiddlewares(middlewares ...midkit.Middleware) OptionHTTP[httpConfig]

WithGlobalMiddlewares sets given middlewares as router-wide middlewares. Means that they will be applied to each server endpoint.

func WithHTTPServerTimeouts

func WithHTTPServerTimeouts(options ...OptionHTTP[httpTimeoutsConfig]) OptionHTTP[httpConfig]

WithHTTPServerTimeouts configures the HTTP listener httpTimeoutsConfig. Receives the following option to configure the endpoint: - HTTPServerReadHeaderTimeout - sets the http.Server ReadHeaderTimeout. - HTTPServerReadTimeout - sets the http.Server ReadTimeout. - HTTPServerWriteTimeout - sets the http.Server WriteTimeout. - HTTPServerIdleTimeout - sets the http.Server IdleTimeout.

func WithHealthCheck

func WithHealthCheck(options ...OptionHTTP[healthConfig]) OptionHTTP[httpConfig]

WithHealthCheck turns on the health check endpoint. Receives the following option to configure the endpoint: - HealthChecker - to change the healthChecker implementation. - HealthCheckRoute - to set the endpoint route. - HealthCheckAccessLog - to enable access log for endpoint. - HealthCheckMetricsForEndpoint - to enable metrics collection for endpoint.

func WithLogger

func WithLogger(logger *slog.Logger) OptionHTTP[httpConfig]

WithLogger sets the server logger.

func WithMetrics

func WithMetrics(options ...OptionHTTP[metricsConfig]) OptionHTTP[httpConfig]

WithMetrics turns on the metrics endpoint. Receives the following option to configure the endpoint: - MetricsRoute - to set the endpoint route. - MetricsAccessLog - to enable access log for endpoint. - MetricsMetricsForEndpoint - to enable metrics collection for endpoint.

func WithProfiler

func WithProfiler(cfg pprofConfig) OptionHTTP[httpConfig]

WithProfiler turns on the profiler endpoint.

func WithTLS

func WithTLS(cert, key string) OptionHTTP[httpConfig]

WithTLS sets the TLS certificate and key to be used by the HTTP server. The certificate and key must be provided as strings containing the file paths. Note that this function is an OptionHTTP for httpConfig and should be passed to the NewServer constructor.

type Server

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

Server is a type that represents a server that holds a map of listeners.

func NewServer

func NewServer(logger *slog.Logger) *Server

NewServer creates a new Server instance with an empty listeners map and returns a pointer to the created Server.

func (*Server) RegisterListener

func (s *Server) RegisterListener(name string, listener Listener)

RegisterListener adds a listener to the Server's listeners map.

func (*Server) Serve

func (s *Server) Serve(ctx context.Context) error

Serve runs the server and serves requests from all listeners. It creates an error group and a listener context. It iterates through the listeners map and starts a goroutine for each listener. Each goroutine retries calling the listener's Serve method until it succeeds or the retry limit is reached. If the Serve method returns an error, it logs an error message and checks if the error is retryable. If the context is canceled, it returns the context error. If the retry limit is reached, it returns ErrRetryLimitReached. Finally, it waits for all goroutines to complete and returns any error encountered during serving.