otetcd

Documentation

Overview

Package otetcd provides etcd client with opentracing. For documentation about etcd usage, see https://github.com/etcd-io/etcd/tree/master/client/v3

Integration

package otetcd exports the configuration in the following format:

	etcd:
	  default:
        autoSyncIntervalSecond: 0
        dialKeepAliveTimeSecond: 0
        dialKeepAliveTimeoutSecond: 0
        dialTimeoutSecond: 0
        endpoints:
        - 127.0.0.1:2379
        maxCallRecvMsgSize: 0
        maxCallSendMsgSize: 0
        password: ""
        permitWithoutStream: false
        rejectOldCluster: false
        username: ""

Add the etcd dependency to core:

var c *core.C = core.New()
c.Provide(otetcd.Providers())

Then you can invoke etcd from the application.

c.Invoke(func(client *clientv3.Client) {
	// Do something with etcd v3
})

Sometimes there are valid reasons to connect to more than one etcd server. Inject otetcd.Maker to factory a *clientv3.Client with a specific configuration entry.

c.Invoke(function(maker otetcd.Maker) {
	client, err := maker.Make("default")
	// do something with client
})

Example

if os.Getenv("ETCD_ADDR") == "" {
	fmt.Println("set ETCD_ADDR to run example")
	return
}
c := core.New()
c.ProvideEssentials()
c.Provide(otetcd.Providers())
c.Invoke(func(cli *clientv3.Client) {
	_, err := cli.Put(context.TODO(), "foo", "bar")
	if err != nil {
		log.Fatal("etcd put failed")
	}
	resp, _ := cli.Get(context.TODO(), "foo")
	for _, ev := range resp.Kvs {
		fmt.Printf("%s : %s\n", ev.Key, ev.Value)
	}
})

Output:

foo : bar

Index

• func Providers(opts ...ProvidersOptionFunc) di.Deps
• type EtcdConfigInterceptor
• type Factory
  • func (r Factory) Make(name string) (*clientv3.Client, error)
• type Maker
• type Option
• type ProvidersOptionFunc
  • func WithConfigInterceptor(interceptor EtcdConfigInterceptor) ProvidersOptionFunc
  • func WithReload(shouldReload bool) ProvidersOptionFunc

Examples

• Package

Functions

func Providers

func Providers(opts ...ProvidersOptionFunc) di.Deps

Providers returns a set of dependencies including the Maker, the default *clientv3.Client and the exported configs.

Depends On:
	log.Logger
	contract.ConfigAccessor
	opentracing.Tracer    `optional:"true"`
Provide:
	Maker
	Factory
	*clientv3.Client

Types

type EtcdConfigInterceptor

type EtcdConfigInterceptor func(name string, options *clientv3.Config)

EtcdConfigInterceptor is an injector type hint that allows user to do last minute modification to etcd configurations. This is useful when some configuration can not be expressed in yaml/json. For example, the *tls.Config.

type Factory

type Factory struct {
	*di.Factory
}

Factory is a *di.Factory that creates *clientv3.Client using a specific configuration entry.

func (Factory) Make

func (r Factory) Make(name string) (*clientv3.Client, error)

Make creates *clientv3.Client using a specific configuration entry.

type Maker

type Maker interface {
	Make(name string) (*clientv3.Client, error)
}

Maker is models Factory

type Option

type Option struct {
	// Endpoints is a list of URLs.
	Endpoints []string `json:"endpoints" yaml:"endpoints"`

	// AutoSyncInterval is the interval to update endpoints with its latest members.
	// 0 disables auto-sync. By default auto-sync is disabled.
	AutoSyncInterval config.Duration `json:"autoSyncInterval" yaml:"autoSyncInterval"`

	// DialTimeout is the timeout for failing to establish a connection.
	DialTimeout config.Duration `json:"dialTimeout" yaml:"dialTimeout"`

	// DialKeepAliveTime is the time after which client pings the server to see if
	// transport is alive.
	DialKeepAliveTime config.Duration `json:"dialKeepAliveTime" yaml:"dialKeepAliveTime"`

	// DialKeepAliveTimeout is the time that the client waits for a response for the
	// keep-alive probe. If the response is not received in this time, the connection is closed.
	DialKeepAliveTimeout config.Duration `json:"dialKeepAliveTimeout" yaml:"dialKeepAliveTimeout"`

	// MaxCallSendMsgSize is the client-side request send limit in bytes.
	// If 0, it defaults to 2.0 MiB (2 * 1024 * 1024).
	// Make sure that "MaxCallSendMsgSize" < server-side default send/recv limit.
	// ("--max-request-bytes" flag to etcd or "embed.Config.MaxRequestBytes").
	MaxCallSendMsgSize int `json:"maxCallSendMsgSize" yaml:"maxCallSendMsgSize"`

	// MaxCallRecvMsgSize is the client-side response receive limit.
	// If 0, it defaults to "math.MaxInt32", because range response can
	// easily exceed request send limits.
	// Make sure that "MaxCallRecvMsgSize" >= server-side default send/recv limit.
	// ("--max-request-bytes" flag to etcd or "embed.Config.MaxRequestBytes").
	MaxCallRecvMsgSize int `json:"maxCallRecvMsgSize" yaml:"MaxCallRecvMsgSize"`

	// TLS holds the client secure credentials, if any.
	TLS *tls.Config `json:"-" yaml:"-"`

	// Username is a user name for authentication.
	Username string `json:"username" yaml:"username"`

	// Password is a password for authentication.
	Password string `json:"password" yaml:"password"`

	// RejectOldCluster when set will refuse to create a client against an outdated cluster.
	RejectOldCluster bool `json:"rejectOldCluster" yaml:"rejectOldCluster"`

	// DialOptions is a list of dial options for the grpc client (e.g., for interceptors).
	// For example, pass "grpc.WithBlock()" to block until the underlying connection is up.
	// Without this, Dial returns immediately and connecting the server happens in background.
	DialOptions []grpc.DialOption `json:"-" yaml:"-"`

	// Context is the default client context; it can be used to cancel grpc dial out and
	// other operations that do not have an explicit context.
	Context context.Context `json:"-" yaml:"-"`

	// LogConfig configures client-side logger.
	// If nil, use the default logger.
	// TODO: configure gRPC logger
	LogConfig *zap.Config `json:"-" yaml:"-"`

	// PermitWithoutStream when set will allow client to send keepalive pings to server without any active streams(RPCs).
	PermitWithoutStream bool `json:"permitWithoutStream" yaml:"permitWithoutStream"`
}

Option is a type that holds all of available etcd configurations.

type ProvidersOptionFunc

type ProvidersOptionFunc func(options *providersOption)

ProvidersOptionFunc is the type of functional providersOption for Providers. Use this type to change how Providers work.

func WithConfigInterceptor

func WithConfigInterceptor(interceptor EtcdConfigInterceptor) ProvidersOptionFunc

WithConfigInterceptor instructs the Providers to accept the EtcdConfigInterceptor so that users can change config during runtime. This can be useful when some dynamic computations on configs are required.

func WithReload

func WithReload(shouldReload bool) ProvidersOptionFunc

WithReload toggles whether the factory should reload cached instances upon OnReload event.