reachability

package
v1.5.4 Latest Latest
Warning

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

 Go to latest Published: Sep 20, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package reachability tracks probe-backed reachability independently from managed-server lifecycle and admission state.

Index

Constants

View Source 
const (
	ProtocolVersion2024_11_05 = "2024-11-05"
	ProtocolVersion2025_03_26 = "2025-03-26"
	ProtocolVersion2025_06_18 = "2025-06-18"
	ProtocolVersion2025_11_25 = "2025-11-25"

	DefaultProbeInterval = 30 * time.Second
	// EndToEndProbeIntervalMultiple keeps the admission-consuming probe rare
	// relative to the free listener probe.
	EndToEndProbeIntervalMultiple = 10
)
View Source 
const (
	// FailureThreshold prevents transient failures from reporting a server as
	// unreachable. This is the daemon-wide established probe convention.
	FailureThreshold = 3
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Depth 

type Depth string

Depth identifies how far a probe got before producing evidence. 

const (
	DepthListener Depth = "listener"
	DepthSession  Depth = "session"
	DepthEndToEnd Depth = "end_to_end"
)

func (Depth) Rank 

func (d Depth) Rank() int

Rank orders probe depths from shallowest to deepest for evidence selection.

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager owns one cancellable probe worker per server.

func NewManager 

func NewManager(store *Store, selector *VersionSelector, logger ...*slog.Logger) *Manager

func (*Manager) Close 

func (m *Manager) Close()

Close cancels and joins every worker. It is safe to call repeatedly.

func (*Manager) Remove 

func (m *Manager) Remove(name string) error

Remove stops the worker before deleting evidence, ensuring an in-flight result cannot be written after the server has left the registry.

func (*Manager) Start 

func (m *Manager) Start(parent context.Context, target Target, interval time.Duration) error

func (*Manager) StartWithProbe 

func (m *Manager) StartWithProbe(parent context.Context, target Target, interval time.Duration, probe Probe) error

func (*Manager) Stop 

func (m *Manager) Stop(name string) error

func (*Manager) Wait 

func (m *Manager) Wait()

Wait joins currently registered workers. Parent context cancellation causes workers to unregister, so this is useful during daemon shutdown as well.

type Outcome 

type Outcome string

Outcome is the result of a completed probe. 

const (
	OutcomeSuccess Outcome = "success"
	OutcomeFailure Outcome = "failure"
)

type Probe 

type Probe interface {
	Probe(context.Context, Target) (bool, error)
}

Probe is the version-independent seam for reachability mechanisms. Implementations return false with an error when the target is not reachable.

type ProbeEvidence 

type ProbeEvidence struct {
	Depth               Depth     `json:"depth"`
	LastProbeAttempt    time.Time `json:"last_probe_attempt"`
	LastProbeOutcome    Outcome   `json:"last_probe_outcome"`
	LastProbeError      string    `json:"last_probe_error,omitempty"`
	ConsecutiveFailures int       `json:"consecutive_failures"`
}

ProbeEvidence is the latest result and failure streak for one probe depth. LastProbeError is deliberately a bounded, single-line string so it can be rendered directly by administrative surfaces without exposing an error object or control characters.

type ProbeResult 

type ProbeResult struct {
	Depth       Depth
	AttemptedAt time.Time
	Success     bool
	Error       string
}

ProbeResult records one completed probe. A zero AttemptedAt is replaced by the store's current time. Error is ignored for successful probes.

type Reachability 

type Reachability struct {
	State    State                   `json:"state"`
	Evidence map[Depth]ProbeEvidence `json:"evidence,omitempty"`
}

Reachability is a point-in-time value returned by Store. Evidence is kept per depth so a shallow result cannot erase a deeper result. Callers receive an independent copy of the evidence map.

type State 

type State string

State is the current reachability state of a server. 

const (
	StateUnprobed    State = "unprobed"
	StateProbing     State = "probing"
	StateReachable   State = "reachable"
	StateUnreachable State = "unreachable"
)

type Store 

type Store struct {
	// contains filtered or unexported fields
}

Store is a concurrency-safe, in-memory reachability store keyed by server name. It has no admission or lifecycle behavior.

func NewStore 

func NewStore() *Store

NewStore creates an empty reachability store.

func (*Store) Get 

func (s *Store) Get(serverName string) (Reachability, bool)

Get returns the current reachability for serverName. An unseen server returns an unprobed value and false.

func (*Store) RecordDefinitiveFailure 

func (s *Store) RecordDefinitiveFailure(serverName string, depth Depth, attemptedAt time.Time, cause string) Reachability

RecordDefinitiveFailure records a failure that is known to be terminal rather than transient, marking the depth unreachable immediately without waiting for FailureThreshold consecutive failures.

FailureThreshold exists to stop a flaky probe from reporting a healthy server as broken. That reasoning does not apply to a failure whose cause is already proven, such as a proxy listener that failed to register: there is no listener to become reachable again, so requiring two further confirmations would report a known-broken server as healthy for the duration.

Callers must use this only when the failure is structurally terminal. A probe that merely failed to connect is transient and belongs in RecordProbe.

func (*Store) RecordProbe 

func (s *Store) RecordProbe(serverName string, result ProbeResult) Reachability

RecordProbe records a completed probe and returns the resulting value. Failures become unreachable only after FailureThreshold consecutive failures at the same depth. A success resets that depth's failure streak.

func (*Store) Remove 

func (s *Store) Remove(serverName string)

Remove deletes all reachability evidence for serverName.

func (*Store) StartProbe 

func (s *Store) StartProbe(serverName string, depth Depth, attemptedAt time.Time) Reachability

StartProbe marks a server as probing at depth and records the attempt time. It is safe for multiple probe workers to start concurrently.

type Target 

type Target struct {
	Name            string
	Port            int
	ProtocolVersion string
	BearerToken     string
}

Target identifies the local Vision listener to probe. ProtocolVersion is the negotiated MCP revision; keeping it on the target makes the mechanism selection explicit when a later revision needs a different probe.

type VersionSelector 

type VersionSelector struct {
	// contains filtered or unexported fields
}

VersionSelector maps negotiated MCP revisions to probe mechanisms. It is intentionally explicit: protocol revisions that remove initialize/sessions must not silently inherit a mechanism designed for an older revision.

func NewVersionSelector 

func NewVersionSelector(listener Probe, endToEnd ...Probe) *VersionSelector

func (*VersionSelector) Select 

func (s *VersionSelector) Select(protocolVersion string) (Probe, error)

Select returns the mechanism for a negotiated revision. An empty revision uses the latest revision supported by the current SDK, which is the only safe default before a server has completed negotiation.

func (*VersionSelector) SelectEndToEnd 

func (s *VersionSelector) SelectEndToEnd(protocolVersion string) (Probe, error)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.