README
Go Micro

Go Micro is a framework for distributed systems development.
Overview
Go Micro provides the core requirements for distributed systems development including RPC and Event driven communication. The Micro philosophy is sane defaults with a pluggable architecture. We provide defaults to get you started quickly but everything can be easily swapped out.
Features
Go Micro abstracts away the details of distributed systems. Here are the main features.
-
Authentication - Auth is built in as a first class citizen. Authentication and authorization enable secure zero trust networking by providing every service an identity and certificates. This additionally includes rule based access control.
-
Dynamic Config - Load and hot reload dynamic config from anywhere. The config interface provides a way to load application level config from any source such as env vars, file, etcd. You can merge the sources and even define fallbacks.
-
Data Storage - A simple data store interface to read, write and delete records. It includes support for memory, file and CockroachDB by default. State and persistence becomes a core requirement beyond prototyping and Micro looks to build that into the framework.
-
Service Discovery - Automatic service registration and name resolution. Service discovery is at the core of micro service development. When service A needs to speak to service B it needs the location of that service. The default discovery mechanism is multicast DNS (mdns), a zeroconf system.
-
Load Balancing - Client side load balancing built on service discovery. Once we have the addresses of any number of instances of a service we now need a way to decide which node to route to. We use random hashed load balancing to provide even distribution across the services and retry a different node if there's a problem.
-
Message Encoding - Dynamic message encoding based on content-type. The client and server will use codecs along with content-type to seamlessly encode and decode Go types for you. Any variety of messages could be encoded and sent from different clients. The client and server handle this by default. This includes protobuf and json by default.
-
gRPC Transport - gRPC based request/response with support for bidirectional streaming. We provide an abstraction for synchronous communication. A request made to a service will be automatically resolved, load balanced, dialled and streamed.
-
Async Messaging - PubSub is built in as a first class citizen for asynchronous communication and event driven architectures. Event notifications are a core pattern in micro service development. The default messaging system is a HTTP event message broker.
-
Synchronization - Distributed systems are often built in an eventually consistent manner. Support for distributed locking and leadership are built in as a Sync interface. When using an eventually consistent database or scheduling use the Sync interface.
-
Pluggable Interfaces - Go Micro makes use of Go interfaces for each distributed system abstraction. Because of this these interfaces are pluggable and allows Go Micro to be runtime agnostic. You can plugin any underlying technology. Find plugins in github.com/micro/go-plugins.
Getting Started
To make use of Go Micro
import "github.com/micro/go-micro/v2"
// create a new service
service := micro.NewService(
micro.Name("helloworld"),
)
// initialise flags
service.Init()
// start the service
service.Run()
See the docs for detailed information on the architecture, installation and use of go-micro.
License
Go Micro is Apache 2.0 licensed.
Documentation
Overview ¶
Package micro is a pluggable framework for microservices
Index ¶
- Variables
- func NewContext(ctx context.Context, s Service) context.Context
- func RegisterHandler(s server.Server, h interface{}, opts ...server.HandlerOption) error
- func RegisterSubscriber(topic string, s server.Server, h interface{}, opts ...server.SubscriberOption) error
- type Event
- type Function
- type Option
- func Action(a func(*cli.Context) error) Option
- func Address(addr string) Option
- func AfterStart(fn func() error) Option
- func AfterStop(fn func() error) Option
- func Auth(a auth.Auth) Option
- func BeforeStart(fn func() error) Option
- func BeforeStop(fn func() error) Option
- func Broker(b broker.Broker) Option
- func Client(c client.Client) Option
- func Cmd(c cmd.Cmd) Option
- func Config(c config.Config) Option
- func Context(ctx context.Context) Option
- func Flags(flags ...cli.Flag) Option
- func HandleSignal(b bool) Option
- func Metadata(md map[string]string) Option
- func Name(n string) Option
- func Profile(p profile.Profile) Option
- func RegisterInterval(t time.Duration) Option
- func RegisterTTL(t time.Duration) Option
- func Registry(r registry.Registry) Option
- func Runtime(r runtime.Runtime) Option
- func Selector(s selector.Selector) Option
- func Server(s server.Server) Option
- func Store(s store.Store) Option
- func Tracer(t trace.Tracer) Option
- func Transport(t transport.Transport) Option
- func Version(v string) Option
- func WrapCall(w ...client.CallWrapper) Option
- func WrapClient(w ...client.Wrapper) Option
- func WrapHandler(w ...server.HandlerWrapper) Option
- func WrapSubscriber(w ...server.SubscriberWrapper) Option
- type Options
- type Publisher
- type Service
Constants ¶
Variables ¶
var (
HeaderPrefix = "Micro-"
)
Functions ¶
func NewContext ¶
NewContext returns a new Context with the Service embedded within it.
func RegisterHandler ¶
func RegisterHandler(s server.Server, h interface{}, opts ...server.HandlerOption) error
RegisterHandler is syntactic sugar for registering a handler
func RegisterSubscriber ¶
func RegisterSubscriber(topic string, s server.Server, h interface{}, opts ...server.SubscriberOption) error
RegisterSubscriber is syntactic sugar for registering a subscriber
Types ¶
type Event ¶
type Event interface { // Publish publishes a message to the event topic Publish(ctx context.Context, msg interface{}, opts ...client.PublishOption) error }
Event is used to publish messages to a topic
type Function ¶
type Function interface { // Inherits Service interface Service // Done signals to complete execution Done() error // Handle registers an RPC handler Handle(v interface{}) error // Subscribe registers a subscriber Subscribe(topic string, v interface{}) error }
Function is a one time executing Service
func NewFunction ¶
NewFunction returns a new Function for a one time executing Service
type Option ¶
type Option func(*Options)
func BeforeStart ¶
BeforeStart run funcs before service starts
func Context ¶
Context specifies a context for the service. Can be used to signal shutdown of the service and for extra option values.
func HandleSignal ¶
HandleSignal toggles automatic installation of the signal handler that traps TERM, INT, and QUIT. Users of this feature to disable the signal handler, should control liveness of the service through the context.
func RegisterInterval ¶
RegisterInterval specifies the interval on which to re-register
func RegisterTTL ¶
RegisterTTL specifies the TTL to use when registering the service
func WrapCall ¶
func WrapCall(w ...client.CallWrapper) Option
WrapCall is a convenience method for wrapping a Client CallFunc
func WrapClient ¶
WrapClient is a convenience method for wrapping a Client with some middleware component. A list of wrappers can be provided. Wrappers are applied in reverse order so the last is executed first.
func WrapHandler ¶
func WrapHandler(w ...server.HandlerWrapper) Option
WrapHandler adds a handler Wrapper to a list of options passed into the server
func WrapSubscriber ¶
func WrapSubscriber(w ...server.SubscriberWrapper) Option
WrapSubscriber adds a subscriber Wrapper to a list of options passed into the server
type Options ¶
type Options struct { Auth auth.Auth Broker broker.Broker Cmd cmd.Cmd Config config.Config Client client.Client Server server.Server Store store.Store Registry registry.Registry Runtime runtime.Runtime Transport transport.Transport Profile profile.Profile // Before and After funcs BeforeStart []func() error BeforeStop []func() error AfterStart []func() error AfterStop []func() error // Other options for implementations of the interface // can be stored in a context Context context.Context Signal bool }
Options for micro service
type Service ¶
type Service interface { // The service name Name() string // Init initialises options Init(...Option) // Options returns the current options Options() Options // Client is used to call services Client() client.Client // Server is for handling requests and events Server() server.Server // Run the service Run() error // The service implementation String() string }
Service is an interface that wraps the lower level libraries within go-micro. Its a convenience method for building and initialising services.
func FromContext ¶
FromContext retrieves a Service from the Context.
func NewService ¶
NewService creates and returns a new Service based on the packages within.
Directories
Path | Synopsis |
---|---|
agent | Package agent provides an interface for building robots |
agent/command | Package command is an interface for defining bot commands |
agent/input | Package input is an interface for bot inputs |
agent/input/discord | |
agent/input/slack | |
agent/input/telegram | |
agent/proto | |
api | |
api/handler | Package handler provides http handlers |
api/handler/api | Package api provides an http-rpc handler which provides the entire http request over rpc |
api/handler/event | Package event provides a handler which publishes an event |
api/handler/http | Package http is a http reverse proxy handler |
api/handler/rpc | Package rpc is a go-micro rpc handler. |
api/handler/web | Package web contains the web handler including websocket support |
api/internal/proto | |
api/proto | |
api/resolver | Package resolver resolves a http request to an endpoint |
api/resolver/grpc | Package grpc resolves a grpc service like /greeter.Say/Hello to greeter service |
api/resolver/host | Package host resolves using http host |
api/resolver/path | Package path resolves using http path |
api/resolver/vpath | Package vpath resolves using http path and recognised versioned urls |
api/router | Package router provides api service routing |
api/router/registry | Package registry provides a dynamic api service router |
api/router/static | |
api/router/util | |
api/server | Package server provides an API gateway server which handles inbound requests |
api/server/acme | Package acme abstracts away various ACME libraries |
api/server/acme/autocert | Package autocert is the ACME provider from golang.org/x/crypto/acme/autocert This provider does not take any config. |
api/server/acme/certmagic | Package certmagic is the ACME provider from github.com/caddyserver/certmagic |
api/server/cors | |
api/server/http | Package http provides a http server with features; acme, cors, etc |
api/service/proto | |
auth | Package auth provides authentication and authorization capability |
auth/jwt | |
auth/provider | Package provider is an external auth provider e.g oauth |
auth/provider/basic | |
auth/provider/oauth | |
auth/rules | |
auth/service | |
auth/service/proto | |
auth/token | |
auth/token/basic | |
auth/token/jwt | |
broker | Package broker is an interface used for asynchronous messaging Package http provides a http based message broker |
broker/http | Package http provides a http based message broker |
broker/memory | Package memory provides a memory broker |
broker/nats | Package nats provides a NATS broker |
broker/service | Package service provides the broker service client |
broker/service/proto | |
client | Package client is an interface for an RPC client |
client/grpc | Package grpc provides a gRPC client Package grpc provides a gRPC options |
client/mucp | Package mucp provides an mucp client |
client/selector | Package selector is a way to pick a list of service nodes |
client/selector/dns | Package dns provides a dns SRV selector |
client/selector/registry | Package registry uses the go-micro registry for selection |
client/selector/router | Package router is a network/router selector |
client/selector/static | Package static provides a static resolver which returns the name/ip passed in without any change |
client/service/proto | |
codec | Package codec is an interface for encoding messages |
codec/bytes | Package bytes provides a bytes codec which does not encode or decode anything |
codec/grpc | Package grpc provides a grpc codec |
codec/json | Package json provides a json codec |
codec/jsonrpc | Package jsonrpc provides a json-rpc 1.0 codec |
codec/proto | Package proto provides a proto codec |
codec/protorpc | Protorpc provides a net/rpc proto-rpc codec. |
codec/text | Package text reads any text/* content-type |
config | Package config is an interface for dynamic configuration. |
config/cmd | Package cmd is an interface for parsing the command line |
config/encoder | Package encoder handles source encoding formats |
config/encoder/hcl | |
config/encoder/json | |
config/encoder/toml | |
config/encoder/xml | |
config/encoder/yaml | |
config/loader | package loader manages loading from multiple sources |
config/loader/memory | |
config/reader | Package reader parses change sets and provides config values |
config/reader/json | |
config/secrets | Package secrets is an interface for encrypting and decrypting secrets |
config/secrets/box | Package box is an asymmetric implementation of config/secrets using nacl/box |
config/secrets/secretbox | Package secretbox is a config/secrets implementation that uses nacl/secretbox to do symmetric encryption / verification |
config/source | Package source is the interface for sources |
config/source/cli | |
config/source/env | |
config/source/etcd | |
config/source/file | Package file is a file source. |
config/source/flag | |
config/source/memory | Package memory is a memory source |
config/source/service | |
config/source/service/proto | |
debug | Package debug provides micro debug packages |
debug/log | Package log provides debug logging |
debug/log/kubernetes | Package kubernetes is a logger implementing (github.com/micro/go-micro/v2/debug/log).Log |
debug/log/memory | Package memory provides an in memory log buffer |
debug/log/noop | |
debug/profile | Package profile is for profilers |
debug/profile/http | Package http enables the http profiler |
debug/profile/pprof | Package pprof provides a pprof profiler |
debug/service | Package service provides the service log |
debug/service/handler | Package handler implements service debug handler embedded in go-micro services |
debug/service/proto | |
debug/stats | Package stats provides runtime stats |
debug/trace | Package trace provides an interface for distributed tracing |
debug/trace/memory | |
errors | Package errors provides a way to return detailed information for an RPC request error. |
logger | Package log provides a log interface |
metadata | Package metadata is a way of defining message headers |
network | Package network is for creating internetworks |
network/resolver | Package resolver resolves network names to addresses |
network/resolver/dns | Package dns resolves names to dns records |
network/resolver/dnssrv | Package dns srv resolves names to dns srv records |
network/resolver/http | Package http resolves names to network addresses using a http request |
network/resolver/registry | Package registry resolves names using the go-micro registry |
network/resolver/static | Package static is a static resolver |
network/service/proto | |
plugin | Package plugin provides the ability to load plugins Package plugin provides the ability to load plugins |
proxy | Package proxy is a transparent proxy built on the go-micro/server Package proxy is a transparent proxy built on the go-micro/server |
proxy/grpc | Package grpc transparently forwards the grpc protocol using a go-micro client. |
proxy/http | Package http provides a micro rpc to http proxy |
proxy/mucp | Package mucp transparently forwards the incoming request using a go-micro client. |
registry | Package mdns is a multicast dns registry Package registry is an interface for service discovery |
registry/cache | Package cache provides a registry cache |
registry/etcd | Package etcd provides an etcd service registry |
registry/mdns | Package mdns provides a multicast dns registry |
registry/memory | Package memory provides an in-memory registry |
registry/service | Package service uses the registry service |
registry/service/proto | |
router | Package router provides a network routing control plane |
router/service | |
router/service/proto | |
runtime | Package runtime is a service runtime manager |
runtime/kubernetes | Package kubernetes implements kubernetes micro runtime Package kubernetes taken from https://github.com/micro/go-micro/blob/master/debug/log/kubernetes/kubernetes.go There are some modifications compared to the other files as this package doesn't provide write functionality. |
runtime/local | Package local provides a local runtime |
runtime/local/build | Package build builds a micro runtime package |
runtime/local/build/docker | Package docker builds docker images |
runtime/local/build/go | Package golang is a go package manager |
runtime/local/git | |
runtime/local/process | Package process executes a binary |
runtime/local/process/os | Package os runs processes locally Package os runs processes locally |
runtime/local/source | Package source retrieves source code |
runtime/local/source/git | Package git provides a git source |
runtime/local/source/go | Package golang is a source for Go |
runtime/service | |
runtime/service/proto | |
server | Package server is an interface for a micro server |
server/grpc | Package grpc provides a grpc server |
server/grpc/proto | |
server/mock | |
server/mucp | Package mucp provides an mucp server |
server/proto | |
service | Package service encapsulates the client, server and other interfaces to provide a complete micro service. |
service/grpc | |
service/grpc/proto | |
service/mucp | Package mucp initialises a mucp service |
store | Package store is an interface for distributed data storage. |
store/cache | Package cache implements a faulting style read cache on top of multiple micro stores |
store/cockroach | Package cockroach implements the cockroach store |
store/file | Package local is a file system backed store |
store/memory | Package memory is a in-memory store store |
store/service | Package service implements the store service interface |
store/service/proto | |
sync | Package sync is an interface for distributed synchronization |
sync/etcd | Package etcd is an etcd implementation of lock |
sync/memory | Package memory provides a sync.Mutex implementation of the lock for local use |
transport | Package transport is an interface for synchronous connection based communication |
transport/grpc | Package grpc provides a grpc transport |
transport/grpc/proto | |
transport/http | Package http returns a http2 transport using net/http |
transport/memory | Package memory is an in-memory transport |
transport/quic | Package quic provides a QUIC based transport |
tunnel | Package tunnel provides gre network tunnelling |
tunnel/broker | Package broker is a tunnel broker |
tunnel/transport | Package transport provides a tunnel transport |
util/addr | |
util/auth | |
util/backoff | Package backoff provides backoff functionality |
util/buf | |
util/ctx | |
util/file | |
util/file/proto | |
util/grpc | |
util/http | |
util/io | Package io is for io management |
util/jitter | Package jitter provides a random jitter |
util/kubernetes/api | |
util/kubernetes/client | Package client provides an implementation of a restricted subset of kubernetes API client |
util/log | Package log is a global internal logger DEPRECATED: this is frozen package, use github.com/micro/go-micro/v2/logger |
util/mdns | |
util/mux | Package mux provides proxy muxing |
util/net | |
util/pki | Package pki provides PKI all the PKI functions necessary to run micro over an untrusted network including a CA |
util/pool | Package pool is a connection pool |
util/proto | Package proto contains utility functions for working with protobufs |
util/qson | Package qson implmenets decoding of URL query params into JSON and Go values (using JSON struct tags). |
util/registry | |
util/ring | Package ring provides a simple ring buffer for storing local data |
util/scope | |
util/signal | |
util/socket | Package socket provides a pseudo socket |
util/stream | Package stream encapsulates streams within streams |
util/sync | Package syncs will sync multiple stores |
util/test | |
util/tls | |
util/wrapper | |
web | Package web provides web based micro services |