README

Go Micro License GoDoc Travis CI Go Report Card

Go Micro is a framework for microservice 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.

Plugins are available at github.com/micro/go-plugins.

Follow us on Twitter or join the Slack community.

Features

Go Micro abstracts away the details of distributed systems. Here are the main features.

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

  • Request/Response - 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. The default transport is http/1.1 or http2 when tls is enabled.

  • 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 is point-to-point http/1.1 or http2 when tls is enabled.

  • 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

See the docs for detailed information on the architecture, installation and use of go-micro.

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 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)) Option

              func Address

              func Address(addr string) Option

                Address sets the address of the server

                func AfterStart

                func AfterStart(fn func() error) Option

                func AfterStop

                func AfterStop(fn func() error) Option

                func BeforeStart

                func BeforeStart(fn func() error) Option

                func BeforeStop

                func BeforeStop(fn func() error) Option

                func Broker

                func Broker(b broker.Broker) Option

                func Client

                func Client(c client.Client) Option

                func Cmd

                func Cmd(c cmd.Cmd) Option

                func Context

                func Context(ctx context.Context) Option

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

                  func Flags

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

                  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 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 Selector

                              func Selector(s selector.Selector) Option

                                Selector sets the selector for the service client

                                func Server

                                func Server(s server.Server) Option

                                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 {
                                            	Broker    broker.Broker
                                            	Cmd       cmd.Cmd
                                            	Client    client.Client
                                            	Server    server.Server
                                            	Registry  registry.Registry
                                            	Transport transport.Transport
                                            
                                            	// 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
                                            }

                                            type Publisher

                                            type Publisher interface {
                                            	Publish(ctx context.Context, msg interface{}, opts ...client.PublishOption) error
                                            }

                                              Publisher is syntactic sugar for publishing

                                              func NewPublisher

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

                                                NewPublisher returns a new Publisher

                                                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
                                                      Package agent provides an interface for building robots
                                                      Package agent provides an interface for building robots
                                                      command
                                                      Package command is an interface for defining bot commands
                                                      Package command is an interface for defining bot commands
                                                      input
                                                      Package input is an interface for bot inputs
                                                      Package input is an interface for bot inputs
                                                      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/broker
                                                      Package broker provides a go-micro/broker handler
                                                      Package broker provides a go-micro/broker handler
                                                      handler/cloudevents
                                                      Package cloudevents provides a cloudevents handler publishing the event using the go-micro/client
                                                      Package cloudevents provides a cloudevents handler publishing the event using the go-micro/client
                                                      handler/event
                                                      Package event provides a handler which publishes an event
                                                      Package event provides a handler which publishes an event
                                                      handler/file
                                                      Package file serves file relative to the current directory
                                                      Package file serves file relative to the current directory
                                                      handler/http
                                                      Package http is a http reverse proxy handler
                                                      Package http is a http reverse proxy handler
                                                      handler/registry
                                                      Package registry is a go-micro/registry handler
                                                      Package registry is a go-micro/registry handler
                                                      handler/rpc
                                                      Package rpc is a go-micro rpc handler.
                                                      Package rpc is a go-micro rpc handler.
                                                      handler/udp
                                                      Package udp reads and write from a udp connection
                                                      Package udp reads and write from a udp connection
                                                      handler/unix
                                                      Package unix reads from a unix socket expecting it to be in /tmp/path
                                                      Package unix reads from a unix socket expecting it to be in /tmp/path
                                                      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/micro
                                                      Package micro provides a micro rpc resolver which prefixes a namespace
                                                      Package micro provides a micro rpc resolver which prefixes a namespace
                                                      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/acme/certmagic
                                                      Package certmagic is the ACME provider from github.com/mholt/certmagic
                                                      Package certmagic is the ACME provider from github.com/mholt/certmagic
                                                      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 broker is an interface used for asynchronous messaging
                                                      Package broker is an interface used for asynchronous messaging
                                                      http
                                                      Package http provides a http based message broker
                                                      Package http provides a http based message broker
                                                      memory
                                                      Package memory provides a memory broker
                                                      Package memory provides a memory broker
                                                      nats
                                                      Package nats provides a NATS broker
                                                      Package nats provides a NATS broker
                                                      service
                                                      Package service provides the broker service client
                                                      Package service provides the broker service client
                                                      Package client is an interface for an RPC client
                                                      Package client is an interface for an RPC client
                                                      grpc
                                                      Package grpc provides a gRPC client Package grpc provides a gRPC options
                                                      Package grpc provides a gRPC client Package grpc provides a gRPC options
                                                      mock
                                                      Package mock provides a mock client for testing
                                                      Package mock provides a mock client for testing
                                                      mucp
                                                      Package mucp provides an mucp client
                                                      Package mucp provides an mucp client
                                                      pool
                                                      Package pool is a connection pool
                                                      Package pool is a connection pool
                                                      selector
                                                      Package selector is a way to pick a list of service nodes
                                                      Package selector is a way to pick a list of service nodes
                                                      selector/dns
                                                      Package dns provides a dns SRV selector
                                                      Package dns provides a dns SRV selector
                                                      selector/registry
                                                      Package registry uses the go-micro registry for selection
                                                      Package registry uses the go-micro registry for selection
                                                      selector/router
                                                      Package router is a network/router selector
                                                      Package router is a network/router selector
                                                      selector/static
                                                      Package static provides a static resolver which returns the name/ip passed in without any change
                                                      Package static provides a static resolver which returns the name/ip passed in without any change
                                                      cmd
                                                      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
                                                      Package proto is a generated protocol buffer package.
                                                      Package proto is a generated protocol buffer package.
                                                      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.
                                                      cmd
                                                      Package cmd is an interface for parsing the command line
                                                      Package cmd is an interface for parsing the command line
                                                      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
                                                      options
                                                      Package options provides a way to initialise options
                                                      Package options provides a way to initialise options
                                                      reader
                                                      Package reader parses change sets and provides config values
                                                      Package reader parses change sets and provides config values
                                                      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
                                                      Package debug provides micro debug packages
                                                      Package debug provides micro debug packages
                                                      buffer
                                                      Package buffer provides a simple ring buffer for storing local data
                                                      Package buffer provides a simple ring buffer for storing local data
                                                      log
                                                      Package log provides debug logging
                                                      Package log provides debug logging
                                                      profile
                                                      Package profile is for profilers
                                                      Package profile is for profilers
                                                      profile/pprof
                                                      Package pprof provides a pprof profiler
                                                      Package pprof provides a pprof profiler
                                                      service/handler
                                                      Pacjage handler implements service debug handler
                                                      Pacjage handler implements service debug handler
                                                      stats
                                                      Package stats provides runtime stats
                                                      Package stats provides runtime stats
                                                      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.
                                                      examples module
                                                      Package metadata is a way of defining message headers
                                                      Package metadata is a way of defining message headers
                                                      Package monitor monitors service health
                                                      Package monitor monitors service health
                                                      Package network is for creating internetworks
                                                      Package network is for creating internetworks
                                                      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
                                                      service/handler
                                                      Package handler implements network RPC handler
                                                      Package handler implements network RPC handler
                                                      Package plugin provides the ability to load plugins Package plugin provides the ability to load plugins
                                                      Package plugin provides the ability to load plugins Package plugin provides the ability to load plugins
                                                      plugins
                                                      auth/jwt Module
                                                      broker/grpc Module
                                                      broker/kafka Module
                                                      broker/nats Module
                                                      client/http Module
                                                      logger/zap Module
                                                      registry/etcd Module
                                                      registry/nats Module
                                                      server/grpc Module
                                                      server/http Module
                                                      Package proxy is a transparent proxy built on the go-micro/server
                                                      Package proxy is a transparent proxy built on the go-micro/server
                                                      grpc
                                                      Package grpc transparently forwards the grpc protocol using a go-micro client.
                                                      Package grpc transparently forwards the grpc protocol using a go-micro client.
                                                      http
                                                      Package http provides a micro rpc to http proxy
                                                      Package http provides a micro rpc to http 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.
                                                      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
                                                      etcd
                                                      Package etcd provides an etcd service registry
                                                      Package etcd provides an etcd service registry
                                                      mdns
                                                      Package mdns provides a multicast dns registry
                                                      Package mdns provides a multicast dns registry
                                                      memory
                                                      Package memory provides an in-memory registry
                                                      Package memory provides an in-memory registry
                                                      service
                                                      Package service uses the registry service
                                                      Package service uses the registry service
                                                      Package router provides a network routing control plane
                                                      Package router provides a network routing control plane
                                                      Package runtime is a service runtime manager
                                                      Package runtime is a service runtime manager
                                                      build
                                                      Package build builds a micro runtime package
                                                      Package build builds a micro runtime package
                                                      build/docker
                                                      Package docker builds docker images
                                                      Package docker builds docker images
                                                      build/go
                                                      Package golang is a go package manager
                                                      Package golang is a go package manager
                                                      kubernetes
                                                      Package kubernetes implements kubernetes micro runtime
                                                      Package kubernetes implements kubernetes micro runtime
                                                      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
                                                      process
                                                      Package process executes a binary
                                                      Package process executes a binary
                                                      process/os
                                                      Package os runs processes locally Package os runs processes locally
                                                      Package os runs processes locally Package os runs processes locally
                                                      source
                                                      Package source retrieves source code
                                                      Package source retrieves source code
                                                      source/git
                                                      Package git provides a git source
                                                      Package git provides a git source
                                                      source/go
                                                      Package golang is a source for Go
                                                      Package golang is a source for Go
                                                      Package server is an interface for a micro server
                                                      Package server is an interface for a micro server
                                                      grpc
                                                      Package grpc provides a grpc server
                                                      Package grpc provides a grpc server
                                                      mucp
                                                      Package mucp provides an mucp server
                                                      Package mucp provides an mucp server
                                                      Package service encapsulates the client, server and other interfaces to provide a complete micro service.
                                                      Package service encapsulates the client, server and other interfaces to provide a complete micro service.
                                                      mucp
                                                      Package mucp initialises a mucp service
                                                      Package mucp initialises a mucp service
                                                      Package store is an interface for distribute data storage.
                                                      Package store is an interface for distribute data storage.
                                                      cloudflare
                                                      Package cloudflare is a store implementation backed by cloudflare workers kv Note that the cloudflare workers KV API is eventually consistent.
                                                      Package cloudflare is a store implementation backed by cloudflare workers kv Note that the cloudflare workers KV API is eventually consistent.
                                                      etcd
                                                      Package etcd is an etcd v3 implementation of kv
                                                      Package etcd is an etcd v3 implementation of kv
                                                      memory
                                                      Package memory is a in-memory store store
                                                      Package memory is a in-memory store store
                                                      postgresql
                                                      Package postgresql implements a micro Store backed by sql
                                                      Package postgresql implements a micro Store backed by sql
                                                      service
                                                      Package service implements the store service interface
                                                      Package service implements the store service interface
                                                      Package sync is a distributed synchronization framework
                                                      Package sync is a distributed synchronization framework
                                                      event
                                                      Package event provides a distributed log interface
                                                      Package event provides a distributed log interface
                                                      leader
                                                      Package leader provides leader election
                                                      Package leader provides leader election
                                                      lock
                                                      Package lock provides distributed locking
                                                      Package lock provides distributed locking
                                                      lock/etcd
                                                      Package etcd is an etcd implementation of lock
                                                      Package etcd is an etcd implementation of lock
                                                      lock/http
                                                      Package http adds a http lock implementation
                                                      Package http adds a http lock implementation
                                                      lock/http/server
                                                      Package server implements the sync http server
                                                      Package server implements the sync http server
                                                      lock/memory
                                                      Package memory provides a sync.Mutex implementation of the lock for local use
                                                      Package memory provides a sync.Mutex implementation of the lock for local use
                                                      task
                                                      Package task provides an interface for distributed jobs
                                                      Package task provides an interface for distributed jobs
                                                      task/broker
                                                      Package broker provides a distributed task manager built on the micro broker
                                                      Package broker provides a distributed task manager built on the micro broker
                                                      task/local
                                                      Package local provides a local task runner
                                                      Package local provides a local task runner
                                                      time
                                                      Package time provides clock synchronization
                                                      Package time provides clock synchronization
                                                      time/local
                                                      Package local provides a local clock
                                                      Package local provides a local clock
                                                      time/ntp
                                                      Package ntp provides ntp synchronized time
                                                      Package ntp provides ntp synchronized time
                                                      Package transport is an interface for synchronous connection based communication
                                                      Package transport is an interface for synchronous connection based communication
                                                      grpc
                                                      Package grpc provides a grpc transport
                                                      Package grpc provides a grpc transport
                                                      http
                                                      Package http returns a http2 transport using net/http
                                                      Package http returns a http2 transport using net/http
                                                      memory
                                                      Package memory is an in-memory transport
                                                      Package memory is an in-memory transport
                                                      quic
                                                      Package quic provides a QUIC based transport
                                                      Package quic provides a QUIC based transport
                                                      Package tunnel provides gre network tunnelling
                                                      Package tunnel provides gre network tunnelling
                                                      broker
                                                      Package broker is a tunnel broker
                                                      Package broker is a tunnel broker
                                                      transport
                                                      Package transport provides a tunnel transport
                                                      Package transport provides a tunnel transport
                                                      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
                                                      log
                                                      Package log is a global internal logger
                                                      Package log is a global internal logger
                                                      mux
                                                      Package mux provides proxy muxing
                                                      Package mux provides proxy muxing
                                                      net
                                                      socket
                                                      Package socket provides a pseudo socket
                                                      Package socket provides a pseudo socket
                                                      tls
                                                      Package web provides web based micro services
                                                      Package web provides web based micro services