beacon

type Action string

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
}

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
}

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.
}

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
}

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

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

type Filter interface {
	MatchContainer(*Container) bool
}

type Protocol string

type Route interface {
	Filter
	Backend
}

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
}