quark

README

quark-go

Quark-go is a quark size (meaning very very small) toolbelt for building microservices in golang.

Important: Library requires Golang 1.8+! Work in progress! Some interfaces could be changed!

Goals

The goal of the project is to help quickly build microservices using distributed programming best practices and tools which are best in the class (choice is subjective). Common techniques and components are at disposal of a developer who should be focus more on business logic instead of tweaking and finding right tools to do the job.

Quark-go is very extensible and allows to implement custom providers for all specified features below. It is not the goal of the project to support all available tools, configurations and components on the market. Project is focused to deliver community proven best preconfigured tools and components prepared OOTB to use it in your projects. It aims to be end-to-end solution for modern, distributed applications.

If you are interesed in more "enterprise" solutions. Please see the following projects:

• go-kit
• go-micro

Features

• Message Broker - asynchronous messaging using RabbitMQ and Apache Kafka
• Circuit Breaker - custom implementation of Circuit Breaker pattern
• Logging - structured service diagnostics using Logrus library
• Metrics Collection - service metrics collection using Prometheus
• Service Discovery - service discovery using Consul
• Load Balancing - custom implementation of load balancing strategy
• RPC - Remote Procedure Call client and server using gRPC library
• Request Tracing - using opentracing and zipkin
• Data Access Layer
  • Relational databases - using Domain-Driven Design aggregates and repository pattern
• Middlewares:
  • Authentication - middleware for HTTP JSON Web Tokens authentication
  • Rate Limiter - custom implementation of HTTP rate limiter middleware
  • Error - panic error recovery middleware
  • Logging - request logging middleware
  • Metrics - middleware for request metrics exposing
  • Security - middleware for securing request via HTTP headers
  • Tracing - request tracing middleware

Planned features

• More security - HTTP headers, OpenID Connect, Two-factor authentication etc.
• Searchability - Elasticsearch indexing and searching
• Data Access Layer - patterns for accessing data (document oriented)
• Caching - data caching patterns

Installation

$ go get -u github.com/gkarlik/quark-go

Examples

Please see repo with example and documentation.

Documentation

Overview

Package quark provides core functionality, helpers, structs and interfaces of quark framework.

Index

• func CallHTTPService(s Service, method string, url string, body io.Reader, parent trace.Span) ([]byte, error)
• func GetEnvVar(key string) string
• func GetHostAddress(port int) (*url.URL, error)
• func HandleInterrupt(s Service) <-chan bool
• func StartMessageSpan(s Service, name string, m broker.Message) trace.Span
• func StartRPCSpan(ctx context.Context, s Service, name string) trace.Span
• type MessageContextCarrier
  • func (c MessageContextCarrier) ForeachKey(handler func(key string, val interface{}) error) error
  • func (c MessageContextCarrier) Set(key, val string)
• type Option
  • func Address(url *url.URL) Option
  • func Broker(b broker.MessageBroker) Option
  • func Discovery(d discovery.ServiceDiscovery) Option
  • func Logger(l log.Logger) Option
  • func Metrics(e metrics.Exposer) Option
  • func Name(name string) Option
  • func Tags(tags ...string) Option
  • func Tracer(t trace.Tracer) Option
  • func Version(version string) Option
• type Options
• type RPCMetadataCarrier
  • func (c RPCMetadataCarrier) ForeachKey(handler func(key, val string) error) error
  • func (c RPCMetadataCarrier) Set(key, val string)
• type RPCService
• type Service
• type ServiceBase
  • func NewService(opts ...Option) *ServiceBase
  • func (sb ServiceBase) Broker() broker.MessageBroker
  • func (sb ServiceBase) Discovery() discovery.ServiceDiscovery
  • func (sb ServiceBase) Dispose()
  • func (sb ServiceBase) Info() service.Info
  • func (sb ServiceBase) Log() logger.Logger
  • func (sb ServiceBase) Metrics() metrics.Exposer
  • func (sb ServiceBase) Options() Options
  • func (sb ServiceBase) Tracer() trace.Tracer

Functions

func CallHTTPService

func CallHTTPService(s Service, method string, url string, body io.Reader, parent trace.Span) ([]byte, error)

CallHTTPService calls HTTP service at specified url with HTTP method and body.

func GetEnvVar

func GetEnvVar(key string) string

GetEnvVar gets environment variable by key. Panics is variable is not set.

func GetHostAddress

func GetHostAddress(port int) (*url.URL, error)

GetHostAddress returns host address and optionally port on which service is hosted. If port is 0 only address is returned.

func HandleInterrupt

func HandleInterrupt(s Service) <-chan bool

HandleInterrupt handles interrupt signal receiced by the service.

func StartMessageSpan

func StartMessageSpan(s Service, name string, m broker.Message) trace.Span

StartMessageSpan starts span with name and parent span taken from message.

func StartRPCSpan

func StartRPCSpan(ctx context.Context, s Service, name string) trace.Span

StartRPCSpan starts span with name and parent span taken from RPC context.

Types

type MessageContextCarrier

type MessageContextCarrier struct {
	Context *broker.MessageContext
}

MessageContextCarrier represents carrier for span propagation using broker message context.

func (MessageContextCarrier) ForeachKey

func (c MessageContextCarrier) ForeachKey(handler func(key string, val interface{}) error) error

ForeachKey iterates over broker message context key.

func (MessageContextCarrier) Set

func (c MessageContextCarrier) Set(key, val string)

Set sets metadata value inside broker message context.

type Option

type Option func(*Options)

Option represents function which is used to apply service options.

func Address

func Address(url *url.URL) Option

Address allows to set service address.

func Broker

func Broker(b broker.MessageBroker) Option

Broker allows to set message broker implementation.

func Discovery

func Discovery(d discovery.ServiceDiscovery) Option

Discovery allows to set service discovery implementation.

func Logger

func Logger(l log.Logger) Option

Logger allows to set service logger implementation. If it is not set, internal logger will be taken.

func Metrics

func Metrics(e metrics.Exposer) Option

Metrics allows to set service metrics collector implementation.

func Name

func Name(name string) Option

Name allows to set service name.

func Tags

func Tags(tags ...string) Option

Tags allows to set service tag(s).

func Tracer

func Tracer(t trace.Tracer) Option

Tracer allows to set tracer implementation.

func Version

func Version(version string) Option

Version allows to set service version.

type Options

type Options struct {
	Info      service.Info               // service metadata information
	Logger    log.Logger                 // service logger interface implementation
	Discovery discovery.ServiceDiscovery // service discovery interface implementation
	Broker    broker.MessageBroker       // service message broker interface implementation
	Metrics   metrics.Exposer            // service metrics collector interface implementation
	Tracer    trace.Tracer               // service request tracer interface implementation

	Context context.Context // service context
}

Options represents service options.

type RPCMetadataCarrier

type RPCMetadataCarrier struct {
	MD *metadata.MD // gRPC metadata
}

RPCMetadataCarrier represents carrier for span propagation using gRPC metadata.

func (RPCMetadataCarrier) ForeachKey

func (c RPCMetadataCarrier) ForeachKey(handler func(key, val string) error) error

ForeachKey iterates over gRPC metadata key and values.

func (RPCMetadataCarrier) Set

func (c RPCMetadataCarrier) Set(key, val string)

Set sets metadata value inside gRPC metadata.

type RPCService

type RPCService interface {
	Service

	RegisterServiceInstance(server interface{}, serviceInstance interface{}) error
}

RPCService represents service which exposes procedures that could be called remotely.

type Service

type Service interface {
	Info() service.Info                    // service metadata
	Options() Options                      // service options
	Log() logger.Logger                    // service logger
	Discovery() discovery.ServiceDiscovery // service discovery
	Broker() broker.MessageBroker          // service message broker
	Metrics() metrics.Exposer              // service metrics collector
	Tracer() trace.Tracer                  // service request tracer

	system.Disposer
}

Service represents service instance.

type ServiceBase

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

ServiceBase is base structure for custom service.

func NewService

func NewService(opts ...Option) *ServiceBase

NewService creates instance of service with options passed as arguments. Service name, version and address are required options.

func (ServiceBase) Broker

func (sb ServiceBase) Broker() broker.MessageBroker

Broker gets message broker instance.

func (ServiceBase) Discovery

func (sb ServiceBase) Discovery() discovery.ServiceDiscovery

Discovery gets service discovery instance.

func (ServiceBase) Dispose

func (sb ServiceBase) Dispose()

Dispose cleans up service instance.

func (ServiceBase) Info

func (sb ServiceBase) Info() service.Info

Info gets service metadata information.

func (ServiceBase) Log

func (sb ServiceBase) Log() logger.Logger

Log gets service logger instance.

func (ServiceBase) Metrics

func (sb ServiceBase) Metrics() metrics.Exposer

Metrics gets service metrics collector instance.

func (ServiceBase) Options

func (sb ServiceBase) Options() Options

Options gets service options.

func (ServiceBase) Tracer

func (sb ServiceBase) Tracer() trace.Tracer

Tracer gets service request tracer instance.