orion

package
v2.0.0-...-1c13370 Latest Latest
Warning

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

Go to latest
Published: Feb 22, 2023 License: Apache-2.0 Imports: 34 Imported by: 0

Documentation

Overview

Package orion is a small lightweight framework written around grpc with the aim to shorten time to build microservices

Source code for Orion can be found at https://github.com/carousell/Orion

It is derived from 'Framework' a small microservices framework written and used inside https://carousell.com, It comes with a number of sensible defaults such as zipkin tracing, hystrix, live reload of configuration, etc.

Why Orion

Orion uses protocol-buffers definitions (https://developers.google.com/protocol-buffers/docs/proto3) using gRPC and orion proto plugin as base for building services.

Using proto definitions as our service base allows us to define clean contracts that everyone can understand and enables auto generation of client code.

You define your services as a proto definition, for example

service SimpleService{
	rpc Echo (EchoRequest) returns (EchoResponse){
	}
}
message EchoRequest {
	string msg = 1;
}
message EchoResponse {
	string msg = 1;
}

The above definition represents a service named 'SimpleService' which accepts 'EchoRequest' and returns 'EchoResponse' at 'Echo' endpoint.

After you have generated the code from protoc (using grpc and orion plugin), you need to implement the server interface generated by gRPC, orion uses this service definition and enables HTTP/gRPC calls to be made to the same service implementation.

How do i use it

Lets go through the example defined at https://github.com/carousell/Orion/tree/master/example/simple , It covers the minimum required implementation for orion. It has the following structure

.
├── cmd
│   ├── client
│   │   └── client.go
│   └── server
│       └── server.go
├── service
│   └── service.go
└── simple_proto
	├── generate.sh
	└── simple.proto

First we define the proto 'simple_proto/simple.proto' as

syntax = "proto3";

package simple_proto;

service SimpleService{
	rpc Echo (EchoRequest) returns (EchoResponse){
	}
}

message EchoRequest {
	string msg = 1;
}

message EchoResponse {
	string msg = 1;
}

The above definition represents a service named 'SimpleService' which accepts 'EchoRequest' and returns 'EchoResponse' at 'Echo' endpoint.

Now we can execute 'generate.sh' which contains

protoc -I . simple.proto --go_out=plugins=grpc:. --orion_out=.

Running this command generates the following file in the simple_proto directory:

.
├── generate.sh
├── simple.pb.go
├── simple.proto
└── simple.proto.orion.pb.go

This contains:

All the protocol buffer code to populate, serialize, and retrieve our request and response message types (simple.pb.go)
An interface type (or stub) for clients to call with the methods defined in the SimpleService (simple.pb.go)
An interface type for servers to implement, also with the methods defined in the SimpleService (simple.pb.go)
Registration function for Orion (simple.proto.orion.pb.go)

Whats Incuded

Orion comes included with.

Hystrix (http://github.com/afex/hystrix-go)
Zipkin (http://github.com/opentracing/opentracing-go)
NewRelic (http://github.com/newrelic/go-agent)
Prometheus (http://github.com/grpc-ecosystem/go-grpc-prometheus)
Pprof (https://golang.org/pkg/net/http/pprof/))
Configuration (http://github.com/spf13/viper)
Live Configuration Reload (http://github.com/carousell/Orion/v2/utils/listenerutils)
And much more...

Getting Started

First follow the install guide at https://github.com/carousell/Orion/blob/master/README.md

Index

Constants

View Source
const (
	//ProtoGenVersion1_0 is the version of protoc-gen-orion plugin compatible with current code base
	ProtoGenVersion1_0 = true
	BANNER = `` /* 173-byte string literal not displayed */

)

Variables

View Source
var (
	//ErrNil when the passed argument is nil
	ErrNil = errors.New("nil argument passed")
	//ErrNotServiceFactory when passed argument is not a service factory
	ErrNotServiceFactory = errors.New("you need to pass either a ServiceFactory or ServiceFactoryV2")
)
View Source
var (
	//DefaultInitializers are the initializers applied by orion as default
	DefaultInitializers = []Initializer{
		HystrixInitializer(),
		ZipkinInitializer(),
		NewRelicInitializer(),
		PrometheusInitializer(),
		PprofInitializer(),
		ErrorLoggingInitializer(),
	}
)

Functions

func AddConfigPath

func AddConfigPath(path ...string)

AddConfigPath adds a config path from where orion tries to read config values

func RegisterDecoder

func RegisterDecoder(svr Server, serviceName, method string, decoder Decoder)

RegisterDecoder allows for registering an HTTP request decoder to a method Note: this is normally called from protoc-gen-orion autogenerated files

func RegisterDefaultDecoder

func RegisterDefaultDecoder(svr Server, serviceName string, decoder Decoder)

RegisterDefaultDecoder allows for registering an HTTP request decoder to arbitrary urls for the entire service Note: this is normally called from protoc-gen-orion autogenerated files

func RegisterDefaultEncoder

func RegisterDefaultEncoder(svr Server, serviceName string, encoder Encoder)

RegisterDefaultEncoder allows for registering an HTTP request encoder to arbitrary urls for the entire service Note: this is normally called from protoc-gen-orion autogenerated files

func RegisterEncoder

func RegisterEncoder(svr Server, serviceName, method, httpMethod, path string, encoder Encoder)

RegisterEncoder allows for registering an HTTP request encoder to arbitrary urls Note: this is normally called from protoc-gen-orion autogenerated files

func RegisterEncoders

func RegisterEncoders(svr Server, serviceName, method string, httpMethod []string, path string, encoder Encoder)

RegisterEncoders allows for registering an HTTP request encoder to arbitrary urls Note: this is normally called from protoc-gen-orion autogenerated files

func RegisterHandler

func RegisterHandler(svr Server, serviceName, method string, path string, handler HTTPHandler)

RegisterHandler allows registering an HTTP handler for a given path Note: this is normally called from protoc-gen-orion autogenerated files

func RegisterMethodOption

func RegisterMethodOption(svr Server, serviceName, method, option string)

RegisterMethodOption allows for registering an handler option to a particular method Note: this is normally called from protoc-gen-orion autogenerated files

func RegisterMiddleware

func RegisterMiddleware(svr Server, serviceName, method string, middleware ...string)

RegisterMiddleware allows for registering middlewares to a particular method Note: this is normally called from protoc-gen-orion autogenerated files

func ResetConfigPath

func ResetConfigPath()

ResetConfigPath resets the configuration paths

Types

type Config

type Config struct {
	//OrionServerName is the name of this orion server that is tracked
	OrionServerName string
	// GRPCOnly tells orion not to build HTTP/1.1 server and only initializes gRPC server
	GRPCOnly bool
	//HTTPOnly tells orion not to build gRPC server and only initializes HTTP/1.1 server
	HTTPOnly bool
	// HTTPPort is the port to bind for HTTP requests
	HTTPPort string
	// GRPCPost id the port to bind for gRPC requests
	GRPCPort string
	//PprofPort is the port to use for pprof
	PProfport string
	// HotReload when set reloads the service when it receives SIGHUP
	HotReload bool
	//EnableProtoURL adds gRPC generated urls in HTTP handler
	EnableProtoURL bool
	//EnablePrometheus enables prometheus metric for services on path '/metrics' on pprof port
	EnablePrometheus bool
	//EnablePrometheusHistograms enables request histograms for services
	//ref: https://github.com/grpc-ecosystem/go-grpc-prometheus#histograms
	EnablePrometheusHistogram bool
	//HystrixConfig is the configuration options for hystrix
	HystrixConfig HystrixConfig
	//ZipkinConfig is the configuration options for zipkin
	ZipkinConfig ZipkinConfig
	//NewRelicConfig is the configuration options for new relic
	NewRelicConfig NewRelicConfig
	//RollbarToken is the token to be used in rollbar
	RollbarToken string
	//SentryDSN is the token used by sentry for error reporting
	SentryDSN string
	//Env is the environment this service is running in
	Env string
	// DefaultJSONPB sets jsonpb as the encoder/decoder for application/json request/response bodies
	DefaultJSONPB bool
	// DisableDefaultInterceptors disables the default interceptors for all handlers
	DisableDefaultInterceptors bool
	// Receive message Size is used to update the default limit of message that can be received
	MaxRecvMsgSize int
}

Config is the configuration used by Orion core

func BuildDefaultConfig

func BuildDefaultConfig(name string) Config

BuildDefaultConfig builds a default config object for Orion

type Decoder

type Decoder = handlers.Decoder

Decoder is the function type needed for request decoders

type DefaultServerImpl

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

DefaultServerImpl provides a default implementation of orion.Server this can be embedded in custom orion.Server implementations

func (*DefaultServerImpl) AddDecoder

func (d *DefaultServerImpl) AddDecoder(serviceName, method string, decoder handlers.Decoder)

AddDecoder is the implementation of handlers.Decodable

func (*DefaultServerImpl) AddDefaultDecoder

func (d *DefaultServerImpl) AddDefaultDecoder(serviceName string, decoder Decoder)

AddDefaultDecoder is the implementation of handlers.Decodable

func (*DefaultServerImpl) AddDefaultEncoder

func (d *DefaultServerImpl) AddDefaultEncoder(serviceName string, encoder Encoder)

AddDefaultEncoder is the implementation of handlers.Encodable

func (*DefaultServerImpl) AddEncoder

func (d *DefaultServerImpl) AddEncoder(serviceName, method string, httpMethod []string, path string, encoder handlers.Encoder)

AddEncoder is the implementation of handlers.Encodable

func (*DefaultServerImpl) AddHTTPHandler

func (d *DefaultServerImpl) AddHTTPHandler(serviceName string, method string, path string, handler handlers.HTTPHandler)

AddHTTPHandler is the implementation of handlers.HTTPInterceptor

func (*DefaultServerImpl) AddInitializers

func (d *DefaultServerImpl) AddInitializers(ins ...Initializer)

AddInitializers adds the initializers to orion server

func (*DefaultServerImpl) AddMiddleware

func (d *DefaultServerImpl) AddMiddleware(serviceName string, method string, middlewares ...string)

AddMiddleware adds middlewares for particular service/method

func (*DefaultServerImpl) AddOption

func (d *DefaultServerImpl) AddOption(serviceName, method, option string)

AddOption adds a option for the particular service/method

func (*DefaultServerImpl) GetConfig

func (d *DefaultServerImpl) GetConfig() map[string]interface{}

GetConfig returns current config as parsed from the file/defaults

func (*DefaultServerImpl) GetOrionConfig

func (d *DefaultServerImpl) GetOrionConfig() Config

GetOrionConfig returns current orion config NOTE: this config can not be modifies

func (*DefaultServerImpl) RegisterService

func (d *DefaultServerImpl) RegisterService(sd *grpc.ServiceDesc, sf interface{}) error

RegisterService registers a service from a generated proto file Note: this is only called from code generated by orion plugin

func (*DefaultServerImpl) Start

func (d *DefaultServerImpl) Start()

Start starts the orion server

func (*DefaultServerImpl) Stop

func (d *DefaultServerImpl) Stop(timeout time.Duration) error

Stop stops the server

func (*DefaultServerImpl) Wait

func (d *DefaultServerImpl) Wait() error

Wait waits for all the serving servers to quit

type DefaultServerOption

type DefaultServerOption interface {
	// contains filtered or unexported methods
}

func WithGrpcUnknownHandler

func WithGrpcUnknownHandler(grpcUnknownServiceHandler grpc.StreamHandler) DefaultServerOption

WithGrpcUnknownHandler returns a DefaultServerOption which sets UnknownServiceHandler option in grpc server

type Encoder

type Encoder = handlers.Encoder

Encoder is the function type needed for request encoders

type FactoryParams

type FactoryParams struct {
	// ServiceName contains the proto service name
	ServiceName string
	// Version is a counter that is incremented every time a new service object is requested
	// NOTE: version might rollover in long running services
	Version uint64
}

FactoryParams are the parameters used by the ServiceFactoryV2

type HTTPHandler

type HTTPHandler = handlers.HTTPHandler

HTTPHandler is the http interceptor

type HystrixConfig

type HystrixConfig struct {
	//Port is the port to start hystrix stream handler on
	Port string
	//CommandConfig is configuration for individual commands
	CommandConfig map[string]hystrix.CommandConfig
	//StatsdAddr is the address of the statsd hosts to send hystrix data to
	StatsdAddr string
	// DefaultTimeout is how long to wait for command to complete, in milliseconds
	DefaultTimeout int
	// DefaultMaxConcurrent is how many commands of the same type can run at the same time
	DefaultMaxConcurrent int
	// DefaultVolumeThreshold is the minimum number of requests needed before a circuit can be tripped due to health
	DefaultVolumeThreshold int
	// DefaultSleepWindow is how long, in milliseconds, to wait after a circuit opens before testing for recovery
	DefaultSleepWindow int
	// DefaultErrorPercentThreshold causes circuits to open once the rolling measure of errors exceeds this percent of requests
	DefaultErrorPercentThreshold int
}

HystrixConfig is configuration used by hystrix

func BuildDefaultHystrixConfig

func BuildDefaultHystrixConfig() HystrixConfig

BuildDefaultHystrixConfig builds a default config for hystrix

type Initializer

type Initializer interface {
	Init(svr Server) error
	ReInit(svr Server) error
}

Initializer is the interface needed to be implemented by custom initializers

func ErrorLoggingInitializer

func ErrorLoggingInitializer() Initializer

ErrorLoggingInitializer returns a Initializer implementation for error notifier

func HystrixInitializer

func HystrixInitializer() Initializer

HystrixInitializer returns a Initializer implementation for Hystrix

func NewRelicInitializer

func NewRelicInitializer() Initializer

NewRelicInitializer returns a Initializer implementation for NewRelic

func PprofInitializer

func PprofInitializer() Initializer

PprofInitializer returns a Initializer implementation for Pprof

func PrometheusInitializer

func PrometheusInitializer() Initializer

PrometheusInitializer returns a Initializer implementation for Prometheus

func ZipkinInitializer

func ZipkinInitializer() Initializer

ZipkinInitializer returns a Initializer implementation for Zipkin

type NewRelicConfig

type NewRelicConfig struct {
	APIKey      string
	ServiceName string
	//HttpTxNameType decides the transaction name logged in NR. Options are "fullmethod" (default), "method" , "route".
	HttpTxNameType    string
	IncludeAttributes []string
	ExcludeAttributes []string
}

NewRelicConfig is the configuration for newrelic

func BuildDefaultNewRelicConfig

func BuildDefaultNewRelicConfig() NewRelicConfig

BuildDefaultNewRelicConfig builds a default config for newrelic

type Server

type Server interface {
	//Start starts the orion server, this is non blocking call
	Start()
	//RegisterService registers the service to origin server
	RegisterService(sd *grpc.ServiceDesc, sf interface{}) error
	//Wait waits for the Server loop to exit
	Wait() error
	//Stop stops the Server
	Stop(timeout time.Duration) error
	//GetOrionConfig returns current orion config
	GetOrionConfig() Config
	//GetConfig returns current config as parsed from the file/defaults
	GetConfig() map[string]interface{}
	//AddInitializers adds the initializers to orion server
	AddInitializers(ins ...Initializer)
}

Server is the interface that needs to be implemented by any orion server 'DefaultServerImpl' should be enough for most users.

func GetDefaultServer

func GetDefaultServer(name string, opts ...DefaultServerOption) Server

GetDefaultServer returns a default server object that can be directly used to start orion server

func GetDefaultServerWithConfig

func GetDefaultServerWithConfig(config Config) Server

GetDefaultServerWithConfig returns a default server object that uses provided configuration

type ServiceFactory

type ServiceFactory interface {
	// NewService function receives the server object for which service has to be initialized
	NewService(Server) interface{}
	//DisposeService function disposes the service object
	DisposeService(svc interface{})
}

ServiceFactory is the interface that need to be implemented by client that provides with a new service object

type ServiceFactoryV2

type ServiceFactoryV2 interface {
	// NewService function receives the server object for which service has to be initialized
	NewService(svr Server, params FactoryParams) interface{}
	//DisposeService function disposes the service object
	DisposeService(svc interface{}, params FactoryParams)
}

ServiceFactoryV2 is the interface that needs to be implemented by client that provides a new service object for multiple services this allows a single struct to implement multiple services

func ToServiceFactoryV2

func ToServiceFactoryV2(sf interface{}) (ServiceFactoryV2, error)

ToServiceFactoryV2 converts ServiceFactory to ServiceFactoryV2

type ZipkinConfig

type ZipkinConfig struct {
	//Addr is the address of the zipkin collector
	Addr string
}

ZipkinConfig is the configuration for the zipkin collector

func BuildDefaultZipkinConfig

func BuildDefaultZipkinConfig() ZipkinConfig

BuildDefaultZipkinConfig builds a default config for zipkin

Directories

Path Synopsis
package helpers contains helper that services can use
package helpers contains helper that services can use

Jump to

Keyboard shortcuts

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