Documentation
¶
Index ¶
- Constants
- func OAuthRetryBackoffDuration(oauthRetryCount int) time.Duration
- func RetryBackoffDuration(retryCount int) time.Duration
- type ConnectionInfo
- type ConnectionState
- type StateManager
- func (sm *StateManager) ClearTerminal()
- 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) IsTerminal() (bool, string)
- 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) SetTerminalError(err error, code string)
- 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.
The interval is deliberately FLAT. Parking is reserved for failures the classifier can PROVE deterministic (ConnectionInfo.Terminal, GH #1145); an escalating probe applied to the rest of the give-up tail would stretch unattended recovery to hours for exactly the failures that heal on their own — a stopped Docker daemon, a dropped VPN, a rate-limited upstream — and nothing in the tree shortens it again until a human looks.
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.
const PermanentFailureAttempts = 2
PermanentFailureAttempts is how many classified-permanent connection failures are required before automatic reconnection stops.
Two, not one: the second attempt is a confirmation. A classifier false positive then costs one wasted retry instead of stranding a server that would have recovered — while still cutting the GH #1145 log from 55 attempts to 2.
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"`
// Terminal marks a failure the diagnostics classifier proved deterministic:
// the same attempt will fail identically until a human edits the config, the
// image, or the machine. Automatic reconnection stops once the confirmation
// budget (PermanentFailureAttempts) is spent — retrying a guaranteed failure
// burns a container spawn, a package install and a log flood per attempt for
// no chance of success (GH #1145: 55 identical attempts over 19 hours).
//
// It is CLEARED by every recovery path — a successful connection, an
// explicit Reset (manual reconnect / disconnect), and client recreation on a
// config change — so a user who fixes the problem always gets the server
// back. See StateManager.SetTerminalError.
Terminal bool `json:"terminal,omitempty"`
// TerminalCode is the stable MCPX_* diagnostics code that proved the failure
// permanent. Carried as a plain string so this package stays a leaf (no
// import of internal/diagnostics). Empty unless Terminal is set.
TerminalCode string `json:"terminal_code,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) ClearTerminal ¶ added in v0.64.0
func (sm *StateManager) ClearTerminal()
ClearTerminal un-parks a terminally failed connection without otherwise touching the retry ladder. It exists for the "the user changed something" paths that keep the existing client instead of recreating it.
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) IsTerminal ¶ added in v0.64.0
func (sm *StateManager) IsTerminal() (bool, string)
IsTerminal reports whether the connection is parked on a classifier-proven permanent failure, and the code that proved it.
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) SetTerminalError ¶ added in v0.64.0
func (sm *StateManager) SetTerminalError(err error, code string)
SetTerminalError records a connection failure that the diagnostics classifier proved deterministic and unrecoverable — a missing binary, an image without the interpreter, an unparseable config. Retrying it cannot succeed until a human changes something, so after PermanentFailureAttempts confirmations both retry gates stop dialing and the server is surfaced as terminally failed.
It is otherwise exactly SetError: the state, error, counter and timestamp all advance identically, so every existing consumer keeps working. `code` is the stable MCPX_* string that justified the park, carried through to the API so the failure is visible with its reason rather than silently swallowed.
Call this ONLY from the connect path, and only for a code that diagnostics.ParkableCode accepts — permanence in the catalog is necessary but not sufficient, because the classifier's string fallbacks read the child process's own stderr. Plain SetError deliberately clears the park.
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