announcer

Documentation

Overview

Package announcer encapsulates the idea of a server that dynamically advertizes its presence to clients through various media.

Typical usage:

// On startup:
var a announcer.Announcer
impl, err := announcer.NewFoo(...)
// check err
a.Add(impl)

// When ready to serve:
err = a.Announce(ctx, &membership.Roxy{
	Ready:       true,
	IP:          ipAddr,
	ServerName:  "myserver.example.com", // name on your TLS certificate
	PrimaryPort: mainPort,
	AdditionalPorts: map[string]uint16{
		"foo": fooPort,
		"bar": barPort,
	},
})
// check err

// When about to stop serving:
err = a.Withdraw(ctx)
// check err

// On exit:
err = a.Close()
// check err

Index

• Constants
• func GetDeclaredCPS(ctx context.Context) float64
• func WithDeclaredCPS(ctx context.Context, cps float64) context.Context
• type Announcer
  • func (a *Announcer) Add(impl Interface)
  • func (a *Announcer) Announce(ctx context.Context, r *membership.Roxy) error
  • func (a *Announcer) Close() error
  • func (a *Announcer) State() State
  • func (a *Announcer) Withdraw(ctx context.Context) error
• type Format
  • func (format Format) GoString() string
  • func (format Format) MarshalJSON() ([]byte, error)
  • func (format *Format) Parse(str string) error
  • func (format Format) String() string
  • func (format *Format) UnmarshalJSON(raw []byte) error
• type Interface
  • func NewATC(client *atcclient.ATCClient, serviceName, location, uniqueID, namedPort string) (Interface, error)
  • func NewEtcd(etcd *v3.Client, path, hostID, namedPort string, format Format) (Interface, error)
  • func NewZK(zkconn *zk.Conn, path, hostID, namedPort string, format Format) (Interface, error)
• type State
  • func (state State) GoString() string
  • func (state State) IsReady() bool
  • func (state State) IsRunning() bool
  • func (state State) String() string

Constants

const DeclaredCPSContextKey contextKey = "roxy.announcer.DeclaredCPS"

DeclaredCPSContextKey is the context key for the declared maximum cost-per-second which the server is able to deliver. This is reported by the ATC announcer for load-balancing purposes.

Functions

func GetDeclaredCPS

func GetDeclaredCPS(ctx context.Context) float64

GetDeclaredCPS retrieves the declared maximum cost-per-second, or 0.

func WithDeclaredCPS

func WithDeclaredCPS(ctx context.Context, cps float64) context.Context

WithDeclaredCPS attaches the declared maximum cost-per-second to the given Context.

Types

type Announcer

type Announcer struct {
	// contains filtered or unexported fields
}

Announcer is a multiplexer implementation of Interface that distributes method calls to multiple announcers.

func (*Announcer) Add

func (a *Announcer) Add(impl Interface)

Add adds a child announcer. Both Announcer and the child announcer must be in the ready state, or Add will panic.

func (*Announcer) Announce

func (a *Announcer) Announce(ctx context.Context, r *membership.Roxy) error

Announce broadcasts to all child announcers that the service is available at the given address.

Announcer must be in the ready state, or Announce will panic. A successful call to this method changes Announcer's state from the ready state to the running state.

func (*Announcer) Close

func (a *Announcer) Close() error

Close broadcasts to all child announcers that no further announcements are coming and that they should clean up any resources.

If Announcer is already in the closed state, nothing is done and fs.ErrClosed is returned. If Announcer is in neither the ready state nor the closed state, Close will panic. Any call to this method changes Announcer's state to the closed state.

func (*Announcer) State

func (a *Announcer) State() State

State returns the current state of the Announcer.

func (*Announcer) Withdraw

func (a *Announcer) Withdraw(ctx context.Context) error

Withdraw broadcasts to all child announcers that the service is no longer available.

Announcer must be in the running state, or Withdraw will panic. Any call to this method changes Announcer's state from the running state to the ready state.

type Format

type Format uint8

Format selects which server advertisement serialization format to use.

const (
	// RoxyFormat selects Roxy's native JSON format.
	RoxyFormat Format = iota

	// FinagleFormat selects the Finagle ServerSet JSON format.
	FinagleFormat

	// GRPCFormat selects the etcd.io gRPC JSON format.
	GRPCFormat
)

func (Format) GoString

func (format Format) GoString() string

GoString fulfills fmt.GoStringer.

func (Format) MarshalJSON

func (format Format) MarshalJSON() ([]byte, error)

MarshalJSON fulfills json.Marshaler.

func (*Format) Parse

func (format *Format) Parse(str string) error

Parse parses from a string value.

func (Format) String

func (format Format) String() string

String fulfills fmt.Stringer.

func (*Format) UnmarshalJSON

func (format *Format) UnmarshalJSON(raw []byte) error

UnmarshalJSON fulfills json.Unmarshaler.

type Interface

type Interface interface {
	Announce(ctx context.Context, r *membership.Roxy) error
	Withdraw(ctx context.Context) error
	Close() error
}

Interface is the interface provided by announcers for specific protocols.

func NewATC

func NewATC(client *atcclient.ATCClient, serviceName, location, uniqueID, namedPort string) (Interface, error)

NewATC creates a new Roxy Air Traffic Control announcer.

func NewEtcd

func NewEtcd(etcd *v3.Client, path, hostID, namedPort string, format Format) (Interface, error)

NewEtcd creates a new etcd.io announcer.

func NewZK

func NewZK(zkconn *zk.Conn, path, hostID, namedPort string, format Format) (Interface, error)

NewZK creates a new ZooKeeper announcer.

type State

type State uint8

State is used to keep track of which Announcer methods have been called.

const (
	// StateReady marks that Announce() or Close() may be called.
	StateReady State = iota

	// StateRunning marks that Withdraw() may be called, and that the
	// announcement may be active.
	StateRunning

	// StateDead marks that Withdraw() may be called, and that the
	// announcement has ended due to a context cancellation or the like.
	StateDead

	// StateClosed marks that no more methods may be called.
	StateClosed
)

func (State) GoString

func (state State) GoString() string

GoString fulfills fmt.GoStringer.

func (State) IsReady

func (state State) IsReady() bool

IsReady returns true if it is safe to call Announce.

func (State) IsRunning

func (state State) IsRunning() bool

IsRunning returns true if Withdraw needs to be called.

func (State) String

func (state State) String() string

String fulfills fmt.Stringer.