Documentation
¶
Overview ¶
Package connection establishes and maintains the agent's transport to an admin server. It is responsible for endpoint resolution, dial-time failover across the configured endpoint list, and exponential backoff when every endpoint is unreachable.
The package does NOT own the bidi stream itself; that lives in admin/agent/stream. connection.Dialer.Dial returns a connected AgentService client and the endpoint URL that succeeded; the stream layer owns the call.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Config ¶
type Config struct {
// Endpoints is the ordered list of admin server URLs to try. Each
// entry is a full URL — http://, https://, or h2c:// for unencrypted
// HTTP/2. The dialer tries them in order on each attempt.
Endpoints []string
// Token, if non-empty, is sent on every Connect-RPC call as
// "Authorization: Bearer <Token>". Used for the simplest auth mode
// (decision 13: shared bearer token).
Token string
// TLSConfig is applied to every https:// endpoint (both the /healthz
// probe and the Connect stream). Pass nil to use the system trust
// store; set RootCAs for a private CA, or Certificates to present a
// client certificate to a mutual-TLS agent listener.
TLSConfig *tls.Config
// HealthCheckTimeout caps each endpoint probe (an HTTP GET to /healthz
// on the same origin). Default 3s.
HealthCheckTimeout time.Duration
// InitialBackoff is the first sleep after a complete failover round
// fails. Default 1s.
InitialBackoff time.Duration
// MaxBackoff caps the exponential growth. Default 30s (decision 9).
MaxBackoff time.Duration
// BackoffJitter is multiplied by rand[0,1) and added to each backoff
// to avoid thundering-herd. Default 0.5.
BackoffJitter float64
// Logger is used for the rate-limited disconnect WARN. Pass nil for
// slog.Default.
Logger *slog.Logger
}
Config controls how the dialer probes endpoints and times out.
type Dialer ¶
type Dialer struct {
// contains filtered or unexported fields
}
Dialer attempts to establish a connection to one of the configured endpoints. It is safe to construct once and call Dial repeatedly.
func (*Dialer) Backoff ¶
Backoff returns the duration the caller should wait before the next Dial. Grows exponentially up to MaxBackoff with jitter; resets to InitialBackoff only when the caller invokes ResetBackoff (i.e. after the admin server has actually accepted the stream, not merely after a successful /healthz probe).
Backoff advances internal state, so call it exactly once per failed connect → stream cycle.
func (*Dialer) Dial ¶
Dial tries each endpoint in order, advancing past the ones that fail the health probe. Returns the first one that completes successfully. When every endpoint fails, Dial returns the last error and the caller should sleep on Backoff() before retrying.
Dial respects ctx cancellation and returns ctx.Err() promptly.
func (*Dialer) ResetBackoff ¶
func (d *Dialer) ResetBackoff()
ResetBackoff returns the backoff schedule to InitialBackoff. Call it only on evidence that the server accepted the connection — in practice, when the stream layer receives its first frame from the server. A Dial success must NOT reset: the /healthz probe is exempt from auth, so it succeeds even when the token is being rejected.
type Result ¶
type Result struct {
Client adminv1connect.AgentServiceClient
Endpoint string
}
Result describes a successful Dial.
Source Files