naming

Documentation

Overview

Package naming provides an etcd-backed gRPC resolver for discovering gRPC services.

To use, first import the packages:

import (
	"github.com/hanjm/etcd/clientv3"
	etcdnaming "github.com/hanjm/etcd/clientv3/naming"

	"google.golang.org/grpc"
	"google.golang.org/grpc/naming"
)

First, register new endpoint addresses for a service:

func etcdAdd(c *clientv3.Client, service, addr string) error {
	r := &etcdnaming.GRPCResolver{Client: c}
	return r.Update(c.Ctx(), service, naming.Update{Op: naming.Add, Addr: addr})
}

Dial an RPC service using the etcd gRPC resolver and a gRPC Balancer:

func etcdDial(c *clientv3.Client, service string) (*grpc.ClientConn, error) {
	r := &etcdnaming.GRPCResolver{Client: c}
	b := grpc.RoundRobin(r)
	return grpc.Dial(service, grpc.WithBalancer(b))
}

Optionally, force delete an endpoint:

func etcdDelete(c *clientv3, service, addr string) error {
	r := &etcdnaming.GRPCResolver{Client: c}
	return r.Update(c.Ctx(), service, naming.Update{Op: naming.Delete, Addr: "1.2.3.4"})
}

Or register an expiring endpoint with a lease:

func etcdLeaseAdd(c *clientv3.Client, lid clientv3.LeaseID, service, addr string) error {
	r := &etcdnaming.GRPCResolver{Client: c}
	return r.Update(c.Ctx(), service, naming.Update{Op: naming.Add, Addr: addr}, clientv3.WithLease(lid))
}

Package naming defines the naming API and related data structures for gRPC.

Index

• Variables
• type GRPCResolver
  • func (gr *GRPCResolver) Resolve(target string) (Watcher, error)
  • func (gr *GRPCResolver) Update(ctx context.Context, target string, nm Update, opts ...etcd.OpOption) (err error)
• type Operation
• type Update
• type Watcher

Variables

var ErrWatcherClosed = fmt.Errorf("naming: watch closed")

Types

type GRPCResolver

type GRPCResolver struct {
	// Client is an initialized etcd client.
	Client *etcd.Client
}

GRPCResolver creates a grpc.Watcher for a target to track its resolution changes.

func (*GRPCResolver) Resolve

func (gr *GRPCResolver) Resolve(target string) (Watcher, error)

func (*GRPCResolver) Update

func (gr *GRPCResolver) Update(ctx context.Context, target string, nm Update, opts ...etcd.OpOption) (err error)

type Operation

type Operation uint8

Operation defines the corresponding operations for a name resolution change.

const (
	// Add indicates a new address is added.
	Add Operation = iota
	// Delete indicates an existing address is deleted.
	Delete
)

type Update

type Update struct {
	// Op indicates the operation of the update.
	Op Operation
	// Addr is the updated address. It is empty string if there is no address update.
	Addr string
	// Metadata is the updated metadata. It is nil if there is no metadata update.
	// Metadata is not required for a custom naming implementation.
	Metadata interface{}
}

Update defines a name resolution update. Notice that it is not valid having both empty string Addr and nil Metadata in an Update.

type Watcher

type Watcher interface {
	// Next blocks until an update or error happens. It may return one or more
	// updates. The first call should get the full set of the results. It should
	// return an error if and only if Watcher cannot recover.
	Next() ([]*Update, error)
	// Close closes the Watcher.
	Close()
}

Watcher watches for the updates on the specified target.