beacon

Documentation

Index

• Constants
• Variables
• type Action
• type Backend
• type Beacon
  • func New(runtime Runtime, routes []Route) (Beacon, error)
• type Binding
  • func (b *Binding) Copy() *Binding
  • func (b *Binding) Equal(c *Binding) bool
• type Container
  • func (c *Container) Copy() *Container
  • func (c *Container) Equal(b *Container) bool
• type Event
  • func (e *Event) Copy() *Event
• type Filter
  • func NewFilter(labels map[string]string) Filter
  • func ParseFilter(pattern string) (Filter, error)
• type Protocol
• type Route
  • func NewRoute(filter Filter, backend Backend) Route
• type Runtime

Constants

const (
	Start  Action = "start"  // Container started.
	Stop          = "stop"   // Container stopped.
	Update        = "update" // Container updated.
)

Available event action values.

Variables

var Logger = log.New(os.Stdout, "", 0)

Logger is used by the package to log events. It may be set to the application logger to change the destination.

Types

type Action

type Action string

Action is the thing that's happening to the container.

type Backend

type Backend interface {
	// ProcessEvent instructs the backend to handle an event. This is called in
	// the main event processing loop and so should not block. If ProcessEvent
	// panics it will fail through the Beacon Run function.
	ProcessEvent(event *Event) error

	// Close frees any resources associated with the backend. It blocks until
	// the backend completes processing of all in-flight events.
	Close() error
}

Backend recieves events routed to it by Beacon.

type Beacon

type Beacon interface {
	// Run retrieves events from a runtime and routes them to the appropriate
	// backends. Run also maintains internal state for the Containers method.
	//
	// Run returns an error immediately if the runtime's EmitEvents method
	// fails. It will otherwise block until the runtime channel is closed.
	//
	// The runtime channel can be closed by calling Close either on Beacon or
	// by calling Close on the runtime directly. Beacon's Close method simply
	// wraps the runtime's Close method.
	//
	// Run will drain the channel of events before calling Close on each of the
	// backends. It then exits. An error is returned during if a failure occurs
	// in any of these steps. This error should be considered fatal as there is
	// no way to know the state of each of the involved components.
	Run() error

	// Close the beacon. Stops a running beacon and cleans up any resources
	// attached to it.
	Close() error

	// Containers retrieves the list of containers that Beacon has discovered.
	// An optional filter may be provided in order to limit the containers
	// returned.
	Containers(filter Filter) []*Container
}

Beacon processes events from a runtime into one or more backends. It maintains state for containers it sees and provides methods for interacting with that state.

func New

func New(runtime Runtime, routes []Route) (Beacon, error)

New creates a Beacon which receieves events from the `runtime` and uses `routes` to queue them into appropriate backends. New does not start the Beacon.

type Binding

type Binding struct {
	HostIP        string   // The IP on the host where the host port is accessible.
	HostPort      int      // The port on the host that maps to the container's port.
	ContainerPort int      // The port the container is listening on.
	Protocol      Protocol // The protocol the port is configured for.
}

Binding represents a bound container port on a host. This contains two logical components: the IP and port where an external service can connect to the container; and the internal port that the container itself is listening on. The protocol is, of course, the same for both the host port and container port.

func (*Binding) Copy

func (b *Binding) Copy() *Binding

Copy allocates a copy of the Binding.

func (*Binding) Equal

func (b *Binding) Equal(c *Binding) bool

Equal returns true if this Binding is equal to another.

type Container

type Container struct {
	// The globally unique identifier of the container. This is typically set
	// by the underlying container implementation.
	ID string

	// The name of the service to which the container belongs. Determined by
	// the event listener.
	Service string

	// The label metadata attached to the container.
	Labels map[string]string

	// Network port bindings.
	Bindings []*Binding
}

Container represents a single container belonging to a service. All fields are considered to be immutable with exceptions for the state fields.

func (*Container) Copy

func (c *Container) Copy() *Container

Copy allocates a copy of the Container.

func (*Container) Equal

func (c *Container) Equal(b *Container) bool

Equal returns true if this container is equal to another.

type Event

type Event struct {
	// The action that triggered this event.
	Action Action

	// The container affected by this event.
	Container *Container
}

Event indicates when the status of a container changes.

func (*Event) Copy

func (e *Event) Copy() *Event

Copy allocates a copy of the Event.

type Filter

type Filter interface {
	MatchContainer(*Container) bool
}

Filter is used to match containers againston a set of criteria.

func NewFilter

func NewFilter(labels map[string]string) Filter

NewFilter creates a new filter which returns true if a container has all of the provided labels.

func ParseFilter

func ParseFilter(pattern string) (Filter, error)

ParseFilter creates a filter from the provided pattern. The pattern has the form 'label1=value1,label2=value2,...'. The container must match all of the lable/value pairs. Only matching against labels is currently supported.

type Protocol

type Protocol string

Protocol is the IP protocol of a container port.

const (
	TCP Protocol = "tcp" // The port speaks TCP.
	UDP          = "udp" // The port speaks UDP.
)

Available protocol values.

type Route

type Route interface {
	Filter
	Backend
}

Route processes events which match a particular filter pattern.

func NewRoute

func NewRoute(filter Filter, backend Backend) Route

NewRoute creates a route from the provided filter and backend.

type Runtime

type Runtime interface {
	// EmitEvents returns an event channel which emits container events. This
	// is called once by Beacon to receive events.
	EmitEvents() (<-chan *Event, error)

	// Close closes any open channels returned by Events. It also cleans up any
	// other resources. This is called once by Beacon when its Close is called.
	Close() error
}

Runtime generates events from a container runtime.