Documentation
¶
Overview ¶
Package nodesapi is the Go client for the pilot-geo-exporter `/nodes` service. The service exposes the registry's online-external-node set as JSON, gated by a shared token, reachable via the IAP tunnel to the rendezvous host.
Use this package from Go services that need to enumerate or filter live nodes — e.g. broadcast targets, onboarding agent's catalog, persona-agent peer discovery, validation harnesses.
Wire shape (HTTP/JSON, stable v1):
GET /nodes → full external-online node list (token required) GET /nodes/by_ip?ip=… → filtered to one IP (token required) GET /metrics → Prometheus scrape (no token) GET /healthz → liveness probe (no token)
Token auth: pass via ?token=… query param OR X-Token header. This client uses the header by default to keep the token out of access logs.
"External" = NOT in the exporter's INFRA_IPS env var. "Online" = last_seen within ONLINE_THRESHOLD seconds (default 600). The full list may be capped at NODE_INFO_MAX entries server-side; check Response.MetricTruncated.
Index ¶
Constants ¶
const DefaultBaseURL = "http://127.0.0.1:9117"
DefaultBaseURL is the loopback address used when this client runs ON the rendezvous host (no IAP tunnel needed). Off-host callers should pass the IAP-tunneled local-port URL — typically `http://127.0.0.1:<local>` after `gcloud compute start-iap-tunnel pilot-rendezvous-new 9117`.
const DefaultTimeout = 30 * time.Second
DefaultTimeout matches a comfortable upper bound on `/nodes` response time at typical fleet sizes (~100k nodes ≈ 30 MB JSON over IAP).
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is the minimal HTTP client. Construct with New and reuse — it's safe for concurrent use.
func New ¶
New constructs a Client. Pass an empty baseURL to use DefaultBaseURL. The token is required if the service is configured with NODES_TOKEN.
func (*Client) ByIP ¶
ByIP fetches the subset of external-online nodes registered against the given IP. Server-side filter — much smaller payload than List + client-side.
type Node ¶
type Node struct {
NodeID uint32 `json:"node_id"`
IP string `json:"ip"`
Country string `json:"country"` // ISO-3166-1 alpha-2; "XX" = unresolved
Hostname string `json:"hostname"`
Public bool `json:"public"`
RealAddr string `json:"real_addr"`
LastSeen string `json:"last_seen"` // RFC3339, may be empty
LastSeenUnix float64 `json:"last_seen_unix"` // 0 if missing
AgeS *int `json:"age_s"` // nil if last_seen missing
}
Node is one entry in Response.Nodes. Field tags match the wire JSON.
type Response ¶
type Response struct {
UpdatedAt float64 `json:"updated_at"`
OnlineThresholdSeconds int `json:"online_threshold_seconds"`
InfraIPsExcluded []string `json:"infra_ips_excluded"`
MetricCap int `json:"metric_cap"`
MetricTruncated bool `json:"metric_truncated"`
RequireHostnameFilter bool `json:"require_hostname_filter"`
Count int `json:"count"`
Nodes []Node `json:"nodes"`
}
Response is the envelope returned by /nodes and /nodes/by_ip.
func (*Response) FilterCountry ¶
FilterCountry returns nodes whose Country matches the given ISO code. Case-insensitive.
func (*Response) FilterHostnamed ¶
FilterHostnamed returns only nodes that have a non-empty hostname (i.e. explicitly configured agents, not bare daemons).
func (*Response) FilterPublic ¶
FilterPublic returns only nodes whose Public flag is true.
Source Files