README

Go Micro License Go.Dev reference Travis CI Go Report Card

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.

  • RPC Client/Server - RPC 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.

Getting Started

To make use of Go Micro

import "github.com/asim/go-micro/v3"

// 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.

Code Generation

See cmd/protoc-gen-micro for protobuf code generation.

Example Usage

See examples directory for usage examples.

Plugins

See plugins directory for all the plugins.

License

Go Micro is Apache 2.0 licensed.

Upgrade

Micro v3 consolidates Go Micro into it as a single unified platform. Please see the upgrade guide.

Expand ▾ Collapse ▴

Documentation

Overview

    Package micro is a pluggable framework for microservices

    Index

    Constants

    This section is empty.

    Variables

    View Source
    var (
    	HeaderPrefix = "Micro-"
    )

    Functions

    func NewContext

    func NewContext(ctx context.Context, s Service) context.Context

      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

            func NewEvent

            func NewEvent(topic string, c client.Client) Event

              NewEvent creates a new event publisher

              func NewPublisher

              func NewPublisher(topic string, c client.Client) Event

                Deprecated: NewPublisher returns a new Publisher

                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

                  func NewFunction(opts ...Option) Function

                    NewFunction returns a new Function for a one time executing Service

                    type Option

                    type Option func(*Options)

                    func Action

                    func Action(a func(*cli.Context) error) Option

                      Action can be used to parse user provided cli options

                      func Address

                      func Address(addr string) Option

                        Address sets the address of the server

                        func AfterStart

                        func AfterStart(fn func() error) Option

                          AfterStart run funcs after service starts

                          func AfterStop

                          func AfterStop(fn func() error) Option

                            AfterStop run funcs after service stops

                            func Auth

                            func Auth(a auth.Auth) Option

                              Auth sets the auth for the service

                              func BeforeStart

                              func BeforeStart(fn func() error) Option

                                BeforeStart run funcs before service starts

                                func BeforeStop

                                func BeforeStop(fn func() error) Option

                                  BeforeStop run funcs before service stops

                                  func Broker

                                  func Broker(b broker.Broker) Option

                                    Broker to be used for service

                                    func Client

                                    func Client(c client.Client) Option

                                      Client to be used for service

                                      func Cmd

                                      func Cmd(c cmd.Cmd) Option

                                      func Config

                                      func Config(c config.Config) Option

                                        Config sets the config for the service

                                        func Context

                                        func Context(ctx context.Context) Option

                                          Context specifies a context for the service. Can be used to signal shutdown of the service and for extra option values.

                                          func Flags

                                          func Flags(flags ...cli.Flag) Option

                                            Flags that can be passed to service

                                            func HandleSignal

                                            func HandleSignal(b bool) Option

                                              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 Metadata

                                              func Metadata(md map[string]string) Option

                                                Metadata associated with the service

                                                func Name

                                                func Name(n string) Option

                                                  Name of the service

                                                  func Profile

                                                  func Profile(p profile.Profile) Option

                                                    Profile to be used for debug profile

                                                    func RegisterInterval

                                                    func RegisterInterval(t time.Duration) Option

                                                      RegisterInterval specifies the interval on which to re-register

                                                      func RegisterTTL

                                                      func RegisterTTL(t time.Duration) Option

                                                        RegisterTTL specifies the TTL to use when registering the service

                                                        func Registry

                                                        func Registry(r registry.Registry) Option

                                                          Registry sets the registry for the service and the underlying components

                                                          func Runtime

                                                          func Runtime(r runtime.Runtime) Option

                                                            Runtime sets the runtime

                                                            func Selector

                                                            func Selector(s selector.Selector) Option

                                                              Selector sets the selector for the service client

                                                              func Server

                                                              func Server(s server.Server) Option

                                                                Server to be used for service

                                                                func Store

                                                                func Store(s store.Store) Option

                                                                  Store sets the store to use

                                                                  func Tracer

                                                                  func Tracer(t trace.Tracer) Option

                                                                    Tracer sets the tracer for the service

                                                                    func Transport

                                                                    func Transport(t transport.Transport) Option

                                                                      Transport sets the transport for the service and the underlying components

                                                                      func Version

                                                                      func Version(v string) Option

                                                                        Version of the service

                                                                        func WrapCall

                                                                        func WrapCall(w ...client.CallWrapper) Option

                                                                          WrapCall is a convenience method for wrapping a Client CallFunc

                                                                          func WrapClient

                                                                          func WrapClient(w ...client.Wrapper) Option

                                                                            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 Publisher

                                                                                  type Publisher = Event

                                                                                    Type alias to satisfy the deprecation

                                                                                    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

                                                                                      func FromContext(ctx context.Context) (Service, bool)

                                                                                        FromContext retrieves a Service from the Context.

                                                                                        func NewService

                                                                                        func NewService(opts ...Option) Service

                                                                                          NewService creates and returns a new Service based on the packages within.

                                                                                          Directories

                                                                                          Path Synopsis
                                                                                          api
                                                                                          handler
                                                                                          Package handler provides http handlers
                                                                                          Package handler provides http handlers
                                                                                          handler/api
                                                                                          Package api provides an http-rpc handler which provides the entire http request over rpc
                                                                                          Package api provides an http-rpc handler which provides the entire http request over rpc
                                                                                          handler/event
                                                                                          Package event provides a handler which publishes an event
                                                                                          Package event provides a handler which publishes an event
                                                                                          handler/http
                                                                                          Package http is a http reverse proxy handler
                                                                                          Package http is a http reverse proxy handler
                                                                                          handler/rpc
                                                                                          Package rpc is a go-micro rpc handler.
                                                                                          Package rpc is a go-micro rpc handler.
                                                                                          handler/web
                                                                                          Package web contains the web handler including websocket support
                                                                                          Package web contains the web handler including websocket support
                                                                                          resolver
                                                                                          Package resolver resolves a http request to an endpoint
                                                                                          Package resolver resolves a http request to an endpoint
                                                                                          resolver/grpc
                                                                                          Package grpc resolves a grpc service like /greeter.Say/Hello to greeter service
                                                                                          Package grpc resolves a grpc service like /greeter.Say/Hello to greeter service
                                                                                          resolver/host
                                                                                          Package host resolves using http host
                                                                                          Package host resolves using http host
                                                                                          resolver/path
                                                                                          Package path resolves using http path
                                                                                          Package path resolves using http path
                                                                                          resolver/vpath
                                                                                          Package vpath resolves using http path and recognised versioned urls
                                                                                          Package vpath resolves using http path and recognised versioned urls
                                                                                          router
                                                                                          Package router provides api service routing
                                                                                          Package router provides api service routing
                                                                                          router/registry
                                                                                          Package registry provides a dynamic api service router
                                                                                          Package registry provides a dynamic api service router
                                                                                          server
                                                                                          Package server provides an API gateway server which handles inbound requests
                                                                                          Package server provides an API gateway server which handles inbound requests
                                                                                          server/acme
                                                                                          Package acme abstracts away various ACME libraries
                                                                                          Package acme abstracts away various ACME libraries
                                                                                          server/acme/autocert
                                                                                          Package autocert is the ACME provider from golang.org/x/crypto/acme/autocert This provider does not take any config.
                                                                                          Package autocert is the ACME provider from golang.org/x/crypto/acme/autocert This provider does not take any config.
                                                                                          server/http
                                                                                          Package http provides a http server with features; acme, cors, etc
                                                                                          Package http provides a http server with features; acme, cors, etc
                                                                                          Package auth provides authentication and authorization capability
                                                                                          Package auth provides authentication and authorization capability
                                                                                          Package broker is an interface used for asynchronous messaging Package http provides a http based message broker
                                                                                          Package broker is an interface used for asynchronous messaging Package http provides a http based message broker
                                                                                          Package client is an interface for an RPC client
                                                                                          Package client is an interface for an RPC client
                                                                                          Package cmd is an interface for parsing the command line
                                                                                          Package cmd is an interface for parsing the command line
                                                                                          Package codec is an interface for encoding messages
                                                                                          Package codec is an interface for encoding messages
                                                                                          bytes
                                                                                          Package bytes provides a bytes codec which does not encode or decode anything
                                                                                          Package bytes provides a bytes codec which does not encode or decode anything
                                                                                          grpc
                                                                                          Package grpc provides a grpc codec
                                                                                          Package grpc provides a grpc codec
                                                                                          json
                                                                                          Package json provides a json codec
                                                                                          Package json provides a json codec
                                                                                          jsonrpc
                                                                                          Package jsonrpc provides a json-rpc 1.0 codec
                                                                                          Package jsonrpc provides a json-rpc 1.0 codec
                                                                                          proto
                                                                                          Package proto provides a proto codec
                                                                                          Package proto provides a proto codec
                                                                                          protorpc
                                                                                          Protorpc provides a net/rpc proto-rpc codec.
                                                                                          Protorpc provides a net/rpc proto-rpc codec.
                                                                                          text
                                                                                          Package text reads any text/* content-type
                                                                                          Package text reads any text/* content-type
                                                                                          Package config is an interface for dynamic configuration.
                                                                                          Package config is an interface for dynamic configuration.
                                                                                          encoder
                                                                                          Package encoder handles source encoding formats
                                                                                          Package encoder handles source encoding formats
                                                                                          loader
                                                                                          package loader manages loading from multiple sources
                                                                                          package loader manages loading from multiple sources
                                                                                          reader
                                                                                          Package reader parses change sets and provides config values
                                                                                          Package reader parses change sets and provides config values
                                                                                          secrets
                                                                                          Package secrets is an interface for encrypting and decrypting secrets
                                                                                          Package secrets is an interface for encrypting and decrypting secrets
                                                                                          secrets/box
                                                                                          Package box is an asymmetric implementation of config/secrets using nacl/box
                                                                                          Package box is an asymmetric implementation of config/secrets using nacl/box
                                                                                          secrets/secretbox
                                                                                          Package secretbox is a config/secrets implementation that uses nacl/secretbox to do symmetric encryption / verification
                                                                                          Package secretbox is a config/secrets implementation that uses nacl/secretbox to do symmetric encryption / verification
                                                                                          source
                                                                                          Package source is the interface for sources
                                                                                          Package source is the interface for sources
                                                                                          source/file
                                                                                          Package file is a file source.
                                                                                          Package file is a file source.
                                                                                          source/memory
                                                                                          Package memory is a memory source
                                                                                          Package memory is a memory source
                                                                                          debug
                                                                                          handler
                                                                                          Package handler implements service debug handler embedded in go-micro services
                                                                                          Package handler implements service debug handler embedded in go-micro services
                                                                                          log
                                                                                          Package log provides debug logging
                                                                                          Package log provides debug logging
                                                                                          log/memory
                                                                                          Package memory provides an in memory log buffer
                                                                                          Package memory provides an in memory log buffer
                                                                                          profile
                                                                                          Package profile is for profilers
                                                                                          Package profile is for profilers
                                                                                          profile/http
                                                                                          Package http enables the http profiler
                                                                                          Package http enables the http profiler
                                                                                          profile/pprof
                                                                                          Package pprof provides a pprof profiler
                                                                                          Package pprof provides a pprof profiler
                                                                                          stats
                                                                                          Package stats provides runtime stats
                                                                                          Package stats provides runtime stats
                                                                                          trace
                                                                                          Package trace provides an interface for distributed tracing
                                                                                          Package trace provides an interface for distributed tracing
                                                                                          Package errors provides a way to return detailed information for an RPC request error.
                                                                                          Package errors provides a way to return detailed information for an RPC request error.
                                                                                          Package log provides a log interface
                                                                                          Package log provides a log interface
                                                                                          Package metadata is a way of defining message headers
                                                                                          Package metadata is a way of defining message headers
                                                                                          Package network is for creating p2p networks
                                                                                          Package network is for creating p2p networks
                                                                                          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
                                                                                          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/mucp
                                                                                          Package mucp transparently forwards the incoming request using a go-micro client.
                                                                                          Package mucp transparently forwards the incoming request using a go-micro client.
                                                                                          resolver
                                                                                          Package resolver resolves network names to addresses
                                                                                          Package resolver resolves network names to addresses
                                                                                          resolver/dns
                                                                                          Package dns resolves names to dns records
                                                                                          Package dns resolves names to dns records
                                                                                          resolver/dnssrv
                                                                                          Package dns srv resolves names to dns srv records
                                                                                          Package dns srv resolves names to dns srv records
                                                                                          resolver/http
                                                                                          Package http resolves names to network addresses using a http request
                                                                                          Package http resolves names to network addresses using a http request
                                                                                          resolver/registry
                                                                                          Package registry resolves names using the go-micro registry
                                                                                          Package registry resolves names using the go-micro registry
                                                                                          resolver/static
                                                                                          Package static is a static resolver
                                                                                          Package static is a static resolver
                                                                                          router
                                                                                          Package router provides a network routing control plane
                                                                                          Package router provides a network routing control plane
                                                                                          tunnel
                                                                                          Package tunnel provides gre network tunnelling
                                                                                          Package tunnel provides gre network tunnelling
                                                                                          tunnel/broker
                                                                                          Package broker is a tunnel broker
                                                                                          Package broker is a tunnel broker
                                                                                          tunnel/transport
                                                                                          Package transport provides a tunnel transport
                                                                                          Package transport provides a tunnel transport
                                                                                          Package plugin provides the ability to load plugins
                                                                                          Package plugin provides the ability to load plugins
                                                                                          Package mdns is a multicast dns registry Package registry is an interface for service discovery
                                                                                          Package mdns is a multicast dns registry Package registry is an interface for service discovery
                                                                                          cache
                                                                                          Package cache provides a registry cache
                                                                                          Package cache provides a registry cache
                                                                                          Package runtime is a service runtime manager
                                                                                          Package runtime is a service runtime manager
                                                                                          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.
                                                                                          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.
                                                                                          local
                                                                                          Package local provides a local runtime
                                                                                          Package local provides a local runtime
                                                                                          local/build
                                                                                          Package build builds a micro runtime package
                                                                                          Package build builds a micro runtime package
                                                                                          local/build/docker
                                                                                          Package docker builds docker images
                                                                                          Package docker builds docker images
                                                                                          local/build/go
                                                                                          Package golang is a go package manager
                                                                                          Package golang is a go package manager
                                                                                          local/process
                                                                                          Package process executes a binary
                                                                                          Package process executes a binary
                                                                                          local/process/os
                                                                                          Package os runs processes locally Package os runs processes locally
                                                                                          Package os runs processes locally Package os runs processes locally
                                                                                          local/source
                                                                                          Package source retrieves source code
                                                                                          Package source retrieves source code
                                                                                          local/source/git
                                                                                          Package git provides a git source
                                                                                          Package git provides a git source
                                                                                          local/source/go
                                                                                          Package golang is a source for Go
                                                                                          Package golang is a source for Go
                                                                                          Package selector is a way to pick a list of service nodes
                                                                                          Package selector is a way to pick a list of service nodes
                                                                                          Package server is an interface for a micro server
                                                                                          Package server is an interface for a micro server
                                                                                          Package store is an interface for distributed data storage.
                                                                                          Package store is an interface for distributed data storage.
                                                                                          Package sync is an interface for distributed synchronization
                                                                                          Package sync is an interface for distributed synchronization
                                                                                          Package transport is an interface for synchronous connection based communication
                                                                                          Package transport is an interface for synchronous connection based communication
                                                                                          util
                                                                                          backoff
                                                                                          Package backoff provides backoff functionality
                                                                                          Package backoff provides backoff functionality
                                                                                          buf
                                                                                          ctx
                                                                                          io
                                                                                          Package io is for io management
                                                                                          Package io is for io management
                                                                                          jitter
                                                                                          Package jitter provides a random jitter
                                                                                          Package jitter provides a random jitter
                                                                                          kubernetes/client
                                                                                          Package client provides an implementation of a restricted subset of kubernetes API client
                                                                                          Package client provides an implementation of a restricted subset of kubernetes API client
                                                                                          log
                                                                                          Package log is a global internal logger DEPRECATED: this is frozen package, use github.com/asim/go-micro/v3/logger
                                                                                          Package log is a global internal logger DEPRECATED: this is frozen package, use github.com/asim/go-micro/v3/logger
                                                                                          mux
                                                                                          Package mux provides proxy muxing
                                                                                          Package mux provides proxy muxing
                                                                                          net
                                                                                          pki
                                                                                          Package pki provides PKI all the PKI functions necessary to run micro over an untrusted network including a CA
                                                                                          Package pki provides PKI all the PKI functions necessary to run micro over an untrusted network including a CA
                                                                                          pool
                                                                                          Package pool is a connection pool
                                                                                          Package pool is a connection pool
                                                                                          qson
                                                                                          Package qson implmenets decoding of URL query params into JSON and Go values (using JSON struct tags).
                                                                                          Package qson implmenets decoding of URL query params into JSON and Go values (using JSON struct tags).
                                                                                          ring
                                                                                          Package ring provides a simple ring buffer for storing local data
                                                                                          Package ring provides a simple ring buffer for storing local data
                                                                                          socket
                                                                                          Package socket provides a pseudo socket
                                                                                          Package socket provides a pseudo socket
                                                                                          stream
                                                                                          Package stream encapsulates streams within streams
                                                                                          Package stream encapsulates streams within streams
                                                                                          sync
                                                                                          Package syncs will sync multiple stores
                                                                                          Package syncs will sync multiple stores
                                                                                          tls