probe

Documentation

Index

• func ParseCloudflareTrace(body []byte) (netip.Addr, *string, error)
• type EgressProbeResult
• type Fetcher
  • func DirectFetcher(timeout func() time.Duration) Fetcher
• type LatencyProbeResult
• type ProbeConfig
• type ProbeManager
  • func NewProbeManager(cfg ProbeConfig) *ProbeManager
  • func (m *ProbeManager) ProbeEgressSync(hash node.Hash) (*EgressProbeResult, error)
  • func (m *ProbeManager) ProbeLatencySync(hash node.Hash) (*LatencyProbeResult, error)
  • func (m *ProbeManager) SetOnProbeEvent(fn func(kind string))
  • func (m *ProbeManager) Start()
  • func (m *ProbeManager) Stop()
  • func (m *ProbeManager) TriggerImmediateEgressProbe(hash node.Hash)
  • func (m *ProbeManager) TriggerImmediateLatencyProbe(hash node.Hash)

Functions

func ParseCloudflareTrace

func ParseCloudflareTrace(body []byte) (netip.Addr, *string, error)

ParseCloudflareTrace parses a Cloudflare /cdn-cgi/trace response body and extracts the "ip" field plus optional "loc" field.

Example response body:

fl=123
h=1.2.3.4
ip=203.0.113.1
ts=1234567890
...

Types

type EgressProbeResult

type EgressProbeResult struct {
	EgressIP      string  `json:"egress_ip"`
	Region        string  `json:"region,omitempty"`
	LatencyEwmaMs float64 `json:"latency_ewma_ms"`
}

EgressProbeResult holds the results of a synchronous egress probe.

type Fetcher

type Fetcher func(hash node.Hash, url string) (body []byte, latency time.Duration, err error)

Fetcher executes an HTTP request through the given node, returning response body and TLS handshake latency. This is injectable for testing.

func DirectFetcher

func DirectFetcher(timeout func() time.Duration) Fetcher

DirectFetcher creates a Fetcher that performs direct HTTP requests (not through a node outbound). This is mostly useful for tests or fallback wiring.

timeout is a closure that returns the current probe timeout.

type LatencyProbeResult

type LatencyProbeResult struct {
	LatencyEwmaMs float64 `json:"latency_ewma_ms"`
}

LatencyProbeResult holds the results of a synchronous latency probe.

type ProbeConfig

type ProbeConfig struct {
	Pool        *topology.GlobalNodePool
	Concurrency int // number of async probe workers
	// QueueCapacity is the per-priority async queue capacity.
	// If <= 0, defaults to max(1024, Concurrency*4).
	QueueCapacity int

	// Fetcher executes HTTP via node hash. Injectable for testing.
	Fetcher Fetcher

	// Interval thresholds — closures for hot-reload from RuntimeConfig.
	MaxEgressTestInterval           func() time.Duration
	MaxLatencyTestInterval          func() time.Duration
	MaxAuthorityLatencyTestInterval func() time.Duration

	LatencyTestURL     func() string
	LatencyAuthorities func() []string

	// OnProbeEvent is called after each probe attempt completes (egress or latency).
	// The kind parameter is "egress" or "latency".
	OnProbeEvent func(kind string)

	// ChooseNormalWhenBoth chooses whether to pop normal-priority queue when
	// both high and normal queues are non-empty.
	// Nil defaults to 10% chance.
	ChooseNormalWhenBoth func() bool
}

ProbeConfig configures the ProbeManager. Field names align 1:1 with RuntimeConfig to prevent mis-wiring.

type ProbeManager

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

ProbeManager schedules and executes active probes against nodes in the pool. It holds a direct reference to *topology.GlobalNodePool (no interface).

func NewProbeManager

func NewProbeManager(cfg ProbeConfig) *ProbeManager

NewProbeManager creates a new ProbeManager.

func (*ProbeManager) ProbeEgressSync

func (m *ProbeManager) ProbeEgressSync(hash node.Hash) (*EgressProbeResult, error)

ProbeEgressSync performs a blocking egress probe and returns the results. Used by API action endpoints that must return probe data synchronously.

func (*ProbeManager) ProbeLatencySync

func (m *ProbeManager) ProbeLatencySync(hash node.Hash) (*LatencyProbeResult, error)

ProbeLatencySync performs a blocking latency probe and returns the results.

func (*ProbeManager) SetOnProbeEvent

func (m *ProbeManager) SetOnProbeEvent(fn func(kind string))

SetOnProbeEvent sets the probe event callback. Must be called before Start.

func (*ProbeManager) Start

func (m *ProbeManager) Start()

Start launches the background probe workers.

func (*ProbeManager) Stop

func (m *ProbeManager) Stop()

Stop signals all probe workers to stop and waits for completion.

Design note:

• In-flight worker tasks are drained before Stop returns.
• Pending queued tasks are dropped on stop.
• We intentionally do not reject post-stop triggers via extra manager-global state; expected ownership is that callers stop upstream event sources first.

func (*ProbeManager) TriggerImmediateEgressProbe

func (m *ProbeManager) TriggerImmediateEgressProbe(hash node.Hash)

TriggerImmediateEgressProbe enqueues an async egress probe for a node. Caller returns immediately.

func (*ProbeManager) TriggerImmediateLatencyProbe

func (m *ProbeManager) TriggerImmediateLatencyProbe(hash node.Hash)

TriggerImmediateLatencyProbe enqueues an async latency probe for a node. Caller returns immediately.