naming

Documentation

Overview

Package naming is a library that converts a target to one or multiple network addresses. A target can be actively watched for updates.

Index

• Variables
• func Register(name string, r Builder)
• func Resolvers() []string
• func SetDefaultScheme(s string)
• type Builder
• type Operation
• type Resolver
  • func DNS(ctx context.Context, freq ...time.Duration) Resolver
  • func Disco(ctx context.Context, tags ...string) Resolver
  • func Passthrough(ctx context.Context) Resolver
  • func URI(ctx context.Context) Resolver
• type Update
• type Watcher
  • func Resolve(ctx context.Context, uri string) (Watcher, error)

Variables

var (
	ErrWatcherClosed = errors.New("watcher closed")
)

Functions

func Register

func Register(name string, r Builder)

Register makes a resolver available by the provided name. If a resolver is registered twice or if it is nil, it will panic.

func Resolvers

func Resolvers() []string

Resolvers returns the list of all registered resolvers

func SetDefaultScheme

func SetDefaultScheme(s string)

SetDefaultScheme defines the default scheme to use when the URI does not have it

Types

type Builder

type Builder func(ctx context.Context, uri *url.URL) (Watcher, error)

Builder is a function that builds a watcher from a URI

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 exisiting address is deleted.
	Delete
)

type Resolver

type Resolver interface {
	// Resolve creates a Watcher for target.
	Resolve(target string) (Watcher, error)
}

Resolver creates a Watcher for a target to track its resolution changes.

func DNS

func DNS(ctx context.Context, freq ...time.Duration) Resolver

DNS creates a DNS Resolver that can resolve DNS names, and create watchers that poll the DNS server using the frequency set by freq or the default frequency defined by defaultFreq.

func Disco

func Disco(ctx context.Context, tags ...string) Resolver

Disco creates a Disco Resolver that uses service discovery to find available instances. It also creates watchers that listen to service discovery updates

func Passthrough

func Passthrough(ctx context.Context) Resolver

Passthrough returns a resolver that defer the name resolution to the client

func URI

func URI(ctx context.Context) Resolver

URI returns a resolver that uses the target URI scheme to select a real resolver

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() error
}

Watcher watches for the updates on the specified target.

func Resolve

func Resolve(ctx context.Context, uri string) (Watcher, error)

Resolve builds a watcher from the given URI

A fully qualified, self contained name used channel construction uses the syntax:

scheme://authority/endpoint_name