policy

Documentation

Overview

Package policy defines functions that control which connections are allowed, and which ones are denied. For server-side imposed policies, Allow functions are used to filter connections. For client-side imposed policies, Timeout functions are used to filter connections.

When listening for incoming connections, it is impossible to control the conditions under which the remote client attempts to dial a new connection. As such, more powerful policy functions are required. The opposite is true for the dialer; when dialing a new connection to a remote peer, it can be assumed that the application-level logic will avoid dialing under conditions that the dialer does not find desirable. Here, the Timeout functions are the client-side analogy to the Allow functions. Although the Timeout functions are much less powerful, they are sufficient for dialers.

Policy functions (Allow functions and Timeout functions) are built in using a functional style, and are designed to be composed together. In this way, policy functions are able to define only a small and simple (and easily testable) amounts of filtering logic, but still be composed together to create more complex filtering logic.

// Create a policy that only allows 100 concurrent connections at any one
// point.
maxConns := policy.Max(100)
// Create a policy that only allows 1 connection attempt per second per IP
// address.
rateLimit := policy.RateLimit(1.0, 1, 65535)
// Compose these policies together to require that all of them pass.
all := policy.All(maxConns, rateLimit)
// Or, compose these policies together to require that any of them pass.
any := policy.Any(maxConns, rateLimit)

Timeout functions are similarly composable.

// Create a policy to Timeout after 1 second.
one := policy.ConstantTimeout(time.Second)
// Create a policy to scale this constant timeout by 60% with every attempt.
backoff := policy.LinearBackoff(1.6, one)
// Create a policy to clamp the Timeout to an upper bound of one minute, no
// matter how many attempts there have been.
max := policy.MaxTimeout(time.Minute, backoff)

The policy functions available by default (of course, the programmer is free to implement their own policy functions) are quite simple. But, by providing "higher order policies" such as All, Any, or LinearBackoff, policies can be composed in more interesting ways. In practice, most of the policies that should be implemented at the raw connection level can be created by composing the available policies.

Index

• Variables
• type Allow
  • func All(fs ...Allow) Allow
  • func Any(fs ...Allow) Allow
  • func Max(maxConns int) Allow
  • func RateLimit(r rate.Limit, b, cap int) Allow
• type Cleanup
• type Timeout
  • func ConstantTimeout(duration time.Duration) Timeout
  • func ExponentialBackoff(rate float64, timeout Timeout) Timeout
  • func LinearBackoff(rate float64, timeout Timeout) Timeout
  • func MaxTimeout(duration time.Duration, timeout Timeout) Timeout

Variables

var ErrMaxConnectionsExceeded = errors.New("max connections exceeded")

ErrMaxConnectionsExceeded is returned when a connection is dropped because the maximum number of inbound/outbound connections has been reached.

var ErrRateLimited = errors.New("rate limited")

ErrRateLimited is returned when a connection is dropped because it has exceeded its rate limit for connection attempts.

Types

type Allow

type Allow func(net.Conn) (error, Cleanup)

Allow is a function that filters connections. If an error is returned, the connection is filtered and closed. Otherwise, it is maintained. A clean-up function is also returned. This function is called after the connection is closed, regardless of whether the closure was caused by filtering or normal control-flow.

func All

func All(fs ...Allow) Allow

All returns an Allow function that only passes a connection if all Allow functions in a set pass for that connection. Execution is lazy; when one of the Allow functions returns an error, no more Allow functions will be called.

func Any

func Any(fs ...Allow) Allow

Any returns an Allow function that passes a connection if any Allow functions in a set pass for that connection. Execution is not lazy; even when one of the Allow functions returns a non-nil error, all other Allow functions will be called.

func Max

func Max(maxConns int) Allow

Max returns an Allow function that rejects connections once a maximum number of connections have already been accepted and are being kept-alive. Once an accepted connection is closed, it opens up room for another connection to be accepted.

func RateLimit

func RateLimit(r rate.Limit, b, cap int) Allow

RateLimit returns an Allow function that rejects an IP-address if it attempts too many connections too quickly.

type Cleanup

type Cleanup func()

Cleanup resource allocation, or reverse per-connection state mutations, done by an Allow function.

type Timeout

type Timeout func(int) time.Duration

Timeout functions accept an attempt (from 0 to the maximum integer) and return an expected duration for which the attempt should run.

func ConstantTimeout

func ConstantTimeout(duration time.Duration) Timeout

ConstantTimeout returns a Timeout function that always returns a constant duration.

func ExponentialBackoff

func ExponentialBackoff(rate float64, timeout Timeout) Timeout

ExponentialBackoff returns a Timeout function that scales the duration returned by another Timeout function exponentially with respect to the attempt.

func LinearBackoff

func LinearBackoff(rate float64, timeout Timeout) Timeout

LinearBackoff returns a Timeout function that scales the duration returned by another Timeout function linearly with respect to the attempt.

func MaxTimeout

func MaxTimeout(duration time.Duration, timeout Timeout) Timeout

MaxTimeout returns a Timeout function that restricts another Timeout function to return a maximum duration.