gate

type Client struct {
	// Closed is the optional round tripper invoked when the gate is closed.  If this
	// field is unset, then a nil *http.Response and a *ClosedError are returned when
	// the gate status indicates closed.
	Closed http.RoundTripper

	// Gate is the Status that indicates whether a gate allows traffic.  If this field
	// is unset, this middleware is a nop.
	Gate Status
}

type ClosedError struct {
	// Gate represents the gate instance that was closed at the time of the error.
	// Note that this gate may have been opened in the time that a caller waited on
	// the call to produce this error.
	Gate Status
}

type Config struct {
	// Name is an optional identifier for this gate.  The Gate itself does not make
	// use of this value.  It's purely for distinguishing gates when an application
	// uses more than one (1) gate.
	Name string

	// InitiallyClosed indicates the state of a Gate when it is created.  The default
	// is to create a Gate that is open.  If this field is true, the Gate is created
	// in the closed state.
	InitiallyClosed bool

	// Hooks is the optional set of preregistered callbacks when a gate is created with this
	// configuration.  Any empty hooks are silently ignored.
	//
	// Any callbacks that match the initial state of the gate, e.g. OnOpen when InitiallyClosed
	// is false, are immediately invoked before New returns.
	Hooks Hooks
}

type Control interface {
	// Open raises this gate to allow traffic.  This method is atomic and idempotent.  It returns
	// true if there was a state change, false to indicate the gate was already open.
	Open() bool

	// Close lowers this gate to reject traffic.  This method is atomic and idempotent.  It returns
	// true if there was a state change, false to indicate the gate was already closed.
	Close() bool

	// Register adds a tuple of callbacks to this status instance.  If the given Hook
	// has no callbacks set, this method does nothing.
	//
	// Callbacks registered for the current state, e.g. OnOpen registered against an open gate,
	// will be immediately invoked prior to this method returning.
	Register(Hook)
}

type ControlHandler struct {
	// StateChange is the required strategy for determining how to change a gate
	// given an HTTP request.  This closure can examine any aspect of the request, e.g.
	// URL parameters, request URI, etc, to determine what state change should occur.
	//
	// This closure can return StateNoChange to indicate that the handler should do nothing
	// to a gate.  For example, the request may fail a security permissions check.
	StateChange func(*http.Request) StateChange

	// Gate is the required gate control instance used to open and close the gate
	Gate Control
}

type Hook struct {
	// OnOpen is invoked any time a gate is opened.  If a gate is open when this callback
	// is registered, it will be immediately invoked.
	//
	// Note: Callbacks should never modify the gate.  The Status instance passed to all callbacks
	// is not castable to Control.
	OnOpen func(Status)

	// OnClose is invoked any time a gate is closed.  If a gate is closed when this
	// callback is registered, it will be immediately invoked.
	//
	// Note: Callbacks should never modify the gate.  The Status instance passed to all callbacks
	// is not castable to Control.
	OnClosed func(Status)
}

type Hooks []Hook

type Interface interface {
	Status
	Control
}

type Server struct {
	// Closed is the optional handler to be invoked with the gate is closed.
	// If this field is not set, http.StatusServiceUnavailable is written
	// to the response.
	//
	// A convenient, configurable handler for this field is httpaux.ConstantHandler.
	Closed http.Handler

	// Gate is the Status that indicates whether a gate allows traffic.  If this field
	// is unset, this middleware is a nop.
	Gate Status
}

type StateChange int

type Status interface {
	// Name is an optional identifier for this atomic boolean.  No guarantees
	// as to uniqueness are made.  This value is completely up to client configuration.
	//
	// A non-empty name is often useful when an application uses multiple gates.  This
	// name can be used in log files, metrics, etc.
	Name() string

	// IsOpen checks if this instance is open and thus allowing traffic
	IsOpen() bool
}