proxy

Documentation

Index

• Constants
• Variables
• func GetPrivateIP() net.IP
• func ResolveAddr(addr string) (string, error)
• func WaitForPrivateNetwork() bool
• type Agent
  • func NewAgent(proxy Proxy, retry Retry) Agent
• type Proxy
• type Retry

Constants

const (
	// MaxAborts is the maximum number of cascading abort messages to buffer.
	// This should be the upper bound on the number of proxies available at any point in time.
	MaxAborts = 10
)

Variables

var (

	// DefaultRetry configuration for proxies
	DefaultRetry = Retry{
		MaxRetries:      10,
		InitialInterval: 200 * time.Millisecond,
	}
)

var ErrResolveNoAddress = errors.New("no address specified")

ErrResolveNoAddress error occurs when IP address resolution is attempted, but no address was provided.

Functions

func GetPrivateIP

func GetPrivateIP() net.IP

GetPrivateIP returns a private IP address, or panics if no IP is available.

func ResolveAddr

func ResolveAddr(addr string) (string, error)

ResolveAddr resolves an authority address to an IP address. Incoming addr can be an IP address or hostname. If addr is an IPv6 address, the IP part must be enclosed in square brackets.

TODO: LookupIPAddr() may return multiple IP addresses, of which this function returns the first entry. We're assuming that IPv4 addresses will be listed first, meaning it has priority over IPv6. If this does not hold, then additional logic will be needed to enforce an IP mode priority.

To use this function in an IPv6 only environment, either provide an IPv6 address or ensure the hostname resolves to only IPv6 addresses.

func WaitForPrivateNetwork

func WaitForPrivateNetwork() bool

WaitForPrivateNetwork blocks until a private IP address is available, or a timeout is reached. Returns 'true' if a private IP is available before timeout is reached, and 'false' otherwise.

Types

type Agent

type Agent interface {
	// ScheduleConfigUpdate sets the desired configuration for the proxy.  Agent
	// compares the current active configuration to the desired state and
	// initiates a restart if necessary. If the restart fails, the agent attempts
	// to retry with an exponential back-off.
	ScheduleConfigUpdate(config interface{})

	// Run starts the agent control loop and awaits for a signal on the input
	// channel to exit the loop.
	Run(ctx context.Context)
}

Agent manages the restarts and the life cycle of a proxy binary. Agent keeps track of all running proxy epochs and their configurations. Hot restarts are performed by launching a new proxy process with a strictly incremented restart epoch. It is up to the proxy to ensure that older epochs gracefully shutdown and carry over all the necessary state to the latest epoch. The agent does not terminate older epochs. The initial epoch is 0.

The restart protocol matches Envoy semantics for restart epochs: to successfully launch a new Envoy process that will replace the running Envoy processes, the restart epoch of the new process must be exactly 1 greater than the highest restart epoch of the currently running Envoy processes. See https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/hot_restart.html for more information about the Envoy hot restart protocol.

Agent requires two functions "run" and "cleanup". Run function is a call to start the proxy and must block until the proxy exits. Cleanup function is executed immediately after the proxy exits and must be non-blocking since it is executed synchronously in the main agent control loop. Both functions take the proxy epoch as an argument. A typical scenario would involve epoch 0 followed by a failed epoch 1 start. The agent then attempts to start epoch 1 again.

Whenever the run function returns an error, the agent assumes that the proxy failed to start and attempts to restart the proxy several times with an exponential back-off. The subsequent restart attempts may reuse the epoch from the failed attempt. Retry budgets are allocated whenever the desired configuration changes.

Agent executes a single control loop that receives notifications about scheduled configuration updates, exits from older proxy epochs, and retry attempt timers. The call to schedule a configuration update will block until the control loop is ready to accept and process the configuration update.

func NewAgent

func NewAgent(proxy Proxy, retry Retry) Agent

NewAgent creates a new proxy agent for the proxy start-up and clean-up functions.

type Proxy

type Proxy interface {
	// Run command for a config, epoch, and abort channel
	Run(interface{}, int, <-chan error) error

	// Cleanup command for an epoch
	Cleanup(int)

	// Panic command is invoked with the desired config when all retries to
	// start the proxy fail just before the agent terminating
	Panic(interface{})
}

Proxy defines command interface for a proxy

type Retry

type Retry struct {

	// MaxRetries is the maximum number of retries
	MaxRetries int

	// InitialInterval is the delay between the first restart, from then on it is
	// multiplied by a factor of 2 for each subsequent retry
	InitialInterval time.Duration
	// contains filtered or unexported fields
}

Retry configuration for the proxy