Documentation
¶
Index ¶
- Constants
- func OAuthRetryBackoffDuration(oauthRetryCount int) time.Duration
- func RetryBackoffDuration(retryCount int) time.Duration
- type ConnectionInfo
- type ConnectionState
- type StateManager
- func (sm *StateManager) GetConnectionInfo() ConnectionInfo
- func (sm *StateManager) GetState() ConnectionState
- func (sm *StateManager) GetStateChangeCallback() func(oldState, newState ConnectionState, info *ConnectionInfo)
- func (sm *StateManager) IsConnecting() bool
- func (sm *StateManager) IsOAuthError() bool
- func (sm *StateManager) IsReady() bool
- func (sm *StateManager) IsState(state ConnectionState) bool
- func (sm *StateManager) IsUserLoggedOut() bool
- func (sm *StateManager) Reset()
- func (sm *StateManager) ResetForReconnect()
- func (sm *StateManager) RetryAfter() time.Time
- func (sm *StateManager) SetError(err error)
- func (sm *StateManager) SetOAuthError(err error)
- func (sm *StateManager) SetPendingAuth(err error)
- func (sm *StateManager) SetRetryAfter(deadline time.Time)
- func (sm *StateManager) SetServerInfo(name, version string)
- func (sm *StateManager) SetStateChangeCallback(callback func(oldState, newState ConnectionState, info *ConnectionInfo))
- func (sm *StateManager) SetUserLoggedOut(loggedOut bool)
- func (sm *StateManager) ShouldRetry() bool
- func (sm *StateManager) ShouldRetryOAuth() bool
- func (sm *StateManager) TransitionTo(newState ConnectionState)
- func (sm *StateManager) ValidateTransition(from, to ConnectionState) error
Constants ¶
const GaveUpProbeInterval = 30 * time.Minute
GaveUpProbeInterval is how often a given-up server is still probed by the periodic reconciliation. After MaxConnectionRetries consecutive failures the client stops its own retry ladder, but "never again" would leave an upstream silently dead after any outage longer than the ladder (laptop sleep, VPN drop, overnight maintenance) until a human notices and reconnects by hand — a failed upstream is invisible to the operator (#1013). One probe every 30 minutes keeps that self-healing at ~48 requests/day instead of ~2880.
const MaxConnectionRetries = 20
ConnectionInfo holds information about the current connection state MaxConnectionRetries is the maximum number of consecutive connection failures before giving up automatic reconnection. The server can still be reconnected manually or via reconnect-on-use.
Variables ¶
This section is empty.
Functions ¶
func OAuthRetryBackoffDuration ¶ added in v0.61.0
OAuthRetryBackoffDuration returns the (much longer) backoff to wait after the given number of consecutive OAuth failures: 5min, 15min, 1h, 4h, then 24h. An OAuth failure cannot be resolved by redialing quickly — it needs a token refresh or a human completing a login — so its ladder is deliberately coarse.
func RetryBackoffDuration ¶ added in v0.61.0
RetryBackoffDuration returns the exponential backoff to wait after the given number of consecutive connection failures: 1s, 2s, 4s, ... capped at 5 minutes.
Types ¶
type ConnectionInfo ¶
type ConnectionInfo struct {
State ConnectionState `json:"state"`
LastError error `json:"last_error,omitempty"`
RetryCount int `json:"retry_count"`
LastRetryTime time.Time `json:"last_retry_time,omitempty"`
ServerName string `json:"server_name,omitempty"`
ServerVersion string `json:"server_version,omitempty"`
LastOAuthAttempt time.Time `json:"last_oauth_attempt,omitempty"`
OAuthRetryCount int `json:"oauth_retry_count"`
IsOAuthError bool `json:"is_oauth_error"`
GaveUp bool `json:"gave_up"` // True when max retries exceeded
// RetryAfter is the instant before which the upstream asked us not to come
// back, captured from a `Retry-After` header on a rate-limited response
// (#1040). Zero when the upstream gave no hint. It acts as a floor under the
// retry ladder — the effective delay is max(backoff, Retry-After).
RetryAfter time.Time `json:"retry_after,omitempty"`
}
func (*ConnectionInfo) ShouldAutoReconnect ¶ added in v0.61.0
func (ci *ConnectionInfo) ShouldAutoReconnect(now time.Time) bool
ShouldAutoReconnect reports whether an automatic (supervisor-driven) reconnect attempt is appropriate given the connection's failure history. It returns false while a backoff window from the last failure has not elapsed and for servers parked in PendingAuth — redialing cannot succeed until the user completes the OAuth login, and each attempt costs real requests against the upstream. Manual reconnects, login flows, and reconnect-on-use are not subject to this policy.
type ConnectionState ¶
type ConnectionState int
ConnectionState represents the state of an upstream connection
const ( // StateDisconnected indicates the upstream is not connected StateDisconnected ConnectionState = iota // StateConnecting indicates the upstream is attempting to connect StateConnecting // StatePendingAuth indicates the upstream requires OAuth authentication but is deferred (e.g., waiting for user action) StatePendingAuth // StateAuthenticating indicates the upstream is performing OAuth authentication StateAuthenticating // StateDiscovering indicates the upstream is discovering available tools StateDiscovering // StateReady indicates the upstream is connected and ready for requests StateReady // StateError indicates the upstream encountered an error StateError )
func (ConnectionState) String ¶
func (s ConnectionState) String() string
String returns the string representation of the connection state
type StateManager ¶
type StateManager struct {
// contains filtered or unexported fields
}
StateManager manages the state transitions for an upstream connection
func NewStateManager ¶
func NewStateManager() *StateManager
NewStateManager creates a new state manager
func (*StateManager) GetConnectionInfo ¶
func (sm *StateManager) GetConnectionInfo() ConnectionInfo
GetConnectionInfo returns detailed connection information
func (*StateManager) GetState ¶
func (sm *StateManager) GetState() ConnectionState
GetState returns the current connection state
func (*StateManager) GetStateChangeCallback ¶
func (sm *StateManager) GetStateChangeCallback() func(oldState, newState ConnectionState, info *ConnectionInfo)
GetStateChangeCallback returns the current state change callback
func (*StateManager) IsConnecting ¶
func (sm *StateManager) IsConnecting() bool
IsConnecting returns true if the connection is in progress
func (*StateManager) IsOAuthError ¶
func (sm *StateManager) IsOAuthError() bool
IsOAuthError returns true if the last error was OAuth-related
func (*StateManager) IsReady ¶
func (sm *StateManager) IsReady() bool
IsReady returns true if the connection is ready for requests
func (*StateManager) IsState ¶
func (sm *StateManager) IsState(state ConnectionState) bool
IsState checks if the current state matches the given state
func (*StateManager) IsUserLoggedOut ¶
func (sm *StateManager) IsUserLoggedOut() bool
IsUserLoggedOut returns true if the user has explicitly logged out
func (*StateManager) Reset ¶
func (sm *StateManager) Reset()
Reset resets the state manager to disconnected state
func (*StateManager) ResetForReconnect ¶ added in v0.24.0
func (sm *StateManager) ResetForReconnect()
ResetForReconnect transitions to Disconnected state for a reconnection attempt while PRESERVING retryCount and lastRetryTime so exponential backoff is not defeated. Use this instead of Reset() when retrying a failed connection.
func (*StateManager) RetryAfter ¶ added in v0.61.0
func (sm *StateManager) RetryAfter() time.Time
RetryAfter returns the current park deadline, or the zero time when the upstream has given no rate-limit hint.
func (*StateManager) SetError ¶
func (sm *StateManager) SetError(err error)
SetError sets an error and transitions to error state
func (*StateManager) SetOAuthError ¶
func (sm *StateManager) SetOAuthError(err error)
SetOAuthError sets an OAuth-specific error with longer backoff periods
func (*StateManager) SetPendingAuth ¶ added in v0.61.0
func (sm *StateManager) SetPendingAuth(err error)
SetPendingAuth parks the connection in StatePendingAuth with the deferred-OAuth error attached. It exists because the obvious spelling — TransitionTo(StatePendingAuth) followed by SetError(err) — silently undoes itself: SetError forces StateError unconditionally, so the PendingAuth state survived microseconds and every consumer (health, notifications, the supervisor's reconnect gate) saw a plain error and kept redialing a server that cannot connect until a human logs in (#1013).
RetryCount is deliberately NOT bumped: a parked server is not retrying, so there is no ladder to advance and nothing to "give up" on. The wake paths are explicit user action (login, manual reconnect, reconnect-on-use) and the persisted-token scan in Manager.scanForNewTokens.
func (*StateManager) SetRetryAfter ¶ added in v0.61.0
func (sm *StateManager) SetRetryAfter(deadline time.Time)
SetRetryAfter records an upstream-supplied park deadline captured from a `Retry-After` header on a rate-limited (429 / 503) response (#1040).
It only ever EXTENDS the window: a later, shorter hint must not shorten a wait the upstream already asked for, and an already-elapsed deadline is dropped rather than stored. Call it BEFORE SetError/SetOAuthError so the resulting ConnectionInfo the state-change callback publishes already carries the window.
func (*StateManager) SetServerInfo ¶
func (sm *StateManager) SetServerInfo(name, version string)
SetServerInfo sets the server information
func (*StateManager) SetStateChangeCallback ¶
func (sm *StateManager) SetStateChangeCallback(callback func(oldState, newState ConnectionState, info *ConnectionInfo))
SetStateChangeCallback sets a callback function that will be called on state changes
func (*StateManager) SetUserLoggedOut ¶
func (sm *StateManager) SetUserLoggedOut(loggedOut bool)
SetUserLoggedOut marks that the user has explicitly logged out This prevents automatic reconnection until cleared (e.g., by explicit login)
func (*StateManager) ShouldRetry ¶
func (sm *StateManager) ShouldRetry() bool
ShouldRetry returns true if the connection should be retried based on exponential backoff
func (*StateManager) ShouldRetryOAuth ¶
func (sm *StateManager) ShouldRetryOAuth() bool
ShouldRetryOAuth returns true if OAuth should be retried with much longer backoff intervals
func (*StateManager) TransitionTo ¶
func (sm *StateManager) TransitionTo(newState ConnectionState)
TransitionTo transitions to a new state
func (*StateManager) ValidateTransition ¶
func (sm *StateManager) ValidateTransition(from, to ConnectionState) error
ValidateTransition validates if a state transition is allowed