probe

Documentation

Overview

Package probe implements OS-native ping / trace / mtr engines rather than open raw ICMP sockets. Raw sockets require root or CAP_NET_RAW on Linux, are restricted on macOS user sessions, and need elevated privileges on Windows. Shelling out works everywhere with no setup; this is a deliberate non-feature.

Index

• func MTR(ctx context.Context, target string, cycles int, interval time.Duration, ...) <-chan MTRUpdate
• func OutboundIP(target string) string
• func PingStream(ctx context.Context, target string, opts PingOptions) (<-chan PingEvent, <-chan PingResult, error)
• func TraceStream(ctx context.Context, target string, opts TraceOptions) (<-chan TraceEvent, <-chan TraceResult, error)
• type MTRResult
• type MTRStat
• type MTRUpdate
• type PingEvent
• type PingOptions
• type PingReply
• type PingResult
  • func Ping(ctx context.Context, target string, opts PingOptions) (PingResult, error)
• type TraceEvent
• type TraceHop
• type TraceOptions
• type TraceResult
  • func Trace(ctx context.Context, target string, opts TraceOptions) (TraceResult, error)

Functions

func MTR

func MTR(ctx context.Context, target string, cycles int, interval time.Duration, traceOpts TraceOptions) <-chan MTRUpdate

MTR runs traceroute every `interval` until ctx is cancelled or `cycles` is reached (0 = infinite). It emits an MTRUpdate on the returned channel after each cycle.

func OutboundIP

func OutboundIP(target string) string

OutboundIP returns the local IP address that would be used to reach target. Uses a UDP "connect" (no packets sent to avoid overhead) so the OS fills in the correct source address via routing table lookup. Returns an empty string if resolution fails.

func PingStream

func PingStream(ctx context.Context, target string, opts PingOptions) (<-chan PingEvent, <-chan PingResult, error)

PingStream runs ping and streams parsed replies on the returned channel. The channel is closed when ping exits. The final aggregated PingResult is sent on `done` (single value, then closed).

func TraceStream

func TraceStream(ctx context.Context, target string, opts TraceOptions) (<-chan TraceEvent, <-chan TraceResult, error)

TraceStream runs traceroute and streams parsed hops on `events` as they appear. The final aggregated TraceResult is sent on `done` (single value, then closed).

Types

type MTRResult

type MTRResult struct {
	Target string    `json:"target"`
	Cycles int       `json:"cycles"`
	Hops   []MTRStat `json:"hops"`
}

MTRResult is the accumulated MTR state, suitable for live render or final snapshot.

type MTRStat

type MTRStat struct {
	Hop    int     `json:"hop"`
	IP     string  `json:"ip"`
	LossPc float64 `json:"loss"`
	Snt    int     `json:"snt"`
	Last   float64 `json:"last"`
	Avg    float64 `json:"avg"`
	Best   float64 `json:"best"`
	Wrst   float64 `json:"wrst"`
	StDev  float64 `json:"stdev"`
	// contains filtered or unexported fields
}

MTRStat is per-hop running stats in classic mtr column order.

type MTRUpdate

type MTRUpdate struct {
	Cycle    int
	Snapshot MTRResult
}

MTRUpdate is emitted on the channel after each completed cycle.

type PingEvent

type PingEvent struct {
	Reply PingReply
}

PingEvent is delivered for every echo reply parsed from the live ping output. emitted as the kernel hands them to us so the renderer can show rows in real time.

type PingOptions

type PingOptions struct {
	Count      int
	PacketSize int
	TimeoutMs  int
	IntervalMs int
}

PingOptions controls the Ping engine. Zero values are filled in from the package defaults (count=4, packet 56B, 1s timeout, 1s interval).

type PingReply

type PingReply struct {
	Seq    int     `json:"seq"`
	Bytes  int     `json:"bytes"`
	Source string  `json:"source"` // local outbound IP
	Target string  `json:"target"` // probe target (host or IP)
	IP     string  `json:"ip"`
	TTL    int     `json:"ttl"`
	TimeMs float64 `json:"timeMs"`
	Status string  `json:"status"` // "ok" | "timeout"

	// Enrichment (DNS populated when dns.public/dns.private are set;
	// org/asn/location/city/region/country/loc from ipinfo;
	// policy/net_type/pdb_* from PeeringDB).
	PublicDNS  string `json:"publicDns,omitempty"`
	PrivateDNS string `json:"privateDns,omitempty"`
	Hostname   string `json:"hostname,omitempty"` // ipinfo PTR
	Org        string `json:"org,omitempty"`
	ASN        string `json:"asn,omitempty"`
	Location   string `json:"location,omitempty"` // "City, CC"
	City       string `json:"city,omitempty"`
	Region     string `json:"region,omitempty"`
	Country    string `json:"country,omitempty"`
	Loc        string `json:"loc,omitempty"` // "lat,lon"
	Policy     string `json:"policy,omitempty"`
	NetType    string `json:"netType,omitempty"`
	PdbName    string `json:"pdbName,omitempty"`
	Traffic    string `json:"traffic,omitempty"`
	Prefixes4  int    `json:"prefixes4,omitempty"`
	Prefixes6  int    `json:"prefixes6,omitempty"`
	IXPCount   int    `json:"ixpCount,omitempty"`
}

PingReply describes one echo reply (or one timeout).

type PingResult

type PingResult struct {
	Command  string      `json:"command"`
	Sent     int         `json:"sent"`
	Received int         `json:"received"`
	LossPct  float64     `json:"lossPct"`
	AvgMs    float64     `json:"avgMs"`
	MinMs    float64     `json:"minMs"`
	MaxMs    float64     `json:"maxMs"`
	Packets  []PingReply `json:"packets"`
}

PingResult is the parsed outcome of a ping run.

func Ping

func Ping(ctx context.Context, target string, opts PingOptions) (PingResult, error)

Ping is a convenience wrapper that drains PingStream and returns the final aggregated PingResult. Most callers should prefer PingStream for live output.

type TraceEvent

type TraceEvent struct {
	Hop TraceHop
}

TraceEvent is emitted for each parsed hop as traceroute prints it.

type TraceHop

type TraceHop struct {
	Hop      int     `json:"hop"`
	Source   string  `json:"source"` // local outbound IP
	Target   string  `json:"target"` // probe target (host or IP)
	IP       string  `json:"ip"`
	Host     string  `json:"host,omitempty"`
	Probe1Ms float64 `json:"probe1Ms"`
	Probe2Ms float64 `json:"probe2Ms"`
	Probe3Ms float64 `json:"probe3Ms"`
	TimeMs   float64 `json:"timeMs"` // = Probe1Ms, kept for back-compat
	Status   string  `json:"status"` // "ok" | "timeout"

	// Enrichment (see PingReply for field semantics).
	PublicDNS  string `json:"publicDns,omitempty"`
	PrivateDNS string `json:"privateDns,omitempty"`
	Hostname   string `json:"hostname,omitempty"`
	Org        string `json:"org,omitempty"`
	ASN        string `json:"asn,omitempty"`
	Location   string `json:"location,omitempty"`
	City       string `json:"city,omitempty"`
	Region     string `json:"region,omitempty"`
	Country    string `json:"country,omitempty"`
	Loc        string `json:"loc,omitempty"`
	Policy     string `json:"policy,omitempty"`
	NetType    string `json:"netType,omitempty"`
	PdbName    string `json:"pdbName,omitempty"`
	Traffic    string `json:"traffic,omitempty"`
	Prefixes4  int    `json:"prefixes4,omitempty"`
	Prefixes6  int    `json:"prefixes6,omitempty"`
	IXPCount   int    `json:"ixpCount,omitempty"`
}

TraceHop is one row of traceroute output (one TTL).

type TraceOptions

type TraceOptions struct {
	MaxHops    int
	Queries    int
	WaitMs     int
	PacketSize int
}

TraceOptions controls the Trace engine.

type TraceResult

type TraceResult struct {
	Command string     `json:"command"`
	Hops    []TraceHop `json:"hops"`
}

TraceResult is the parsed outcome of a traceroute run.

func Trace

func Trace(ctx context.Context, target string, opts TraceOptions) (TraceResult, error)

Trace is the buffered convenience wrapper.