Documentation
¶
Overview ¶
Package track provides a simple interface to keep track of proxies as described via "gossip" messages shared by other proxies as part of the reverse tunnel protocol, and to decide if and when it's appropriate to attempt a new connection to a proxy load balancer at any given moment.
The Tracker object gives out Lease objects through its TryAcquire() function whenever it's appropriate to attempt a new connection - the Lease object represents the permission to open a new connection and to try and Claim exclusivity over the remote proxy that was reached.
A Lease starts "unclaimed", and can be switched into a "claimed" state given a proxy name; if no other Lease has claimed the same proxy, the claim is successful; otherwise, the Lease should be released with Release() so that a new connection can be spawned in its stead. The Lease should also be released if the connection fails, or after it's closed.
The Tracker keeps track of how many Leases are in unclaimed state, and of which proxies have been claimed. In addition, it receives gossip messages (usually from the reverse tunnel clients themselves, through the reverse tunnel "gossip" protocol, see `handleDiscovery` in lib/reversetunnel/agent.go) containing information about proxies in the cluster - namely, which proxies exist, and which group ID and generation, if any, they belong to.
A proxy can report a group ID and a group generation (it's valid for a proxy to belong to the "" group or the zero generation); the group ID represents independent deployments of proxies, the group generation is a monotonically increasing counter scoped to each group.
The Tracker will grant Leases (to attempt to connect to new proxies) based on which proxies have been claimed, how many Leases have been granted but have yet to claim a proxy (they're still "inflight") and which proxies are known and which group ID and generation they have reported:
- the set of desired proxies is defined to be the union of all proxies in the biggest known generation of each proxy group; if proxies A, B and C belong to the same group but proxy A is in generation 2 while B and C are in generation 1, only proxy A is in the desired set
- if in proxy peering mode, the count of desired proxies is limited by the connection count, such that if the connection count is 40 but only 3 proxies are in the desired set, the effective count is going to be 3 - however, if the connection count is 3 and there's 40 proxies in the desired set, the effective count is also going to be 3
- the desired proxy count is compared with the sum of the count of currently claimed proxies in the desired set and the current amount of inflight connections (Lease objects that haven't been released and haven't claimed a proxy); new connections can be spawned if the desired proxy count is strictly greater.
Proxies are removed from the tracked set after a TTL (defaulting to 3 minutes), which is refreshed whenever they're mentioned in a gossip message.
Index ¶
Constants ¶
const ( // DefaultProxyExpiry is the default amount of time a tracker will attempt // to successfully connect to a proxy before giving up DefaultProxyExpiry = 3 * time.Minute )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// ProxyExpiry is the duration an entry will be held since the last
// successful connection to, or message about, a given proxy.
ProxyExpiry time.Duration
// ClusterName is the name of the tracked cluster.
ClusterName string
}
Config configures basic Tracker parameters.
func (*Config) CheckAndSetDefaults ¶
CheckAndSetDefaults set default values for Config.
type Lease ¶
type Lease struct {
// contains filtered or unexported fields
}
Lease represents an authorization to attempt to connect to a reverse tunnel server, and to attempt to exclusively claim a specific server. It should be explicitly released after use.
func (*Lease) Claim ¶
Claim attempts to claim exclusive access to a reverse tunnel server identified by the principals. It will fail if the server is already claimed or if the Lease had already been released or has already claimed a different server.
func (*Lease) ID ¶
ID returns a numerical ID associated with the Lease, for debugging purposes; IDs are consecutively assigned starting from 1 for each given Tracker.
func (*Lease) IsReleased ¶
IsReleased returns true if Release has been called. Used by tests.
type Proxy ¶
type Proxy struct {
Name string
Group string
Generation uint64
// contains filtered or unexported fields
}
Proxy holds the name and relevant metadata for a reverse tunnel server, as well as some internal bookkeeping data used by the Tracker.
type Tracker ¶
type Tracker struct {
// contains filtered or unexported fields
}
Tracker represents the view that a reverse tunnel client (i.e. an agentpool) has over the reverse tunnel servers (i.e. proxies) that it's connected to and that it knows about. Based on that information, the Tracker is in charge of deciding if new connection attempts should be made, by giving out [Lease]s.
func (*Tracker) IsClaimed ¶
IsClaimed returns true if the reverse tunnel server identified by the principals has already been claimed at the time of the call. Keep in mind that a false return value does not imply that a subsequent call to Claim on a Lease with the same principals is guaranteed to succeed, as other goroutines might also be attempting to claim the same server.
func (*Tracker) SetConnectionCount ¶
SetConnectionCount updates the desired connection count as defined by the tunnel_strategy; 0 means full connectivity, i.e. "agent mesh" mode, a nonzero value (the connection_count of the tunnel_strategy) is proxy peering mode.
func (*Tracker) TrackExpected ¶
TrackExpected starts/refreshes tracking for expected proxies. Called by agents when gossip messages are received.
func (*Tracker) TryAcquire ¶
TryAcquire attempts to acquire a Lease from the tracker; if we shouldn't attempt a new connection at the moment, it will return nil, otherwise it will return a new Lease in the unclaimed state that can attempt to claim exclusivity over a proxy and that must be released (with [Lease.Release()]) at the end of its lifetime.
Source Files