kit

README

Kit Framework

Kit is a framework for building production grade scalable service applications that can run in Kubernetes.

The main goal of Kit is to provide a proven starting point that reduces the repetitive tasks required for a new project. It is designed to follow (at least try to) idiomatic code and Go best practices. Collectively, the project lays out everything logically to minimize guess work and enable engineers to quickly maintain a mental model for the project.

Starting point

Starting building a new kit service is as simple as

// Main function.
// Everything start from here.
func main() {
	podName := config.LookupEnv("POD_NAME", id.NewGenerator("myapp").Generate())
	ctx := context.Background()
	
	// Initiate a logger with pre-configuration for production and telemetry.
	l, err := log.New()
	if err != nil {
		// in case we cannot create the logger, the app should immediately stop.
		panic(err)
	}
	// Replace the global logger with the Service scoped log.
	log.ReplaceGlobal(l)
	
	// Initialise the foundation and start the service
	foundation, err := kit.NewFoundation(podName, kit.WithLogger(l))
	if err != nil {
		l.Fatal(ctx, err.Error())
	}
	
	l.Info(ctx, "Starting service", log.String("pod.name", podName))

	// Start the service
	//
	// This service will be automatically configured to:
	// 1. Provide Observability information such as tracing, loging and metric
	// 2. Provide default /readyz and /healthz endpoint for readiness and liveness probe and profiling via /debug/pprof
	// 3. Setup for production setup
	// 4. Graceful shutdown
	if err := foundation.Serve(); err != nil {
		l.Error(ctx, "fail serving", log.Error(err))
	}
}

Add gRPC service and gRPC gateway

Foundation comes with integration with GRPC (GRPC gateway) out of the box. You can define your protobuf API in api folder. Once you generated the code via make proto-gen, you can start creating your application as shown below:

func main() {
	// Initialise the foundation
	foundation, err := kit.NewFoundation("myservice")
	if err != nil { 
		// handle error 
	}
  
	// Register the GRPC Server
	foundation.RegisterService(func(s *grpc.Server) {
    	// since in a closure, you only need to pass a RegisterServiceFunc
    	// with the proto Register App and the struct that implement the interfaces
    	// the underline implementation and setup of the GRPC server
    	// will be managed by the foundation.
		pb.RegisterMyAppServer(s, &myStruct{})
	})
  
	// Register the Service Handler in case you want to expose your GRPC service via HTTP
	// it use underneath grpc-gateway.
	// like RegisterService, RegisterServiceHandler takes a RegisterServiceHandlerFunc
	// with the proto Register App Handler and the underline implementation and setup
	// will be managed by the foundation.
	foundation.RegisterServiceHandler(func(gw *runtime.ServeMux, conn *grpc.ClientConn) {
		if err := pb.RegisterMyAppHandler(ctx, gw, conn); err != nil {
			// handle error
		}
	})
  
  	// Start the service
  	if err := foundation.Serve(); err != nil {
		// handle error
  	}
}

Documentation

Index

• type Foundation
  • func NewFoundation(name string, options ...Option) (*Foundation, error)
  • func (f *Foundation) RegisterHTTPHandler(path string, fn http.HandlerFunc, methods ...string)
  • func (f *Foundation) RegisterLiveness(fn func() (string, error))
  • func (f *Foundation) RegisterReadiness(fn func() (string, error))
  • func (f *Foundation) RegisterService(fn RegisterServiceFunc)
  • func (f *Foundation) RegisterServiceHandler(fn RegisterServiceHandlerFunc, muxOpts ...runtime.ServeMuxOption)
  • func (f *Foundation) Serve() error
• type FoundationOptions
• type Option
  • func EnableCors() Option
  • func WithCorsOptions(opts cors.Options) Option
  • func WithGrpcAddr(addr string) Option
  • func WithGrpcServerOptions(opts ...grpc.ServerOption) Option
  • func WithHTTPAddr(addr string) Option
  • func WithHTTPReadTimeout(timeout time.Duration) Option
  • func WithHTTPWriteTimeout(timeout time.Duration) Option
  • func WithLogger(logger *log.Logger) Option
• type RegisterServiceFunc
• type RegisterServiceHandlerFunc

Types

type Foundation

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

Foundation provides a convenient way to build new services.

Foundation aims to provide a set of common boilerplate code for creating a production ready GRPC server and HTTP mux router (with grpc-gateway capabilities) and custom HTTP endpoints.

func NewFoundation

func NewFoundation(name string, options ...Option) (*Foundation, error)

NewFoundation creates a new foundation service. A list of configurable option can be passed as option and as env Variable eg:

// Setting up grpc server via option
kit.NewFoundation("myservice", kit.WithGrpcAddr("localhost:8089"))

// Setting up grpc server via Env
FOUNDATION_GRPC_ADDRESS=localhost:8089
kit.NewFoundation("myservice")

Order of priority for option is as follows:

1- Default configuration
2- Env variable
3- Options

func (*Foundation) RegisterHTTPHandler

func (f *Foundation) RegisterHTTPHandler(path string, fn http.HandlerFunc, methods ...string)

RegisterHTTPHandler registers a custom HTTP handler.

func (*Foundation) RegisterLiveness

func (f *Foundation) RegisterLiveness(fn func() (string, error))

RegisterLiveness register a liveness function for /healthz

Many applications running for long periods of time eventually transition to broken states, and cannot recover except by being restarted. Kubernetes provides liveness probes to detect and remedy such situations.

func (*Foundation) RegisterReadiness

func (f *Foundation) RegisterReadiness(fn func() (string, error))

RegisterReadiness register a readiness function for /readyz

Sometimes, applications are temporarily unable to serve traffic. For example, an application might need to load a large amount of data or a large number of configuration files during startup. In such instances, we don’t want to kill the application, but we don’t want to send it requests either.

func (*Foundation) RegisterService

func (f *Foundation) RegisterService(fn RegisterServiceFunc)

RegisterService registers a grpc service handler.

func (*Foundation) RegisterServiceHandler

func (f *Foundation) RegisterServiceHandler(fn RegisterServiceHandlerFunc, muxOpts ...runtime.ServeMuxOption)

RegisterServiceHandler registers a grpc-gateway service handler.

func (*Foundation) Serve

func (f *Foundation) Serve() error

Serve configure and start serving request for the foundation service.

type FoundationOptions

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

FoundationOptions provides a set of configurable options for Foundation.

type Option

type Option func(*FoundationOptions)

Option defines a Foundation option.

func EnableCors

func EnableCors() Option

EnableCors will add cors support to the http server.

func WithCorsOptions

func WithCorsOptions(opts cors.Options) Option

WithCorsOptions defines http server cors options.

func WithGrpcAddr

func WithGrpcAddr(addr string) Option

WithGrpcAddr defines a GRPC server host and port.

func WithGrpcServerOptions

func WithGrpcServerOptions(opts ...grpc.ServerOption) Option

WithGrpcServerOptions defines GRPC server options.

func WithHTTPAddr

func WithHTTPAddr(addr string) Option

WithHTTPAddr defines a HTTP server host and port.

func WithHTTPReadTimeout

func WithHTTPReadTimeout(timeout time.Duration) Option

WithHTTPReadTimeout defines read timeout for the HTTP server.

func WithHTTPWriteTimeout

func WithHTTPWriteTimeout(timeout time.Duration) Option

WithHTTPWriteTimeout defines write timeout for the HTTP server.

func WithLogger

func WithLogger(logger *log.Logger) Option

type RegisterServiceFunc

type RegisterServiceFunc func(s *grpc.Server)

RegisterServiceFunc represents a function for registering a grpc service handler.

type RegisterServiceHandlerFunc

type RegisterServiceHandlerFunc func(gw *runtime.ServeMux, conn *grpc.ClientConn)

RegisterServiceHandlerFunc represents a function for registering a grpc gateway service handler.