connstate

package
v1.159.0 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package connstate holds each connection's state as the calls that used it last found it: healthy, unreachable, or auth_failed (#1898). It is fed by the places that see an upstream's answer -- the outbound HTTP chain for the api, graphql and mcp kinds, the Trino and S3 toolkits' telemetry -- and read when mcp_platform_connections is sampled. Nothing here sends a request: a connection nobody has called has no state, and is reported as configured.

The state is per process. Each replica reports the connections it has called, so the gauge is read with max by (kind, state) across replicas.

A recorded state stands for the maximum age (server.connection_state_max_age, DefaultMaxAge) and then reads as configured again, and every move into or out of a failure is logged naming the connection (#2442).

Index

Constants

View Source
const (
	Healthy     = "healthy"
	Unreachable = "unreachable"
	AuthFailed  = "auth_failed"
)

The states a call can leave a connection in.

View Source
const (
	ReasonAnswered          = "answered"
	ReasonCredentialRefused = "credential_refused" // #nosec G101 -- a reason word a log record carries, not a credential
	ReasonNetworkError      = "network_error"
	ReasonTimeout           = "timeout"
	ReasonTransportError    = "transport_error"
)

The reasons a state is recorded with. A reason is chosen from this list by this package, so a log record or label carrying one carries nothing an upstream wrote.

View Source
const DefaultMaxAge = 15 * time.Minute

DefaultMaxAge is how long a recorded state stands with no call to confirm it (#2442). A connection that failed once and was not called again used to report the failure until the process restarted.

Variables

This section is empty.

Functions

func Forget added in v1.153.0

func Forget(kind, connection string)

Forget drops what calls found kind's connection in (#2444): the connection was deleted, or its configuration changed, so the next call on the connection now under that name says what it is. A connection re-created under a deleted one's name, or saved with a new credential, otherwise read as the old one's last state until a call used it.

func FromHTTP

func FromHTTP(status int, err error) string

FromHTTP is the state an HTTP answer leaves a connection in: 401 and 407 are a refused credential; a transport error, a timeout, or a 502, 503 or 504 is an upstream that could not be reached or could not answer; any other status is an upstream that answered, which is healthy whatever it said about the request itself. A caller that canceled the request says nothing about the upstream, and records nothing.

func FromResultText

func FromResultText(text string, credential ...string) string

FromResultText is the state a failed tool result leaves a connection in when the result is all a caller has: its text names a refused credential (one of credential, the client's own stable error texts or codes), a lost network (Go's net error texts), or an upstream that answered and refused the request, which is healthy.

func HTTPReason added in v1.153.2

func HTTPReason(status int, err error) string

HTTPReason is the reason an HTTP answer gives: http_401, http_407, http_502, http_503 and http_504 for the statuses FromHTTP reads as a failure, the status class (http_2xx, http_4xx, ...) for any other, timeout for an error that is one, and transport_error for any other error. Only the error's type is read, never its text.

func Observe

func Observe(kind, connection, s string)

Observe records the state a call found kind's connection in, with the reason its state alone gives. A call with no connection name (a platform-wide client) and a state that is not one of Healthy, Unreachable and AuthFailed -- "" for an outcome that says nothing about the upstream -- are ignored, so the gauge's state label stays the set this package defines.

func ObserveHTTP added in v1.153.2

func ObserveHTTP(kind, connection string, status int, err error)

ObserveHTTP records the state an HTTP answer or transport error leaves kind's connection in (FromHTTP), with the reason HTTPReason reads from it.

func ObserveStatus added in v1.153.2

func ObserveStatus(kind, connection, s string, status int)

ObserveStatus records s, a state the caller read from an HTTP status by its own rule, with the reason HTTPReason reads from that status.

func SetMaxAge added in v1.153.2

func SetMaxAge(d time.Duration)

SetMaxAge sets how long a recorded state stands with no call to confirm it; zero or less is DefaultMaxAge. Set once at startup from server.connection_state_max_age.

func State

func State(kind, connection string) (string, bool)

State returns the state the last call found kind's connection in, and false when no call has used it in this process or the last one is older than the maximum age.

Types

type Observation added in v1.153.2

type Observation struct {
	State  string
	Reason string
	At     time.Time
}

Observation is a connection's current record.

func Observed added in v1.153.2

func Observed(kind, connection string) (Observation, bool)

Observed returns kind's connection's current record, and false when it has none: no call used it in this process, or the last one aged out.

Jump to

Keyboard shortcuts

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