proxystatus

type Accept struct {
	Accepted    uint64  `json:"accepted"`
	NoTunnel    uint64  `json:"no_tunnel,omitempty"`
	OpenFailed  uint64  `json:"open_failed,omitempty"`
	Opened      uint64  `json:"opened,omitempty"`
	MaxOpenMS   float64 `json:"max_open_ms,omitempty"`
	LastOpenErr string  `json:"last_open_err,omitempty"`
}

type Alias struct {
	Name string `json:"name"`
	PK   string `json:"pk"`
}

type Conn struct {
	ID         string `json:"id"`
	Network    string `json:"network,omitempty"`
	LocalPort  int    `json:"local_port,omitempty"`
	RemotePort int    `json:"remote_port,omitempty"`
}

type Consumer struct {
	// Name is the app name, or "inbound :<port>" for a route group this visor
	// accepted rather than dialed.
	Name    string
	Inbound bool
	Running bool
	Tunnels []Tunnel
}

type DmsgSession struct {
	ServerPK string  `json:"server_pk"`
	Protocol string  `json:"protocol,omitempty"` // carrier label (tcp / quic / ws / wt)
	Addr     string  `json:"addr,omitempty"`     // the carrier address the session rides
	Streams  int     `json:"streams"`
	PingMS   float64 `json:"ping_ms,omitempty"`
}

type DomainRoute struct {
	// Suffix is the domain the rule covers, with its subdomains; "*" for
	// the default.
	Suffix string `json:"suffix"`
	// Upstream is the SOCKS5 address hosts matching Suffix leave through,
	// or "direct".
	Upstream string `json:"upstream"`
	// Via names the local app listening on Upstream and whether it runs,
	// empty when none is known.
	Via string `json:"via,omitempty"`
}

type Forward struct {
	Port      int    `json:"port"`
	LocalPort int    `json:"local_port,omitempty"`
	Label     string `json:"label,omitempty"`
	Skynet    bool   `json:"skynet,omitempty"`
	DMSG      bool   `json:"dmsg,omitempty"`
	UDP       bool   `json:"udp,omitempty"`
}

type Hop struct {
	TpID      string
	From      string
	To        string
	TpType    string
	LatencyMS float64
	// ThroughputBps is the hop transport's passively observed peak goodput in
	// bytes/s (transport.Entry.ThroughputBps), 0 when this visor holds no
	// entry for the transport. It is what lets a route that has never carried
	// a byte be given a capacity PRIOR instead of a guess: the first hop is
	// always owned locally, and a deeper hop reports a number only when the
	// visor happens to hold that transport too. RTT says how LONG a path is;
	// this is the only field that says how WIDE it is.
	ThroughputBps float64 `json:"throughput_bps,omitempty"`
}

type Layer struct {
	Listen string `json:"listen,omitempty"` // SOCKS5 listener the layer binds, e.g. "127.0.0.1:4445"
	Suffix string `json:"suffix,omitempty"` // domain suffix it resolves, e.g. ".dmsg"
	// Upstream is the DOWNSTREAM chain target: the SOCKS5 a non-matching CONNECT
	// is forwarded to (dmsg_web → skynet_web → skysocks-client). Empty when the
	// layer terminates the chain.
	Upstream string `json:"upstream,omitempty"`
	// UpstreamState is an honest, non-probing label for the chain target's
	// liveness — derived from what the visor already knows about the process or
	// runtime behind that address (e.g. "skynet_web running"). Empty when the
	// address belongs to something the visor cannot vouch for; the page then shows
	// the address alone rather than claiming reachability it did not verify.
	UpstreamState string     `json:"upstream_state,omitempty"`
	StartedAt     *time.Time `json:"started_at,omitempty"`
	UptimeSec     int64      `json:"uptime_sec,omitempty"`
	Requests      uint64     `json:"requests"`
	Successful    uint64     `json:"successful"`
	Failed        uint64     `json:"failed"`
	Active        int64      `json:"active"` // requests in flight right now
	LastRequestAt *time.Time `json:"last_request_at,omitempty"`
	LastError     string     `json:"last_error,omitempty"`
}

type Leg struct {
	Index       int
	TransportID string
	TpType      string
	RemotePK    string
	// LatencyMS is the first-hop transport RTT; RouteLatencyMS is the leg's
	// true end-to-end route latency (all hops). Direct is true for a 1-hop
	// route to the destination, false for a multihop (relayed) leg.
	LatencyMS      float64
	RouteLatencyMS float64
	Direct         bool
	SentBytes      uint64
	RecvBytes      uint64
	// DupBytes is inbound DUPLICATE data (seqs already delivered/buffered when
	// they arrived on this leg) — the peer's spurious retransmits, which ride
	// the fastest leg and otherwise read as payload; RepairBytes is inbound FEC
	// repair frames. Both decompose RecvBytes so a standby leg showing inbound
	// traffic is explainable from the page.
	DupBytes    uint64
	RepairBytes uint64
	Retransmits uint64
	// GoodputBps is this leg's recent goodput — the EWMA of (sent+recv) bytes
	// per second over the page's refresh window (~1s), i.e. the RATE the leg is
	// moving now, distinct from the cumulative SentBytes/RecvBytes counters. 0
	// until a second sample lands. GoodputUpBps/GoodputDownBps split it by
	// direction (send-rate / recv-rate), shown beside the ↑/↓ byte totals and
	// driving the per-route share bars; GoodputBps is their sum.
	GoodputBps     float64
	GoodputUpBps   float64
	GoodputDownBps float64
	Alive          bool
	Standby        bool
	// Source names where a leg that is not this group's own dial came from:
	// a leg the standby-pool arbiter took ("standby :4, re-homed in place").
	// Empty for an ordinary dialed leg.
	Source string `json:"source,omitempty"`
	// Hops is the leg's full forward route (every hop to the destination),
	// full PKs, per-hop transport type + latency where known.
	Hops []Hop
}

type Names struct {
	Kind    string  `json:"kind,omitempty"`
	Suffix  string  `json:"suffix,omitempty"`
	Aliases []Alias `json:"aliases,omitempty"`
}

type Provider interface {
	StatusSnapshot(surface Surface) (Snapshot, error)
}

type RangeSplit struct {
	Enabled         bool   `json:"enabled"`           // feature is on for this client
	ActiveSplits    int64  `json:"active_splits"`     // splits in flight right now
	TotalSplits     uint64 `json:"total_splits"`      // cumulative splits performed
	TotalChunks     uint64 `json:"total_chunks"`      // cumulative range chunks fetched
	TotalBytes      uint64 `json:"total_bytes"`       // cumulative bytes delivered via split
	StreamsPerSplit int    `json:"streams_per_split"` // configured concurrency (streams per split)
	ChunkSize       int64  `json:"chunk_size"`        // bytes per range request
}

type Snapshot struct {
	Surface Surface
	App     string // underlying app/logger name (dmsgweb / skynetweb / skysocks-client)
	// SelfPK is this visor's own public key — the route source. Carried explicitly
	// so the tree/graph can label the source and place each leg's first hop even
	// when the legs have no recorded forward-hop path (the router does not always
	// record it for auto/standby legs); treeSrc falls back to this.
	SelfPK     string
	Running    bool  // whether the surface's process/runtime is currently alive
	MuxEnabled bool  // route group has multiplexing enabled
	Legs       []Leg // current per-leg mux state (empty when no active route group)
	// Tunnels is the STREAM-level view: one entry per active route group (a
	// --tunnels stream), each carrying its own PACKET-level mux Legs. The two
	// levels of route multiplexing are stream (tunnels, disjoint route groups)
	// over packet (mux legs striping within a group). When populated the route
	// tree nests tunnel → legs; when empty the tree falls back to the flat Legs
	// list above (a caller that only projects a single route group). Legs mirrors
	// Tunnels[0].Legs for back-compat.
	Tunnels []Tunnel
	// ShapeTunnels is how many ACTIVE tunnels the session's mux.shape target
	// asks for — the k of "<k>x<n>" — and ShapeSource where that target came
	// from: "mux.shape" for an operator-named shape, "auto" (or empty) for the
	// default. The dialing app FOLLOWS k with its own active set: the router
	// can flip a route group's role, but only the app owns the yamux session
	// that puts streams on one (pkg/skysocks reconcileActiveSet).
	ShapeTunnels int    `json:"shape_tunnels,omitempty"`
	ShapeSource  string `json:"shape_source,omitempty"`
	// DisjointRoutes is how many routes to the exit share no intermediate and
	// no first hop: one per intermediate this visor and the exit both hold a
	// transport to, plus the direct transports. 0 until the router has counted
	// them. An auto-sized standby pool (--standby-pool -1) holds this many
	// tunnels, up to pool.size_cap.
	DisjointRoutes int      `json:"disjoint_routes,omitempty"`
	Logs           []string // recent log lines, oldest first
	Events         []string // route/transport events affecting this surface, oldest first
	Streams        []Stream // per-stream detail for the open session (skysocks tunnel), when tracked
	// Accept is the accept path's accounting, which covers the stage BEFORE a
	// connection becomes a row in Streams. Nil until something has been
	// accepted. See the Accept type.
	Accept *Accept `json:"accept,omitempty"`
	// RangeSplit summarizes transparent HTTP range-splitting activity on the
	// surface (skysocks only): whether a split is firing right now and its
	// cumulative shape. Nil when the surface does not range-split (every
	// non-skysocks surface, or a skysocks client with the feature disabled). It
	// makes "is range-split firing" a readable field rather than a log line.
	RangeSplit *RangeSplit `json:"range_split,omitempty"`
	// Layer is the RESOLVING-PROXY layer summary — liveness/uptime, the listener
	// and domain suffix it answers for, its request counters and the downstream
	// SOCKS5 it chains to. Populated for the dmsg_web / skynet_web surfaces, whose
	// interesting state is the layer itself rather than a route group; nil for a
	// surface with no such layer (skysocks, whose tunnel state is Legs/Streams).
	Layer *Layer `json:"layer,omitempty"`
	// Sessions is the dmsg client's established sessions to dmsg servers — the
	// dmsg surface's answer to "what am I actually connected through". Empty for
	// every other surface (they do not relay over dmsg sessions).
	Sessions []DmsgSession `json:"sessions,omitempty"`
	// Names is the layer's name-resolution state: which resolver answers a
	// <name><suffix> lookup and the aliases actually configured on it. There is no
	// lookup CACHE in either resolving proxy today, so no "recent lookups" list is
	// invented here — only the resolution machinery that exists is surfaced.
	Names *Names `json:"names,omitempty"`
	// Forwards is what this visor exposes to the mesh through the surface's
	// forwarding plane (skynet surface: the registered forwarded ports). Empty
	// when nothing is forwarded, or for a surface with no forwarding plane.
	Forwards []Forward `json:"forwards,omitempty"`
	// Conns is the surface's active raw forwarded connections with their metered
	// port pairs — the conn-level view for layers that have no route-group Legs.
	Conns []Conn `json:"conns,omitempty"`
	// ExitOpenTimeouts counts the skysocks client's exit opens that timed out: a
	// stream on a live tunnel whose exit never answered the SOCKS5 greeting, so
	// the browser was handed nothing. Cumulative for the life of the client, and
	// the one failure mode the page reported neither as a leg nor as a stream.
	// Zero (omitted) for every other surface.
	ExitOpenTimeouts uint64 `json:"exit_open_timeouts,omitempty"`
	// Consumers is the skywire surface's content: one entry per app or visor
	// subsystem holding a route group or a direct stream. Empty for every
	// other surface.
	Consumers []Consumer `json:"consumers,omitempty"`
	// DomainRoutes are the resolvers' per-domain upstream rules, last the
	// default every other host takes. Skywire surface only; empty when no
	// rule is set.
	DomainRoutes []DomainRoute `json:"domain_routes,omitempty"`
	Note         string        // optional human note (e.g. why a section is empty)
}

type Stream struct {
	ID          uint32  // yamux stream id
	Target      string  // the CONNECT target host:port the stream carries (never a PK)
	AgeMS       int64   // how long the stream has been open, milliseconds
	SentBytes   uint64  // cumulative bytes browser→exit (up) on this stream
	RecvBytes   uint64  // cumulative bytes exit→browser (down) on this stream
	SentRateBps float64 // smoothed up rate in bytes/sec (EWMA over the refresh window); 0 until a second sample lands
	RecvRateBps float64 // smoothed down rate in bytes/sec (EWMA over the refresh window)
	// LatencyMS is the ROUTE-GROUP latency of the stream's session to the exit,
	// NOT a per-stream RTT — yamux exposes no per-stream round-trip. It is the
	// representative route latency of the surface's live legs, attached to every
	// stream and LABELED as route-group latency by the renderer rather than faked
	// as a per-stream number. 0 when unmeasured.
	LatencyMS float64
}

type Surface string

type Tunnel struct {
	Index      int    // tunnel index in dial order (0-based)
	ExitPK     string // destination exit PK (full, never truncated); same across tunnels
	MuxEnabled bool   // this tunnel's route group has packet-level mux enabled
	Legs       []Leg  // this tunnel's packet-level mux legs
	// Role is "active" (the tunnel carries streams) or "standby" (it is held
	// open, kept alive and measured, carrying nothing, so it can be switched
	// in without a route setup). Empty when the client did not label it — a
	// single-tunnel session, or a route group belonging to something else.
	// It is the local end's own label; an exit cannot know it.
	Role string
	// LegReserve marks a standby group a leg split handed back to the pool: it
	// can be composed back in as a leg but never becomes a tunnel, because no
	// app session runs over it.
	LegReserve bool
	// LocalPort is the route group's LOCAL port — the one name the app, the
	// visor and the bench's carrier.tsv already share for one tunnel (the
	// same port NoteMuxEvent is addressed by). It is what lets the dialing
	// app match a tunnel in this snapshot to its own session rather than
	// trusting the tunnel order. 0 when the visor could not name it.
	// AuditionMS is how long this tunnel has existed. For a STANDBY tunnel it
	// is its audition age: how long the pool has held it open, pinged and
	// measured it without putting a stream on it.
	AuditionMS float64 `json:"audition_ms,omitempty"`
	LocalPort  uint16  `json:"local_port,omitempty"`
	// RemotePort is the route group's FAR-END port. For a leg reserve it is the
	// one name the reserve has (its local port is shared with the tunnel it was
	// split out of): the app adopts a reserve by it (DialOptions.AdoptReservePort).
	RemotePort uint16 `json:"remote_port,omitempty"`
	// OpenStreams is this tunnel's yamux session's current open-stream count
	// (Session.NumStreams), overlaid by the skysocks-client from its own live
	// session — the visor-built base above has no yamux session to read one
	// from. 0 for a standby tunnel (it carries nothing) and for anything the
	// overlay could not match to a live session (LocalPort unknown/0).
	OpenStreams int `json:"open_streams"`
}