connectivity

package
v0.0.21 Latest Latest
Warning

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

Go to latest
Published: Sep 12, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Index

Constants

View Source
const (
	ControlReasonHeartbeatMissing    = "heartbeat_missing"
	ControlReasonHeartbeatStale      = "heartbeat_stale"
	ControlReasonHeartbeatRecovering = "heartbeat_recovering"
)
View Source
const (
	ErrorCodeConnectionGenerationChanged = "connection_generation_changed"

	DenialAgentDisabled           = "agent_disabled"
	DenialControlDisconnected     = "control_disconnected"
	DenialRelayUnsupported        = "relay_unsupported"
	DenialRelayNotConfigured      = "relay_not_configured"
	DenialRelayDisabled           = "relay_disabled"
	DenialRelaySessionUnavailable = "relay_session_unavailable"
)

Variables

View Source
var ErrConnectionGenerationChanged = errors.New(ErrorCodeConnectionGenerationChanged)

Functions

func CanonicalProbeFingerprint

func CanonicalProbeFingerprint(sourceID string, sourceGeneration uint64, target ProbeTarget) string

func CanonicalRelayProbeFingerprint

func CanonicalRelayProbeFingerprint(
	sourceID string,
	sourceControlGeneration uint64,
	sourceRelayGeneration uint64,
	targetID string,
	targetControlGeneration uint64,
	targetRelayGeneration uint64,
) string

Types

type AgentRuntimeFact

type AgentRuntimeFact struct {
	Uptime               int64                                `json:"uptime"`
	CachedTokens         int                                  `json:"cached_tokens"`
	CachedChannels       int                                  `json:"cached_channels"`
	CachedModels         int                                  `json:"cached_models"`
	CachedGlobalRoutings int                                  `json:"cached_global_routings"`
	CachedUserRoutings   int                                  `json:"cached_user_routings"`
	ActiveConnections    int                                  `json:"active_connections"`
	Version              int64                                `json:"version"`
	MasterVersion        int64                                `json:"master_version"`
	PendingUsage         int                                  `json:"pending_usage"`
	CacheStats           map[string]protocol.CacheEntityStats `json:"cache_stats,omitempty"`
	Relay                *RelayRuntimeFact                    `json:"relay,omitempty"`
}

type AgentTransportPolicyFinder added in v0.0.14

type AgentTransportPolicyFinder interface {
	FindAgentTransportPolicies(context.Context, []string) (map[string]models.Agent, error)
}

type AgentTransportPolicySnapshot added in v0.0.14

type AgentTransportPolicySnapshot struct {
	DirectInbound  TransportDirectionSnapshot `json:"direct_inbound"`
	DirectOutbound TransportDirectionSnapshot `json:"direct_outbound"`
	RelayInbound   TransportDirectionSnapshot `json:"relay_inbound"`
	RelayOutbound  TransportDirectionSnapshot `json:"relay_outbound"`
}

type ConnectionSnapshot

type ConnectionSnapshot struct {
	Version           string                       `json:"version"`
	SnapshotEpoch     string                       `json:"snapshot_epoch"`
	SnapshotSeq       uint64                       `json:"snapshot_seq"`
	ObservedAt        int64                        `json:"observed_at"`
	AgentID           string                       `json:"agent_id"`
	AdminStatus       int                          `json:"admin_status"`
	TransportPolicy   AgentTransportPolicySnapshot `json:"transport_policy"`
	Control           ControlSnapshot              `json:"control"`
	Relay             RelaySnapshot                `json:"relay"`
	Direct            DirectSnapshot               `json:"direct"`
	RelayPaths        RelayPathSnapshot            `json:"-"`
	TargetSummaries   RouteTargetSummaries         `json:"target_summaries"`
	RouteTargets      RouteTargetsSnapshot         `json:"-"`
	AllowedOperations []OperationStatus            `json:"allowed_operations"`
}

type ConnectionSummary

type ConnectionSummary struct {
	Version         string                       `json:"version"`
	SnapshotEpoch   string                       `json:"snapshot_epoch"`
	SnapshotSeq     uint64                       `json:"snapshot_seq"`
	ObservedAt      int64                        `json:"observed_at"`
	TransportPolicy AgentTransportPolicySnapshot `json:"transport_policy"`
	Control         ControlSnapshot              `json:"control"`
	Relay           RelaySummary                 `json:"relay"`
	Direct          DirectSummary                `json:"direct"`
	Targets         RouteTargetSummaries         `json:"targets"`
}

type ControlSessionFact

type ControlSessionFact struct {
	Generation        uint64
	ConnectedAt       int64
	HeartbeatAt       int64
	RuntimeReportedAt int64
	Runtime           *AgentRuntimeFact
	RecentErrors      []RecentError
}

type ControlSnapshot

type ControlSnapshot struct {
	State             string   `json:"state"`
	Health            string   `json:"health"`
	ReasonCodes       []string `json:"reason_codes"`
	SessionGeneration uint64   `json:"session_generation"`
	ConnectedAt       int64    `json:"connected_at"`
	HeartbeatAt       int64    `json:"heartbeat_at"`
	RuntimeReportedAt int64    `json:"runtime_reported_at"`
	LastSeen          int64    `json:"last_seen"`
}

type ControlSource

type ControlSource interface {
	GetControlSession(agentID string) (ControlSessionFact, bool)
}

type DirectAddressSnapshot

type DirectAddressSnapshot struct {
	URL string `json:"url"`
	Tag string `json:"tag"`
}

type DirectProbeRunner

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

func (*DirectProbeRunner) Path

func (r *DirectProbeRunner) Path() probePath

func (*DirectProbeRunner) Run

func (r *DirectProbeRunner) Run(ctx context.Context, job probeJob) probeRunResult

type DirectSnapshot

type DirectSnapshot struct {
	Generation uint64                          `json:"generation"`
	Summary    DirectSummary                   `json:"summary"`
	Targets    map[string]DirectTargetSnapshot `json:"targets,omitempty"`
}

type DirectSummary

type DirectSummary struct {
	State       string `json:"state"`
	Disabled    int    `json:"disabled"`
	Reachable   int    `json:"reachable"`
	Degraded    int    `json:"degraded"`
	Unreachable int    `json:"unreachable"`
	Stale       int    `json:"stale"`
	Total       int    `json:"total"`
}

type DirectTargetSnapshot

type DirectTargetSnapshot struct {
	TargetAgentID      string                  `json:"target_agent_id"`
	TargetName         string                  `json:"target_name"`
	Addresses          []DirectAddressSnapshot `json:"addresses"`
	Network            string                  `json:"network"`
	Identity           string                  `json:"identity"`
	Eligible           bool                    `json:"eligible"`
	Checking           bool                    `json:"checking"`
	ProbeGeneration    uint64                  `json:"probe_generation"`
	AddressFingerprint string                  `json:"address_fingerprint"`
	CheckedAt          int64                   `json:"checked_at"`
	LatencyMS          int64                   `json:"latency_ms"`
	LastError          *RecentError            `json:"last_error,omitempty"`
	RecentErrors       []RecentError           `json:"recent_errors"`
}

type HealthSource

type HealthSource interface {
	ReasonCodes(agentID string) []string
}

type Operation

type Operation string
const (
	OperationFullSync           Operation = "full_sync"
	OperationProbe              Operation = "probe"
	OperationRelayReconnect     Operation = "relay_reconnect"
	OperationRelayDrain         Operation = "relay_drain"
	OperationRelayDisconnect    Operation = "relay_disconnect"
	OperationDirectCircuitReset Operation = "direct_circuit_reset"
	OperationInterrupt          Operation = "interrupt"
)

type OperationDeniedError

type OperationDeniedError struct {
	Operation  Operation
	DenialCode string
}

func (*OperationDeniedError) Error

func (e *OperationDeniedError) Error() string

type OperationLease

type OperationLease struct {
	SnapshotEpoch     string
	ControlGeneration uint64
	RelayGeneration   uint64
}

type OperationStatus

type OperationStatus struct {
	Operation  Operation `json:"operation"`
	Allowed    bool      `json:"allowed"`
	DenialCode string    `json:"denial_code,omitempty"`
}

type Options

type Options struct {
	HeartbeatDegradedAfter     time.Duration
	RecoverySamples            int
	AgentTransportPolicyFinder AgentTransportPolicyFinder
	Now                        func() time.Time
	Logger                     *zap.Logger
}

type ProbeCaller

type ProbeCaller interface {
	CallDirectProbe(ctx context.Context, sourceID string, sourceGeneration uint64, target protocol.DirectProbeTarget) (protocol.DirectProbeResult, error)
}

type ProbeRunner

type ProbeRunner interface {
	Path() probePath
	Run(ctx context.Context, job probeJob) probeRunResult
}

type ProbeSourceFinder

type ProbeSourceFinder interface {
	FindEnabledProbeSource(ctx context.Context, sourceAgentID string) (ProbeTarget, error)
}

type ProbeTarget

type ProbeTarget struct {
	AgentID               string
	Name                  string
	Tags                  []string
	Addresses             []protocol.Address
	EffectiveProxy        string
	ControlGeneration     uint64
	Capabilities          []string
	DirectInboundEnabled  bool
	DirectOutboundEnabled bool
	RelayInboundEnabled   bool
	RelayOutboundEnabled  bool
	RelayMode             string
}

type ProbeTargetFinder

type ProbeTargetFinder interface {
	FindEnabledProbeTargets(ctx context.Context, targetAgentIDs []string) ([]ProbeTarget, error)
}

type ProbeTimings

type ProbeTimings struct {
	SuccessTTL      time.Duration
	FailureRetryMin time.Duration
	FailureRetryMax time.Duration
}

type RecentError

type RecentError struct {
	Code       string `json:"code"`
	Stage      string `json:"stage"`
	Message    string `json:"message"`
	OccurredAt int64  `json:"occurred_at"`
	Count      uint64 `json:"count"`
}

type RelayActiveSnapshot

type RelayActiveSnapshot struct {
	URI               string `json:"uri"`
	ActiveGeneration  uint64 `json:"active_generation"`
	SessionGeneration uint64 `json:"session_generation"`
	ConnectedAt       int64  `json:"connected_at"`
	Streams           int    `json:"streams"`
	RetryAt           int64  `json:"retry_at"`
}

type RelayDesiredSnapshot

type RelayDesiredSnapshot struct {
	Mode              string `json:"mode"`
	ConfiguredURI     string `json:"configured_uri"`
	EffectiveURI      string `json:"effective_uri"`
	DesiredGeneration uint64 `json:"desired_generation"`
}

type RelayPathSnapshot

type RelayPathSnapshot struct {
	Generation uint64                         `json:"generation"`
	Summary    RelayPathSummary               `json:"summary"`
	Targets    map[string]RelayTargetSnapshot `json:"targets,omitempty"`
}

type RelayPathSummary

type RelayPathSummary struct {
	State       string `json:"state"`
	Disabled    int    `json:"disabled"`
	Reachable   int    `json:"reachable"`
	Unreachable int    `json:"unreachable"`
	Unavailable int    `json:"unavailable"`
	Unknown     int    `json:"unknown"`
	Unsupported int    `json:"unsupported"`
	Stale       int    `json:"stale"`
	Total       int    `json:"total"`
}

type RelayProbeCaller

type RelayProbeCaller interface {
	CallRelayProbe(ctx context.Context, sourceID string, sourceGeneration uint64, target protocol.RelayProbeTarget) (protocol.RelayProbeResult, error)
}

type RelayProbeRunner

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

func (*RelayProbeRunner) Path

func (r *RelayProbeRunner) Path() probePath

func (*RelayProbeRunner) Run

func (r *RelayProbeRunner) Run(ctx context.Context, job probeJob) probeRunResult

type RelayRuntimeFact

type RelayRuntimeFact struct {
	Desired             RelayDesiredSnapshot
	Active              RelayActiveSnapshot
	Support             string
	Config              string
	Availability        string
	AcceptingNewStreams bool
	Convergence         string
	RecentErrors        []RecentError
}

type RelaySnapshot

type RelaySnapshot struct {
	Support             string               `json:"support"`
	Config              string               `json:"config"`
	Availability        string               `json:"availability"`
	AcceptingNewStreams bool                 `json:"accepting_new_streams"`
	Convergence         string               `json:"convergence"`
	Desired             RelayDesiredSnapshot `json:"desired"`
	Active              RelayActiveSnapshot  `json:"active"`
	RecentErrors        []RecentError        `json:"recent_errors"`
}

type RelaySource

type RelaySource interface {
	GetRelayRuntime(agentID string) (RelayRuntimeFact, bool)
}

type RelaySummary

type RelaySummary struct {
	Support             string `json:"support"`
	Config              string `json:"config"`
	Availability        string `json:"availability"`
	AcceptingNewStreams bool   `json:"accepting_new_streams"`
	Convergence         string `json:"convergence"`
	Streams             int    `json:"streams"`
}

type RelayTargetSnapshot

type RelayTargetSnapshot struct {
	TargetAgentID         string                   `json:"target_agent_id"`
	TargetName            string                   `json:"target_name"`
	State                 protocol.RelayProbeState `json:"state"`
	Stage                 protocol.RelayProbeStage `json:"stage,omitempty"`
	Checking              bool                     `json:"checking"`
	ProbeGeneration       uint64                   `json:"probe_generation"`
	RelayFingerprint      string                   `json:"relay_fingerprint"`
	SourceRelayGeneration uint64                   `json:"source_relay_generation"`
	TargetRelayGeneration uint64                   `json:"target_relay_generation"`
	CheckedAt             int64                    `json:"checked_at"`
	LatencyMS             int64                    `json:"latency_ms"`
	LastError             *RecentError             `json:"last_error,omitempty"`
	PolicyReason          string                   `json:"policy_reason,omitempty"`
}

type RouteDirectTargetSnapshot

type RouteDirectTargetSnapshot struct {
	State              string                  `json:"state"`
	PolicyReason       string                  `json:"policy_reason,omitempty"`
	Addresses          []DirectAddressSnapshot `json:"addresses"`
	Network            string                  `json:"network"`
	Identity           string                  `json:"identity"`
	Eligible           bool                    `json:"eligible"`
	Checking           bool                    `json:"checking"`
	ProbeGeneration    uint64                  `json:"probe_generation"`
	AddressFingerprint string                  `json:"address_fingerprint"`
	CheckedAt          int64                   `json:"checked_at"`
	LatencyMS          int64                   `json:"latency_ms"`
	LastError          *RecentError            `json:"last_error,omitempty"`
}

type RouteFailureDiagnostic

type RouteFailureDiagnostic struct {
	RequestID     string `json:"request_id"`
	SourceAgentID string `json:"source_agent_id"`
	TargetAgentID string `json:"target_agent_id"`
	RouteID       uint   `json:"route_id"`
	PathKind      string `json:"path_kind"`
	Stage         string `json:"stage"`
	CommitState   string `json:"commit_state"`
	ReasonCode    string `json:"reason_code"`
	OccurredAt    int64  `json:"occurred_at"`
}

type RouteTargetSnapshot

type RouteTargetSnapshot struct {
	TargetAgentID string                    `json:"target_agent_id"`
	TargetName    string                    `json:"target_name"`
	Direct        RouteDirectTargetSnapshot `json:"direct"`
	Relay         RelayTargetSnapshot       `json:"relay"`
}

type RouteTargetSummaries

type RouteTargetSummaries struct {
	Direct DirectSummary    `json:"direct"`
	Relay  RelayPathSummary `json:"relay"`
}

type RouteTargetsPage

type RouteTargetsPage struct {
	SnapshotEpoch string                `json:"snapshot_epoch"`
	SnapshotSeq   uint64                `json:"snapshot_seq"`
	ObservedAt    int64                 `json:"observed_at"`
	Summaries     RouteTargetSummaries  `json:"summaries"`
	Data          []RouteTargetSnapshot `json:"data"`
	NextCursor    string                `json:"next_cursor,omitempty"`
	Limit         int                   `json:"limit"`
}

type RouteTargetsSnapshot

type RouteTargetsSnapshot struct {
	Generation uint64                         `json:"generation"`
	Summaries  RouteTargetSummaries           `json:"summaries"`
	Targets    map[string]RouteTargetSnapshot `json:"targets"`
}

type Scheduler

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

func NewScheduler

func NewScheduler(control ProbeCaller, service *Service, opts SchedulerOptions) *Scheduler

func (*Scheduler) Cancel

func (s *Scheduler) Cancel()

func (*Scheduler) Close

func (s *Scheduler) Close(ctx context.Context) error

func (*Scheduler) Done

func (s *Scheduler) Done() <-chan struct{}

func (*Scheduler) EnqueueManual

func (s *Scheduler) EnqueueManual(ctx context.Context, sourceID string, scope protocol.ProbeScope) (protocol.ProbeAck, error)

func (*Scheduler) EnqueueManualSession

func (s *Scheduler) EnqueueManualSession(ctx context.Context, sourceID string, expectedControlGeneration uint64, scope protocol.ProbeScope) (protocol.ProbeAck, error)

func (*Scheduler) FindProgressForSource

func (s *Scheduler) FindProgressForSource(sourceID, probeID string) (protocol.ManualProbeProgress, bool)

func (*Scheduler) Progress

func (s *Scheduler) Progress(probeID string) (protocol.ManualProbeProgress, bool)

func (*Scheduler) ResourceCount

func (s *Scheduler) ResourceCount() int

func (*Scheduler) Run

func (s *Scheduler) Run(ctx context.Context) error

func (*Scheduler) SetTimings

func (s *Scheduler) SetTimings(successTTL, failureRetryMin, failureRetryMax time.Duration)

type SchedulerOptions

type SchedulerOptions struct {
	GlobalConcurrency    int
	PerSourceConcurrency int
	SuccessTTL           time.Duration
	FailureRetryMin      time.Duration
	FailureRetryMax      time.Duration
	ManualRetention      time.Duration
	MaxProgressEntries   int
	Now                  func() time.Time
	ProbeTargetFinder    ProbeTargetFinder
}

type Service

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

func NewService

func NewService(instanceID string, sources Sources, opts Options) *Service

func (*Service) AdvanceRouteObservationSession

func (s *Service) AdvanceRouteObservationSession(sourceID string, controlGeneration uint64)

func (*Service) ApplyDirectProbeResult

func (s *Service) ApplyDirectProbeResult(sourceID string, sourceGeneration uint64, target ProbeTarget, result protocol.DirectProbeResult, probeGeneration uint64)

func (*Service) ApplyEvents

func (s *Service) ApplyEvents(sourceID string, batch protocol.RouteTelemetryBatch) error

func (*Service) ApplyRelayProbeResult

func (s *Service) ApplyRelayProbeResult(
	sourceID string,
	sourceControlGeneration uint64,
	target ProbeTarget,
	fingerprint string,
	probeGeneration uint64,
	sourceRelayGeneration uint64,
	targetRelayGeneration uint64,
	result protocol.RelayProbeResult,
)

func (*Service) ApplySessionEvents

func (s *Service) ApplySessionEvents(sourceID string, controlGeneration uint64, batch protocol.RouteTelemetryBatch) error

func (*Service) Authorize

func (s *Service) Authorize(agent models.Agent, op Operation) (OperationLease, error)

func (*Service) Build

func (s *Service) Build(agent models.Agent) ConnectionSnapshot

func (*Service) BuildContext added in v0.0.14

func (s *Service) BuildContext(ctx context.Context, agent models.Agent) (ConnectionSnapshot, error)

func (*Service) BuildMany

func (s *Service) BuildMany(agents []models.Agent) SnapshotBatch

func (*Service) BuildManyContext added in v0.0.14

func (s *Service) BuildManyContext(ctx context.Context, agents []models.Agent) (SnapshotBatch, error)

func (*Service) FinishDirectProbeWithoutResult

func (s *Service) FinishDirectProbeWithoutResult(sourceID string, sourceGeneration uint64, target ProbeTarget, fingerprint string, probeGeneration uint64)

func (*Service) FinishRelayProbeWithoutResult

func (s *Service) FinishRelayProbeWithoutResult(
	sourceID string,
	sourceControlGeneration uint64,
	target ProbeTarget,
	fingerprint string,
	probeGeneration uint64,
)

func (*Service) Forget

func (s *Service) Forget(agentID string, generation uint64)

func (*Service) MarkDirectProbeChecking

func (s *Service) MarkDirectProbeChecking(sourceID string, sourceGeneration uint64, target ProbeTarget, fingerprint string, probeGeneration uint64)

func (*Service) MarkRelayProbeChecking

func (s *Service) MarkRelayProbeChecking(
	sourceID string,
	sourceControlGeneration uint64,
	target ProbeTarget,
	fingerprint string,
	probeGeneration uint64,
	sourceRelayGeneration uint64,
	targetRelayGeneration uint64,
)

func (*Service) ReplaceDigest

func (s *Service) ReplaceDigest(sourceID string, digest protocol.RouteEdgeDigest) error

func (*Service) ReplaceSessionDigest

func (s *Service) ReplaceSessionDigest(sourceID string, controlGeneration uint64, digest protocol.RouteEdgeDigest) error

func (*Service) RouteEdgeSources

func (s *Service) RouteEdgeSources() []string

func (*Service) RouteEdges

func (s *Service) RouteEdges(sourceID string) []protocol.RouteEdgeSnapshot

func (*Service) RouteFailures

func (s *Service) RouteFailures(sourceID string) []RouteFailureDiagnostic

func (*Service) Run

func (s *Service) Run(ctx context.Context)

type SnapshotBatch

type SnapshotBatch struct {
	SnapshotEpoch string
	SnapshotSeq   uint64
	ObservedAt    int64
	Items         map[string]ConnectionSnapshot
}

type Sources

type Sources struct {
	Control ControlSource
	Relay   RelaySource
	Health  HealthSource
}

type TransportDirectionSnapshot added in v0.0.14

type TransportDirectionSnapshot struct {
	Configured bool   `json:"configured"`
	Effective  bool   `json:"effective"`
	ReasonCode string `json:"reason_code,omitempty"`
}

Jump to

Keyboard shortcuts

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