server

Documentation

Overview

Package server provides the go-micro server. It is responsible for managing entrypoints.

Entrypoints

Entrypoints are the actual servers used that listen for incoming requests. Various entrypoint plugins are provided by default, but it is straight forward to create your own entrypoint implementation. Entrypoints are configured through functional options, and your config file. Entrypionts can be dynamically added, modified, or disabled through your config files.

Handler registrations

Entrypoints can be used in any number of combinations. The handlers are registered by providing registration functions to the entrypoint config. A handler registration function takes care of registering the handler in the server specific way. While internal project handlers are designed such that they can be used with any type of server out of the box, the way they are registered usually differs per server type. Registration functions take care of this by switching on the server type. This also allows you to create server specific handlers if necessary.

Internal handlers

The server has been architected with protobuf service definitions as primary handler types. Thus registration of these has been made as easy as possible. For proto services defined within your go-micro project, registration functions will be automatically generated for you, and you only need to provide the handler implementation, everything beyond is taken care of.

External handlers

You may wish to register either external proto service handlers, or server specific handlers such as any existing HTTP handlers. THis is also possible. External proto services can be registered with the help of the NewRegistrationFunc type, which utliizes the power of generics to allow you to convert any gRPC registration into an entrypoint registration function. It is also possible to manually define your own registration functions. These must take one parameter of type any and convert it into the required server type, such as the go-micro HTTP server, or the go-micro gRPC server.

Index

• Constants
• Variables
• type Config
  • func NewConfig(options ...Option) Config
  • func (c *Config) ApplyOptions(options ...Option)
  • func (c *Config) UnmarshalJSON(data []byte) error
  • func (c *Config) UnmarshalYAML(data *yaml.Node) error
• type Entrypoint
• type EntrypointConfig
• type EntrypointTemplate
• type HandlerRegistrations
  • func (m HandlerRegistrations) MarshalJSON() ([]byte, error)
  • func (m HandlerRegistrations) MarshalYAML() ([]byte, error)
  • func (m HandlerRegistrations) UnmarshalJSON(data []byte) error
  • func (m HandlerRegistrations) UnmarshalText(data []byte) error
  • func (m HandlerRegistrations) UnmarshalYAML(data *yaml.Node) error
• type MicroServer
  • func ProvideServer(name types.ServiceName, data types.ConfigData, logger log.Logger, ...) (MicroServer, error)
  • func (s *MicroServer) GetEntrypoint(name string) (Entrypoint, error)
  • func (s *MicroServer) Start() error
  • func (s *MicroServer) Stop(ctx context.Context) error
  • func (s *MicroServer) String() string
  • func (s *MicroServer) Type() string
• type NewDefault
• type Option
• type ProviderFunc
• type RegistrationFunc
  • func NewRegistrationFunc[Tsrv any, Thandler any](register func(Tsrv, Thandler), handler Thandler) RegistrationFunc

Constants

const ComponentType = "server"

ComponentType is the server component type name.

Variables

var (
	ErrInvalidEpSecType  = errors.New("config section entrypoints should be a list")
	ErrInvalidEpItemType = errors.New("config section entrypoints item should be a map")
	ErrInvalidServerType = errors.New("config section server plugins should be a map")
)

Errors.

var (
	// Plugins is the plugins container for registry.
	Plugins = container.NewPlugins[ProviderFunc]()

	// NewDefaults is the factory container for defaults.
	NewDefaults = container.NewPlugins[NewDefault]()

	// Handlers is a container of registration functions that can be used to
	// dynamically configure entrypoints.
	//
	// You need to register your handlers with a registration function to use it.
	// Example:
	//     Handlers.Register("myHandler", RegisterEchoHandler)
	Handlers = container.NewPlugins[RegistrationFunc]()
)

var DefaultConfigSection = "server" //nolint:gochecknoglobals

DefaultConfigSection is the section key used in config files used to configure the server options.

var (
	ErrEntrypointNotFound = errors.New("requested entrypoint not found")
)

Errors.

Types

type Config

type Config struct {
	// Enabled keeps track of whether server plugins are globally disabled or not.
	Enabled map[string]bool

	// Defaults is the list of defaults the each server plugin.
	// Provisioned with the factory methods registered by the entrypoint plugins.
	Defaults map[string]EntrypointConfig

	// Templates contains a set of entrypoint templates to create, indexed by name.
	//
	// Each entrypoint needs a unique name, as each entrypoint can be dynamically
	// configured by referencing the name. The default name used in an entrypoint
	// is the format of "http-<uuid>", used if no custom name is provided.
	Templates map[string]EntrypointTemplate
}

Config is the server config. It contains the list of addresses on which entrypoints will be created, and the default config used for each entrypoint.

func NewConfig

func NewConfig(options ...Option) Config

NewConfig creates a new server config with default values as starting point, after which all the functional options are applied.

func (*Config) ApplyOptions

func (c *Config) ApplyOptions(options ...Option)

ApplyOptions takes a list of options and applies them to the current config.

func (*Config) UnmarshalJSON

func (c *Config) UnmarshalJSON(data []byte) error

UnmarshalJSON extracts the entrypoint configuration from a file config.

func (*Config) UnmarshalYAML

func (c *Config) UnmarshalYAML(data *yaml.Node) error

UnmarshalYAML extracts the entrypoint configuration from a file config.

type Entrypoint

type Entrypoint interface {
	types.Component

	// Register is used to register handlers.
	//
	// A registration function takes a pointer to the server, which can then
	// be used to register handlers in the server specific way.
	Register(RegistrationFunc)

	// Address returns the address the entrypoint is listening on.
	Address() string
}

Entrypoint is a server, and represents an entrypoint into the web.

type EntrypointConfig

type EntrypointConfig interface {
	// TODO: as long as https://github.com/golang/go/issues/48522 is open, we need
	// this interface. But should be removed after in favor of some generic
	// constraint to identify entrypoint configs and access common fields.
	GetAddress() string
	Copy() EntrypointConfig
}

EntrypointConfig provides a primitive way to constrain entrypoint config types. It should be implemented by every server plugin.

This interface is a hack around the fact that you cannot create custom type constraints on common struct fields, as described in golang/go/issues/48522. Once this issue is solved, this interface should be replaced in favor of which ever new semantics get introduced.

type EntrypointTemplate

type EntrypointTemplate struct {
	Enabled bool

	// Type is the entrypoint type to use. To use a specific server type as
	// entrypiont the provider function needs to be registered as an entrypoint
	// plugin. This is done by importing the package, typically done with a named
	// import as _.
	Type string

	// Config is the configuration used to create the entrypoint. The default
	// options are used as starting point, to which this list of options will be
	// applied as provided through both the fuctional options and any file config.
	// The result will be your full entrypoint configuration.
	//
	// By default, a random port will be chosen for the entrypoint to listen on,
	// defined as ":0". For all options not specified, default values will be used.
	// TODO: do we really use :0 as address, or the v4 code to identify an interface?
	Config EntrypointConfig
}

EntrypointTemplate is the configuation used to create a single entrypoint.

You will rarely need to manually create a template object, it will be done for you through the provided server options.

type HandlerRegistrations

type HandlerRegistrations map[string]RegistrationFunc

HandlerRegistrations type is a map of regirstration functions for an entrypoint. A custom type is used to manually define the json/yaml unmarshal behavior, as we don't want to overwrite the list, we only want to add on to it with a config file.

func (HandlerRegistrations) MarshalJSON

func (m HandlerRegistrations) MarshalJSON() ([]byte, error)

MarshalJSON no-op.

func (HandlerRegistrations) MarshalYAML

func (m HandlerRegistrations) MarshalYAML() ([]byte, error)

MarshalYAML no-op.

func (HandlerRegistrations) UnmarshalJSON

func (m HandlerRegistrations) UnmarshalJSON(data []byte) error

UnmarshalJSON handler registrations list.

func (HandlerRegistrations) UnmarshalText

func (m HandlerRegistrations) UnmarshalText(data []byte) error

UnmarshalText handler registrations list..

func (HandlerRegistrations) UnmarshalYAML

func (m HandlerRegistrations) UnmarshalYAML(data *yaml.Node) error

UnmarshalYAML handler registrations list.

type MicroServer

type MicroServer struct {
	Logger log.Logger
	Config Config
	// contains filtered or unexported fields
}

MicroServer is repsponsible for managing entrypoints. Entrypoints are the actual servers that bind to a port and accept connections. Entrypoints can be dynamically configured.

For more info look at the entrypoint types.

func ProvideServer

func ProvideServer(name types.ServiceName, data types.ConfigData, logger log.Logger, opts ...Option) (MicroServer, error)

ProvideServer creates a new server.

func (*MicroServer) GetEntrypoint

func (s *MicroServer) GetEntrypoint(name string) (Entrypoint, error)

GetEntrypoint returns the requested entrypoint, if present.

func (*MicroServer) Start

func (s *MicroServer) Start() error

Start will start the HTTP servers on all entrypoints.

func (*MicroServer) Stop

func (s *MicroServer) Stop(ctx context.Context) error

Stop will stop the HTTP servers on all entrypoints and close the listeners.

func (*MicroServer) String

func (s *MicroServer) String() string

String is no-op.

func (*MicroServer) Type

func (s *MicroServer) Type() string

Type returns the micro component type.

type NewDefault

type NewDefault func() EntrypointConfig

NewDefault is a factory function type for entrypoint defaults, registered by the plugins.

type Option

type Option func(*Config)

Option is a functional HTTP server option.

type ProviderFunc

type ProviderFunc func(
	service types.ServiceName,
	logger log.Logger,

	config any,
) (Entrypoint, error)

ProviderFunc is the function type to create a new entrypoint. ProviderFuncs are registered in the plugins container, and can be called at runtime depending on the configuration.

type RegistrationFunc

type RegistrationFunc func(srv any)

RegistrationFunc is executed to register a handler to a server (entrypoint) passed as srv. srv can be of any of the various server types, should be a pointer.

You can write your own custom registration functions to register extra handlers.

Inside the registration function, you need to convert the server type and assert that you are working with the server type you are expecting, and otherwise no-op. For an example, see the implementation of NewRegistrationFunc.

func NewRegistrationFunc

func NewRegistrationFunc[Tsrv any, Thandler any](register func(Tsrv, Thandler), handler Thandler) RegistrationFunc

NewRegistrationFunc takes a registration function and handler and returns a registration func that can be used with one specific server type.

This function is useful if a user wants to register a non-micro project proto handler. For any internal proto services generated in your project you will already have a pre-defined registration function which only needs the handler implementation.