types

package
v0.63.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 30, 2026 License: MIT Imports: 3 Imported by: 0

Documentation

Index

Constants

View Source
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.

View Source
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

func OAuthRetryBackoffDuration(oauthRetryCount int) time.Duration

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

func RetryBackoffDuration(retryCount int) time.Duration

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL