router

type BatchSavings struct {
	Routes    int
	Issued    int
	Coalesced int
}

type CandidateInfo struct {
	// Hops is the ordered intermediate PKs (hex) from source
	// (excluded) to destination (excluded). Empty for a direct
	// transport.
	Hops []string

	// EstLatencyMs is the sum of per-hop latencies along the
	// route, in milliseconds, drawn from the router's existing
	// transport-tracker lookup. Zero when no measurements are
	// available — treat as "unknown," not "fast."
	EstLatencyMs int
}

type CapabilitiesArgs struct{}

type CapabilitiesReply struct {
	Caps []string `json:"caps"`
}

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

type CascadeConfig struct {
	// ReserveTimeout is the per-hop timeout for the reserve phase.
	ReserveTimeout time.Duration `json:"reserve_timeout,omitempty"`
	// InstallTimeout is the per-hop timeout for the install phase.
	InstallTimeout time.Duration `json:"install_timeout,omitempty"`
	// SessionTTL is how long to keep session state between phases.
	SessionTTL time.Duration `json:"session_ttl,omitempty"`
}

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

type CascadeSignInstallArgs struct {
	Route        routing.BidirectionalRoute
	FwdSessionID uint64
	RevSessionID uint64
	FwdRouteIDs  []routing.RouteID
	RevRouteIDs  []routing.RouteID
}

type CascadeSignInstallReply struct {
	FwdInstallBytes []byte
	RevInstallBytes []byte
	InitEdge        routing.EdgeRules
}

type CascadeSignReserveArgs struct {
	Route routing.BidirectionalRoute
}

type CascadeSignReserveReply struct {
	FwdSessionID    uint64
	FwdReserveBytes []byte
	RevSessionID    uint64
	RevReserveBytes []byte
}

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

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

type Config struct {
	Logger           *logging.Logger
	MasterLogger     *logging.MasterLogger
	PubKey           cipher.PubKey
	SecKey           cipher.SecKey
	TransportManager *transport.Manager
	RouteFinder      rfclient.Client
	// PreferLocalRouteTo, when set and true for dst, tries the local route
	// calculation (this visor's transports plus the transport-discovery
	// snapshot, which includes any local graph source) before the route
	// finder is asked. A hypervisor sets it for its attached visors.
	PreferLocalRouteTo func(dst cipher.PubKey) bool
	RouteGroupDialer   RouteGroupDialer
	SetupNodes         []cipher.PubKey
	RulesGCInterval    time.Duration
	MinHops            uint16
	MaxHops            uint16
	// ExcludeTransportTypes hard-excludes routes traversing any of these transport
	// types from the candidate set (see visorconfig.Routing.RouteExcludeTransportTypes).
	// Empty = nothing excluded. Lowercased type names.
	ExcludeTransportTypes []string
	// NoTransit refuses every request to act as an intermediate hop on another
	// visor's route (visorconfig.Routing.NoTransit). Routes that originate or
	// terminate here are unaffected.
	NoTransit bool
	// DisableRaceRouteSetup turns OFF the app-dial race (default: race ON).
	// Normally, when a dial would create a direct transport to the peer
	// (min-hops==1, not existing-tp-only), DialRoutes runs that transport
	// creation in the BACKGROUND and concurrently tries to route over EXISTING
	// transports — returning as soon as either lands, instead of blocking on the
	// (~20s worst-case) transport dial first. Set true to restore the legacy
	// synchronous behavior (create-transport-then-route) as a safety valve.
	DisableRaceRouteSetup bool
	// ParallelRouteSetup is the number of candidate route groups whose
	// reciprocal-handshake setup DialRoutes races CONCURRENTLY per dial
	// attempt (top-K candidates the route-finder returned, ranked by
	// latency/suspect-liveness). The FIRST candidate to complete its
	// handshake WINS and immediately becomes the working route — the dial
	// returns on it without waiting for a "better" one; the losers are
	// canceled and torn down. This collapses establishment from "up to
	// N×handshakeAwaitTimeout" (the old one-candidate-at-a-time retry loop,
	// where every dead / non-forwarding candidate burned the full ~10s
	// handshake await before the next was tried — up to the ~90s dial ceiling,
	// leaving the app wedged in "starting") down to roughly one RTT. A dead-hop
	// candidate simply loses the race instead of blocking the whole dial, so
	// the app converges to a working route (single multihop at min_hops>=2,
	// or direct at min_hops==1) instead of wedging.
	//
	// 1 = strictly-sequential behavior (a clean rollback switch). 0 (unset)
	// is normalized to defaultParallelRouteSetup by SetDefaults; values above
	// maxParallelRouteSetup are clamped. Losing / failed candidates' intermediate
	// hops are marked suspect for a short TTL so the NEXT dial front-loads
	// known-good hops (see suspectHopCache; composes with #4063).
	ParallelRouteSetup int
	// AwaitSetupListener, if non-nil, is used instead of opening a fresh
	// listener on DmsgAwaitSetupPort. This lets callers reserve the port
	// earlier in init (before the transport manager is ready) so peers
	// dialing it during the router-init window don't hit "request has no
	// associated listener" warnings.
	AwaitSetupListener *dmsg.Listener
	// AppLookup, if set, resolves a routing.Port to the originating
	// app name. Used to tag rg-scoped log entries with app_name=<n>
	// so 'cli proxy start --verbose' can scope to a session. nil
	// means no lookup is performed and entries are emitted untagged
	// (the existing behavior).
	AppLookup func(routing.Port) (string, bool)

	// DialHook, when non-nil, is invoked before each DialRoutes
	// to let an operator-supplied routing policy adjust the
	// per-dial knobs (MuxRoutes, MinHops) or refuse the dial
	// entirely. See pkg/router/dial_hook.go for the contract and
	// pkg/router/policy/ for the Starlark-backed implementation
	// the visor wires up when conf.Routing.PolicyPerDial is set.
	//
	// When nil (the default) DialRoutes behaves identically to
	// its pre-integration shape — zero-cost when no policy is
	// configured.
	DialHook DialHook

	// PolicyOnControlPorts opts the routing policy (DialHook) BACK IN for
	// control-plane destination ports (pty, dmsgctrl, setup, hypervisor RPC,
	// …). Default false: those small noise-XK control channels bypass the
	// policy entirely and take a plain base route, because its per-dial
	// evaluation + warm-standby/reshape churn destabilizes their handshakes
	// (the pty 32-leg-mux footgun). Set true to let the operator's policy
	// manage control-plane routes too (advanced; e.g. a policy purpose-built
	// for them). See effectiveDialHook / controlPlanePorts.
	PolicyOnControlPorts bool

	// MuxFEC advertises CapFEC on mux route groups so repair frames are
	// striped alongside data (off by default; see visorconfig Routing.MuxFEC).
	MuxFEC bool

	// ExcludeSameLANHops, when true (the default the visor wires from
	// routing.exclude_same_lan_hops), makes route calculation drop candidate
	// INTERMEDIATE hops that sit on this visor's own local network — a peer
	// reached over a private/RFC1918 endpoint, or (the NAT-hairpin case) a peer
	// reached at this visor's own public IP or its /24. Routing a remote-
	// destination path through a same-LAN peer adds a hop but no path diversity
	// (same first-mile link, NAT and failure domain) and can fold the path back
	// onto the source network; for a mux it also starves genuinely-diverse aux
	// legs because the same-LAN peer wins on latency and is re-picked every
	// rotation. Same-LAN peers remain fully usable as direct dial DESTINATIONS —
	// only their use as intermediates is suppressed. The exclusion is computed
	// from live transports via TransportManager.SameLANPeers(SelfPublicIP()).
	ExcludeSameLANHops bool
	// SelfPublicIP returns this visor's current public IP (from STUN), or nil
	// when not yet known. Used only by the ExcludeSameLANHops filter to catch
	// the NAT-hairpin case (a same-LAN peer reached at our own public IP). nil
	// getter or nil result is fine — the private-IP and local-interface /24
	// checks still apply.
	SelfPublicIP func() net.IP
}

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

type DatagramCipherConfig struct {
	TimeLimit   time.Duration
	PacketLimit uint64
}

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

type DialAdjustment struct {
	// MuxRoutes, when > 0, overrides DialOptions.MuxRoutes for
	// this dial.
	MuxRoutes int

	// ForwardMuxRoutes and ReverseMuxRoutes are per-direction
	// overrides for asymmetric mux. Zero falls back to MuxRoutes.
	// Used by policies that want different upstream / downstream
	// fan-out (e.g. ForwardMuxRoutes=1 + ReverseMuxRoutes=4 for
	// a download-heavy workload).
	ForwardMuxRoutes int
	ReverseMuxRoutes int

	// MinHops, when > 0, overrides DialOptions.MinHops for this
	// dial.
	MinHops int

	// ForwardMinHops and ReverseMinHops are per-direction
	// overrides for MinHops. Zero falls back to MinHops.
	ForwardMinHops int
	ReverseMinHops int

	// Fallback drives the no-overlay paths:
	//   "drop"   — refuse the dial with ErrDialPolicyDropped.
	//   "direct" — skip the route-finder, force the direct-
	//              transport short-circuit (UseExistingTpOnly=true
	//              + MinHops=1). If no direct transport exists,
	//              DialRoutes still fails — the script gets the
	//              all-or-nothing semantic it asked for.
	// Any other value is ignored (the dial proceeds normally).
	Fallback string

	// Distribution, when Mode != DistributionUnset, overrides
	// the route group's mux distribution strategy (which by
	// default tracks the router's visor-wide muxMode). The
	// policy layer parses the operator's descriptor string
	// (Starlark RouteSpec.Distribution) into this struct so
	// the router stays free of parser logic.
	Distribution DistributionConfig

	// RotationIntervalSeconds, when > 0, configures the route
	// group's rotation servicePacketLoop to fire OnTick every N
	// seconds. The hook gets the current leg snapshot and
	// returns a RotationAction (drop legs / add leg / no-op),
	// which the route group applies. Zero (default) disables
	// rotation. Set by policies that want continuous bandwidth-
	// spreading rotation across the eligible-peer set.
	RotationIntervalSeconds int

	// AvoidDirect, when true, makes the direct-dial fast path
	// (VStreamMux / sky_forward_conn) skip the direct transport
	// even when one exists — the dial falls through to the
	// overlay route-setup path, which is what makes mux /
	// min_hops / rotation policies meaningful.
	//
	// Set by the policy layer implicitly when the script returned
	// MinHops / ForwardMinHops / ReverseMinHops >= 2 — `min_hops=2`
	// already says "no direct" (direct is 0 intermediates), and
	// the alternative would be a separate avoid_direct knob that
	// duplicates the same intent. The direct-dial bridge in
	// wireDirectDialPolicyHook surfaces ErrPolicyAvoidDirect when
	// this is true; the caller (skywire_networker.tryDirectDial)
	// treats that as a normal direct-dial failure and falls
	// through to route setup.
	AvoidDirect bool
}

type DialError struct {
	PK  cipher.PubKey
	Err error
}

type DialHook interface {
	// BeforeDial is invoked synchronously before route setup. Its
	// return value adjusts the dial's opts in-place. Returning the
	// zero DialAdjustment + nil error means "no override; proceed
	// with the caller's opts unchanged."
	//
	// Implementations MUST return quickly — DialRoutes blocks on
	// this call before the route-finder query begins. Budget is
	// the same as the policy's per-call timeout (default 50ms).
	BeforeDial(ctx context.Context, info DialInfo) (DialAdjustment, error)
}

type DialInfo struct {
	AppName string
	PeerPK  cipher.PubKey
	LPort   routing.Port
	RPort   routing.Port

	// CLIOverrides surfaces any DialOptions values the caller
	// (CLI / app) populated before BeforeDial fires, so the
	// script can honor or override them. Keys mirror DialOptions
	// field names in snake_case (mux_routes, min_hops,
	// forward_mux_routes, etc.). Only non-zero values appear.
	// The policy's adjustment runs AFTER this is captured, so
	// the script gets a true "what did the operator pass" view.
	CLIOverrides map[string]string

	// IsDirectDial is true when the hook is being invoked from
	// the sky_forward_conn / VStreamMux direct-dial path (the
	// short-circuit that uses an existing direct transport
	// instead of going through the route-finder). False for the
	// overlay paths (DialRoutes, PingRoute). Lets scripts apply
	// killswitch-style rules to direct dials too (e.g.
	// "vpn-client must never dial direct over dmsg"). Surfaced
	// as `ctx.is_direct_dial` in Starlark.
	IsDirectDial bool

	// TransportKind is the network type ("stcpr"/"sudph"/"stcp"/
	// "dmsg") of the transport the direct dial would use.
	// Populated only when IsDirectDial is true. Empty for
	// overlay dials. Surfaced as `ctx.transport_kind` so a
	// script can branch on the kind even before the overlay's
	// candidates are available.
	TransportKind string
}

type DialOptions struct {
	MinForwardRts         int
	MaxForwardRts         int
	MinConsumeRts         int
	MaxConsumeRts         int
	Retries               int
	UseExistingTpOnly     bool          // If true, only use routes through existing transports, don't create new ones
	EnsureDirectTransport bool          // If true, create a direct transport to the destination if none exists, then dial direct-only (the `--direct` foot-gun fix). Implies a 1-hop, route-finder-bypassing dial that self-heals when the transport drops.
	TransportID           uuid.UUID     // If set, use this specific transport (skips route calculation for direct transports)
	ForwardHops           []routing.Hop // If set, use these hops for forward path (skips route calculation)
	ReverseHops           []routing.Hop // If set, use these hops for reverse path (skips route calculation)
	MuxRoutes             int           // Number of parallel routes to establish (0 or 1 = single route, >1 = mux)
	ExcludeTransportIDs   []uuid.UUID   // Transport IDs to exclude from route calculation (for mux)
	// ExcludeRemoteTransportIDs is the DESTINATION-side analog of
	// ExcludeTransportIDs: transport IDs the REVERSE path must not leave the
	// destination over.
	//
	// Why it exists: the setup node hands the destination `respEdge.Forward`,
	// which is the ForwardRule generated for the REVERSE route's first hop
	// (setupnode.go GenerateRules — fwdRules is keyed by each route's
	// Hops[0].From, and the reverse route starts at the destination). So the
	// destination's route group registers one transport per leg, and that
	// transport is exactly `Reverse[0].TpID` of the plan the initiator dialed.
	// appendRouteToGroup then refuses any leg whose transport is already in
	// that set ("refusing to append mux leg over transport %s already in the
	// group"), because two legs over one link break the mux data plane (#3954).
	//
	// The forward and reverse paths are ranked INDEPENDENTLY (pickDisjointPath),
	// and a 0-intermediate direct reverse carries no intermediates to exclude —
	// so ExcludeIntermediatePKs cannot keep a new leg's reverse off the direct
	// transport the destination is already using for the primary leg. Without
	// this field every aux mux leg to such a destination is planned, dialed
	// through the setup node (full ID reservation + intermediary rule install)
	// and then refused: the churn measured on the live setup nodes.
	//
	// Populated by the aux-mux-leg planners from the group's live legs
	// (RouteGroup.remoteLegTransportIDs). Unset for every non-mux dial, which
	// is therefore byte-identical to before.
	ExcludeRemoteTransportIDs []uuid.UUID
	// ExcludeFirstHopPeers / ExcludeFirstHopIPs are the diversify dial's
	// PEER-level first-hop exclusion: the remote visor PKs (and, where the
	// underlying transport exposes one, the remote IPs) that a sibling tunnel to
	// the same exit already leaves over.
	//
	// ExcludeTransportIDs alone is not enough, because one peer commonly answers
	// on SEVERAL transports: this visor holds an stcpr, a squicr and a sudph
	// transport to the same exit host. Excluding only the sibling's transport ID
	// left the other two as "free first hops", and a diversify dial took the
	// squicr twin — same host, same NIC, same physical path — so the two tunnels
	// shared one link and split it instead of summing (measured 2026-09-17: 50 MB
	// up 2.57 MB/s, down 5.64 on a 29/21 MB split, against 8.36-8.49 down on two
	// genuinely disjoint routes). Excluding the PEER makes every transport to
	// that peer unavailable, so the candidates are the other intermediates — the
	// disjointness the RFC promises.
	//
	// The IP list catches the same host reached under a different PK. Like the
	// transport-ID exclusion these are a soft preference: a dial that can find
	// nothing else still falls back to a shared first hop rather than failing.
	ExcludeFirstHopPeers []cipher.PubKey
	ExcludeFirstHopIPs   []string
	// Datagram, when true, asks the dial to build a faithful-UDP
	// DatagramRouteGroup sibling over the established route (#2607).
	// The route's reliable RouteGroup is still set up exactly as
	// usual (and is what carries the one-time Noise handshake whose
	// ChannelBinding keys the datagram AEAD); the datagram sibling is
	// built alongside it once the handshake completes. The accept
	// side opts in independently via RegisterDatagramPort — both ends
	// must locally intend datagram mode for it to work.
	Datagram bool
	// MinHops, when > 0, is the per-call minimum hop count constraint.
	// Overrides Config.MinHops for this dial only — needed by callers
	// that want a non-direct path even when the visor's global
	// min_hops is 1 (e.g. `cli visor ping mux-bw --min-hops 2`, which
	// must force every dial through an intermediate to test the
	// "mux via intermediates > direct" bandwidth hypothesis without
	// requiring the operator to bump visor-global config).
	//
	// Setting MinHops >= 2 also suppresses the direct-transport
	// fast path inside DialRoutes (the existing
	// "if r.isTpdExist(rPK) { MinHops = 1 }" downgrade is skipped),
	// since the caller has explicitly asked NOT to use direct.
	//
	// 0 = inherit Config.MinHops (legacy / single-route callers).
	MinHops int
	// ExcludeIntermediatePKs lists intermediate-visor PKs that route-
	// finder paths must NOT contain. Source + destination are never
	// excluded (they're endpoints, not intermediates). The mux loop
	// populates this with the intermediates of routes already
	// established so that subsequent routes are constructed through
	// different intermediate paths — disjoint in the intermediate-PK
	// set sense. Applied in both the HTTP route-finder path (post-
	// filter response) and the local route-calc fallback (filter
	// candidates).
	//
	// Disjoint-intermediate routing is AUTOMATIC for the mux loop
	// (MuxRoutes > 1). Callers that want overlapping intermediates
	// must dial with explicit ForwardHops/ReverseHops (which bypass
	// the route-finder entirely). This field is also exposed so
	// callers outside the mux loop can pre-populate exclusions if
	// they have constraints to express.
	ExcludeIntermediatePKs []cipher.PubKey
	ExcludeDMSG            bool // Exclude DMSG transports (for mux — DMSG is a relay, not suitable for multiplexing)
	// DiversifyTransports opts this dial into visor-side auto-
	// diversification for bandwidth aggregation (docs/mux_aggregation_rfc.md
	// step 3). When set, DialRoutes looks up THIS visor's currently-live
	// route groups to the SAME destination PK:port and seeds
	// ExcludeTransportIDs / ExcludeIntermediatePKs with their first-hop
	// transports + intermediates, so a new tunnel to an exit leaves over a
	// DIFFERENT first-hop transport than the tunnels already established to
	// it — their throughputs then SUM instead of splitting one link.
	//
	// It is bounded and safe by construction: the exclusions are added ONLY
	// when >= 1 sibling route group to the exact same dst already exists (the
	// skysocks multi-tunnel "tunnel 2..N" case). A lone dial (tunnel 1, or
	// any app that dials a dst once) finds no sibling and is byte-identical
	// to today. It reuses the mux's own disjoint machinery, but across route
	// groups rather than across legs within one group. Set by the
	// skysocks-client for its extra tunnels; unset everywhere else, so
	// single-dials, control-plane forwards and same-LAN/direct dials are
	// untouched. Falls back gracefully — if no disjoint transport is free the
	// dial proceeds on a shared path (a shared tunnel beats no tunnel).
	DiversifyTransports bool
	// RequireDisjointFirstHop turns the diversify PREFERENCE above into a
	// REQUIREMENT: rather than conceding a shared first hop when nothing
	// disjoint is free, the dial fails with ErrNoDisjointFirstHop. Only
	// meaningful together with DiversifyTransports (without siblings there is
	// nothing to be disjoint from, and the dial proceeds as usual).
	//
	// It exists so a caller that is GROWING a pool of sibling tunnels can tell
	// "the topology has more disjoint paths to offer" from "it has none left".
	// The skysocks standby pool dials with it set and stops filling on the
	// first ErrNoDisjointFirstHop — the tunnel-level twin of the mux's
	// "no disjoint path available right now; settling at current degree".
	// A shared extra tunnel aggregates nothing, so for that caller a shared
	// path is not a lesser success but a wrong answer.
	RequireDisjointFirstHop bool
	// TunnelRole records what the DIALER intends this route group to be:
	// "active" (it carries streams) or "standby" (it is held open, measured
	// and ready to take over). Set by the skysocks client; empty everywhere
	// else, and empty is the only value a non-tunnel route group ever has.
	// Surfaced as MuxInfo.TunnelRole. It is the dialing end's own label — the
	// accepting end (the exit) has no idea which of its peers' tunnels are in
	// standby, so this field is always empty there.
	TunnelRole string
	// AdoptReservePort, when set, turns the dial into an ADOPTION: instead of
	// setting up a new route, DialRoutes takes the leg reserve (a split's
	// standalone group, leg_split.go) toward the same peer whose far-end port
	// is this one, re-points its chain at the dial's own descriptor and runs
	// the ordinary handshake on it (leg_adopt.go). It fails — and the caller
	// dials the usual way — when no such reserve exists or the peer does not
	// answer. 0 = an ordinary dial.
	AdoptReservePort routing.Port

	// Distribution overrides the route group's per-packet
	// distribution strategy when set (Mode != DistributionUnset).
	// Populated either by a routing-policy script (see
	// DialAdjustment.Distribution) or directly by a CLI caller
	// constructing DialOptions. Zero-value means "use the
	// router's visor-wide muxMode default."
	Distribution DistributionConfig
	KeepAlive    time.Duration // Route keepalive (0 = DefaultRouteKeepAlive). Routes idle longer expire.
	// ParallelRouteSetup, when > 0, overrides Config.ParallelRouteSetup
	// for this dial only — the number of candidate route groups whose
	// setup is raced concurrently (first to complete its handshake wins).
	// 1 forces sequential setup for this dial; 0 inherits the visor
	// config. See Config.ParallelRouteSetup.
	ParallelRouteSetup int
	// AppName is the originating app's name. Set by appnet's
	// DialContextWithOptions when the caller threaded a context
	// carrying it (RPCIngressGateway.Dial uses appnet.WithAppName).
	// router-side: scopedLog prefers this over AppLookup-by-port,
	// since DialRoutes is invoked with an ephemeral source port that
	// isn't the app's registered SetAppPort value.
	AppName string

	// ForwardMinHops / ReverseMinHops are per-direction overrides for
	// MinHops. When > 0 they take precedence over the symmetric
	// MinHops field for THAT direction only. Use case: bandwidth-
	// asymmetric workloads (HTTP GET = tiny upstream, bulk downstream)
	// where the user wants e.g. direct stcpr for the forward leg but
	// multi-hop for the reverse-direction bulk payload.
	//
	// 0 (the default) means "inherit MinHops" — back-compat for
	// callers that only care about symmetric routes.
	//
	// Resolution at use site (see resolveDirMinHops): if the per-
	// direction override is > 0 it wins; else MinHops; else
	// Config.MinHops; else the global default.
	ForwardMinHops int
	ReverseMinHops int

	// ForwardMuxRoutes / ReverseMuxRoutes are per-direction overrides
	// for MuxRoutes. When > 1 they take precedence over the symmetric
	// MuxRoutes field for THAT direction's route count.
	//
	// Use case: the operator's "direct upstream + multi-hop downstream"
	// test — set ForwardMuxRoutes=1 and ReverseMuxRoutes=4 to open a
	// single forward leg (the GET request rides one TCP socket) while
	// the reverse direction aggregates the bulk payload across 4
	// multi-hop legs. The data plane already supports rg.fwd[] and
	// rg.rvs[] being different lengths (the read path is by route-id
	// lookup, not slice index), so this is purely a setup-side change.
	//
	// 0 (the default) means "inherit MuxRoutes" for that direction.
	// When the caller wants strictly N=1 on a side they should set it
	// to 1 explicitly (not 0) since 0 still falls through to MuxRoutes.
	ForwardMuxRoutes int
	ReverseMuxRoutes int

	// RotationIntervalSeconds, when > 0, instructs the route group
	// to fire its rotation hook every N seconds after setup. The
	// hook can drop legs and/or add new ones, enabling bandwidth-
	// spreading policies that rotate across the eligible-peer set.
	// Populated by the policy layer (DialAdjustment) from
	// RouteSpec.RotationIntervalSeconds; zero = no rotation.
	RotationIntervalSeconds int
	// contains filtered or unexported fields
}

type DistributionConfig struct {
	// Mode selects the per-packet algorithm. DistributionUnset
	// means "no override."
	Mode DistributionMode

	// Weights are the operator-supplied fractional weights for
	// DistributionWeighted. Must be the same length as the route
	// group's leg count; values are normalized into an integer
	// schedule by the selector. Empty for non-weighted modes.
	Weights []float64

	// SizeThreshold is the payload-size boundary for
	// DistributionSizeThreshold. Packets larger than this go to
	// leg 0 (assumed to be the wider pipe — the first leg the
	// route-finder returned, ranked by latency); smaller packets
	// round-robin across the remaining legs.
	SizeThreshold int

	// DSCPThreshold is the IPv4 DSCP boundary for
	// DistributionDSCPPriority. Packets with DSCP >= this value
	// take leg 0; others round-robin across the rest. Common
	// values: 0x2E (EF — VoIP), 0x10 (AF — interactive).
	DSCPThreshold int
}

type DistributionMode int

type DstTransportOracle interface {
	DstTransports(ctx context.Context, src, dst cipher.PubKey) ([]*transport.Entry, error)
}

type EmbeddedSetupNode interface {
	// CreateRouteGroup creates a route group using the embedded setup-node's dmsg client.
	CreateRouteGroup(ctx context.Context, biRt routing.BidirectionalRoute) (routing.EdgeRules, error)
	// PK returns the public key of the embedded setup-node.
	PK() cipher.PubKey
	// DmsgClient returns the dmsg client used by the embedded setup-node.
	DmsgClient() *dmsg.Client
}

type ForwardQueue struct {
	TpID     uuid.UUID     `json:"tp_id"`
	TpType   string        `json:"tp_type,omitempty"`
	Remote   cipher.PubKey `json:"remote_pk,omitempty"`
	Queue    int           `json:"queue"`
	Capacity int           `json:"capacity"`
	// QueuedBytes is what the frames waiting in it currently hold, against
	// forward.queue_bytes when that bound is set.
	QueuedBytes int64  `json:"queued_bytes"`
	Sent        uint64 `json:"sent"`
	// The named drop reasons, one counter each.
	DropsQueueFull    uint64 `json:"forward_drop_queue_full"`
	DropsWriteTimeout uint64 `json:"forward_drop_write_timeout"`
	DropsWriteError   uint64 `json:"forward_drop_write_error"`
}

type Group interface {
	Close() error
	LocalAddr() net.Addr
	RemoteAddr() net.Addr
	IsAlive() bool
}

type HealthCheckArgs struct{}

type HealthCheckReply struct {
	Status string `json:"status"`
	// Caps lists the request shapes this node understands, the same list the
	// Capabilities RPC returns — carried here too so a health probe doubles as
	// the negotiation for a client that is already making one.
	Caps    []string `json:"caps,omitempty"`
	Version string   `json:"version,omitempty"`
	Commit  string   `json:"commit,omitempty"`
	Date    string   `json:"date,omitempty"`
}

type IDReserver interface {
	io.Closer
	fmt.Stringer

	// ReserveIDs reserves route IDs from the router clients.
	// It uses an internal map to know how many ids to reserve from each router.
	ReserveIDs(ctx context.Context) error

	// PopID pops a reserved route ID from the ID stack of the given public key.
	PopID(pk cipher.PubKey) (routing.RouteID, bool)

	// TotalIDs returns the total number of route IDs we have reserved from the routers.
	TotalIDs() int

	// Client returns a router client of given public key.
	Client(pk cipher.PubKey) *Client

	// ReturnToPool returns connections to a pool instead of closing them.
	ReturnToPool(pool *ClientPool)
}

type IntakeStats struct {
	// UnknownPacketTypes counts packets dropped as ErrUnknownPacketType, by
	// type name. Non-zero means a peer sends a type this build does not
	// route, or a transport lost its route-ID-0 handler (#4725).
	UnknownPacketTypes map[string]int64 `json:"unknown_packet_types,omitempty"`
	// ControlPlaneToRouter counts route-ID-0 control packets that reached
	// the router instead of being intercepted on the transport, by type.
	ControlPlaneToRouter map[string]int64 `json:"control_plane_to_router,omitempty"`
	// StaleRouteDrops counts frames for rules that no longer exist (normal
	// during teardown; a climbing count on an idle visor is not).
	StaleRouteDrops int64 `json:"stale_route_drops"`
	// RouteGroupQueues is the two inbound queues of every active route group:
	// the app queue (queue/capacity) and the intake queue between the router's
	// shared read loop and the group's own worker (intake_*).
	//
	// An app queue at capacity is an app that stopped reading. That used to
	// block the shared loop — up to 30 s per packet, stalling every transport
	// on the visor; now it backs up into that group's intake queue instead,
	// and a climbing intake_drops is where the loss shows up. Non-zero
	// intake_drops on one group and healthy transfers elsewhere is the
	// expected shape of a single wedged app.
	RouteGroupQueues []RouteGroupQueue `json:"route_group_queues,omitempty"`
	// ForwardQueues is the TRANSIT write side: one entry per next-hop
	// transport this visor is relaying frames to. Non-zero drops name a peer
	// that stopped draining; they used to be a visor-wide freeze instead
	// (see router_forward.go).
	ForwardQueues []ForwardQueue `json:"forward_queues,omitempty"`
}

type LegChange struct {
	Event    string
	LegIndex int
}

type LegChangeHook interface {
	OnLegChange(info DialInfo, legs []LegInfo, change LegChange) DistributionConfig
}

type LegInfo struct {
	Index int
	Kind  string
	// TransportID is the leg transport's stable UUID
	// (ManagedTransport.Entry.ID) as a string. Unlike Index — which
	// shifts when legs are dropped/added and the tps[] slice compacts
	// — TransportID identifies the same underlying transport across
	// ticks, so an on_tick policy can key per-leg state (e.g. an EWMA
	// of latency) by it and smooth signals over time. Empty for a nil
	// leg slot.
	TransportID string
	LatencyMs   int
	Alive       bool
	// Standby is true when the leg is a WARM STANDBY: rules installed and
	// kept alive, but not selected for sending. Lets an on_tick policy see the
	// current gate state so it can promote a warm spare instead of a cold add,
	// or demote a leg it wants to keep warm. See docs/warm_standby_legs_rfc.md.
	Standby bool
	// Direct is true when this leg is the DIRECT (forward-only) leg of a
	// UNIDIRECTIONAL route group: its transport goes straight to a route-group
	// endpoint (1 hop, no intermediary) and it carries only the forward/upload
	// direction. Sourced from routeMux.legIsDirectTp, which is false for a
	// non-directional (symmetric) group — there every leg carries both
	// directions. Lets the adaptive on_tick maintain a floor of active REVERSE
	// (download) legs independent of the direct leg, so a download never falls
	// back onto warm-standby legs for want of an active reverse path.
	Direct bool
	// Flipped is the route group's current unidirectional flip state (the same
	// value on every leg of the group), sourced from routeMux.dirState. Because a
	// leg's send-side direction is an ASSIGNMENT the flip controller can swap —
	// not an intrinsic property — the download-direction class is Direct ==
	// Flipped (unflipped: download rides the multihop legs; flipped: it rides the
	// direct leg). The adaptive on_tick keeps its active-download floor on that
	// class, whichever way the flip currently sits. Always false for a
	// non-directional (symmetric) group.
	Flipped bool
	// SentBytes / RecvBytes are the leg transport's cumulative
	// payload-byte counters (ManagedTransport.GetBandwidth). Lets a
	// policy's on_tick rotate a leg after it carries a byte threshold
	// rather than purely on elapsed time.
	SentBytes uint64
	RecvBytes uint64
	// Retransmits is how many SACK retransmit packets this leg has carried.
	// A high retransmits-to-traffic ratio marks a lossy leg, letting an
	// on_tick policy shed lossy intermediates (not just slow ones).
	Retransmits uint64
	// Hops is the intermediate-PK chain this leg traverses (forward,
	// src->dst, endpoints excluded). Lets on_tick build a precise
	// ExcludeHops set so a rotated-in leg avoids the rotated-out leg's
	// intermediates. Empty for a direct (0-intermediate) leg.
	Hops []string
}

type LegStats struct {
	// Index in the rg's tps[] slice. Stable for the rg's lifetime
	// (transports are appended, never re-ordered) so the index is
	// also a stable identifier for runtime add/remove operations.
	Index int
	// SentBytes / SentPackets are what THIS leg carried outbound.
	SentBytes   uint64
	SentPackets uint64
	// RecvBytes / RecvPackets are what THIS leg carried inbound.
	// Resolved from the reverse-rule's KeyRouteID at packet-handle
	// time, so it reflects what actually arrived on this transport,
	// not what the peer said it sent.
	RecvBytes   uint64
	RecvPackets uint64
	// PayloadBytes is the UNIQUE in-order payload this leg delivered (each seq
	// counted once, on the leg it first arrived on) — retransmits/duplicates
	// excluded, so the per-leg values sum to the transfer size and give a
	// confound-free per-direction attribution (which legs carried the download vs
	// the upload), unlike RecvBytes which includes retransmit/duplicate inflation.
	PayloadBytes uint64
	// DupBytes is inbound DUPLICATE data this leg carried (seqs already
	// delivered/buffered on arrival) — the peer's spurious-retransmit waste,
	// which selectFastestTransport concentrates on the fastest leg. RepairBytes
	// is inbound FEC repair frames (deliberate overhead). Together with
	// PayloadBytes they decompose RecvBytes so "why is this (standby) leg
	// receiving" is answerable from telemetry.
	DupBytes    uint64
	RepairBytes uint64
	// Retransmits is how many SACK retransmit packets THIS leg has
	// carried. A high retransmits:sentPackets ratio marks a lossy leg —
	// the signal a routing policy needs to shed lossy intermediates and
	// the scheduler needs to deweight them.
	Retransmits uint64
	// GoodputUpBps / GoodputDownBps are this leg's recent goodput split by
	// direction — the EWMA of the SENT (up) and RECV (down) byte deltas per
	// second over the telemetry refresh window (~1s for the status page).
	// Distinct from the cumulative SentBytes/RecvBytes counters above: they
	// are the RATE each direction is moving now, not the lifetime total. 0
	// until a second sample lands. Sampled in snapshotLegs.
	GoodputUpBps   float64
	GoodputDownBps float64
	// GoodputBps is the combined (up+down) recent goodput, retained as the
	// sum of GoodputUpBps+GoodputDownBps for back-compat with callers that
	// want a single figure.
	GoodputBps float64
}

type LegWeight struct {
	TransportID string  `json:"transport_id"`
	Weight      float64 `json:"weight"`
}

type Map map[cipher.PubKey]*Client

type MockIDReserver struct {
	mock.Mock
}

type MockRouteGroupDialer struct {
	mock.Mock
}

type MockRouter struct {
	mock.Mock
	// contains filtered or unexported fields
}

type MuxCounters struct {
	// TunnelPromotions counts standby-tunnel promotions to active (a pool
	// tunnel flip) — every MuxEventTunnelPromoted recorded by noteTunnelEvent.
	TunnelPromotions uint64 `json:"tunnel_promotions"`
	// LegRehomesSent/Acked count this visor's OWN outbound leg re-homes
	// (leg_rehome.go rehomeChain): Sent when the request lands on the wire,
	// Acked when the peer's ack completes the in-place move. LegRehomesFailed
	// adds the initiator's own timeout/refusal outcomes to the acceptor's
	// refusals counted below — it does not cover a failure AFTER a peer's ack
	// (adopting the leg locally), which is rarer and separately logged as a
	// MuxEvent. LegRehomesReceived counts an incoming re-home REQUEST this
	// visor accepted or refused (leg_rehome.go acceptRehome).
	LegRehomesSent     uint64 `json:"leg_rehomes_sent"`
	LegRehomesReceived uint64 `json:"leg_rehomes_received"`
	LegRehomesAcked    uint64 `json:"leg_rehomes_acked"`
	LegRehomesFailed   uint64 `json:"leg_rehomes_failed"`
	// LegSplitsSent/Received/Acked/Failed count the REVERSE move
	// (leg_split.go): a leg handed back OUT of a group into a standalone
	// standby group of its own, instead of its transport being closed.
	// Sent/Acked/Failed are this visor's own outbound splits, Received an
	// incoming split request it accepted or refused.
	// LegRehomesForwarded/LegSplitsForwarded count re-home and split control
	// frames this visor RELAYED as an intermediate hop (router_packet.go
	// forwardPacket). They are what makes a transited re-home observable at all:
	// on the initiator a chain through a relay that does not forward the type is
	// indistinguishable from an exit that refused, and the relay itself had no
	// tally of its own. A sent-but-never-acked re-home whose first hop reports 0
	// here died at that hop.
	LegRehomesForwarded uint64 `json:"leg_rehomes_forwarded"`
	LegSplitsForwarded  uint64 `json:"leg_splits_forwarded"`
	// LegControlsInBandSent/LegControlsInBand count the IN-BAND leg control
	// frames (mux_control_frame.go) this visor sent and received: the re-home
	// and split messages carried inside a DataPacket, which every relay
	// forwards whatever it runs. A re-home that is sent but never acked with
	// these rising on both edges is an exit that refused, not a hop that
	// dropped the control frame.
	LegControlsInBandSent uint64 `json:"leg_controls_inband_sent"`
	LegControlsInBand     uint64 `json:"leg_controls_inband_received"`
	LegSplitsSent         uint64 `json:"leg_splits_sent"`
	LegSplitsReceived     uint64 `json:"leg_splits_received"`
	LegSplitsAcked        uint64 `json:"leg_splits_acked"`
	LegSplitsFailed       uint64 `json:"leg_splits_failed"`
	// ForwardFanoutEngaged/Released count noteForwardFanout(on=true/false):
	// the forward direction's fan-out-under-load latch (unidir.go) turning on
	// (MuxEventForwardFanout) or off (MuxEventForwardConfined).
	ForwardFanoutEngaged  uint64 `json:"forward_fanout_engaged"`
	ForwardFanoutReleased uint64 `json:"forward_fanout_released"`
	// AEADFailures counts per-frame AEAD (CapPerFrameNoise) open failures
	// across ALL route groups — the stream RouteGroup's mux path and the
	// datagram group's, which also keeps its own per-group tally. A nonzero
	// value is tampering, a stale duplicate after a rekey, or wire corruption
	// the transport did not catch; the frame is always dropped, never delivered.
	AEADFailures uint64 `json:"aead_failures"`
	// DeliveryCRCFailures counts frames dropped at DELIVERY because their
	// CapDeliveryCRC trailer did not match the CRC32C of (seq ‖ payload) — see
	// delivery_crc.go. Unlike AEADFailures this one is the reassembly check: it
	// catches a reorder/flush defect that would otherwise only surface as an
	// application hash failure. It must be 0 on a healthy mux.
	DeliveryCRCFailures uint64 `json:"delivery_crc_failures"`
}

type MuxEvent struct {
	At    time.Time `json:"at"`
	Event string    `json:"event"`
	// App is the app name the route group was tagged with at dial time
	// (SetAppName), e.g. "via0281a102". Empty on the accept side.
	App string `json:"app,omitempty"`
	// Desc identifies the route group the event belongs to.
	Desc routing.RouteDescriptorFields `json:"desc"`
	// By names who decided: "local", "remote", "operator", "adaptive"
	// (liveness/self-heal) or "policy" (routing-policy rotation hook).
	By string `json:"by,omitempty"`
	// LegIndex is the leg's index at the moment of the event (-1 for
	// whole-group events); Legs is how many legs the group had AFTER it.
	LegIndex int `json:"leg_index"`
	Legs     int `json:"legs"`
	// TpID/TpType/Remote describe the leg's FIRST hop — the transport this
	// visor owns. Zero for whole-group events.
	TpID   uuid.UUID     `json:"tp_id,omitempty"`
	TpType string        `json:"tp_type,omitempty"`
	Remote cipher.PubKey `json:"remote_pk,omitempty"`
	// Hops is the leg's full forward path when the route group recorded one
	// (recordLegRoute); nil for a leg whose path was never stored.
	Hops []RouteHopInfo `json:"hops,omitempty"`
	// Reason is what decided this event, in the words of the code that did
	// ("operator: mux rm", "transport closed", "liveness: no echo for 3
	// probes", "peer retired the leg", …).
	Reason string `json:"reason,omitempty"`
}

type MuxInfo struct {
	// Desc identifies the route group.
	Desc routing.RouteDescriptor
	// FarEndPK is the OTHER end of Desc — the peer this group's chains reach,
	// never this visor. The setup node hands EACH edge the descriptor that
	// points AT that edge, so Desc.DstPK() is the LOCAL visor on BOTH sides
	// (which is why LocalAddr is desc.Dst() and RemoteAddr is desc.Src());
	// reading DstPK as the "destination"/"exit" therefore printed this visor's
	// own key as the far end of every dialed group. Consumers render this
	// instead of deriving an end from Desc.
	FarEndPK cipher.PubKey
	// MuxEnabled is false for non-mux'd rg's; the per-leg counters
	// are still populated for the single transport in that case.
	MuxEnabled bool
	// SACKEnabled is true when the peers negotiated SACK retx.
	SACKEnabled bool
	// HOLRetxEnabled is true when the peers negotiated CapHOLRetx (proactive
	// head-of-line retransmit — the frontier-blocking seq is fast-retransmitted on
	// the fastest leg after ~one fast-leg RTT instead of the reactive waits).
	HOLRetxEnabled bool
	// PerFrameNoise is true when both edges negotiated CapPerFrameNoise and the
	// mux is sealing/opening each DATA frame under its own sequence-nonce (the
	// inverse-multiplexer path, network.EncryptConn bypassed). False means the
	// group runs the classic stream-noise wrap.
	PerFrameNoise bool
	// AppName is the app that DIALED this route group — the key its session's
	// shape and move history are held under. Distinct from KnobApp below,
	// which is only ever set when that app has an override of its own.
	AppName string
	// KnobApp names the app whose `route settings --app <name>` override set this
	// group resolved against; empty means it runs the visor-wide values. It is
	// how a paired subject/reference run proves the two clients really did get
	// different knobs.
	KnobApp string
	// Directional is true when unidirectional send selection (CapUniDir) is
	// active on this mux: each direction rides a disjoint leg class instead of
	// both striping every leg. Flipped reports the current direction->leg-class
	// mapping. DEFAULT (Flipped=false): this end sends its FORWARD/upload on the
	// DIRECT (1-hop) leg and its REVERSE/download on the MULTIHOP mux legs.
	// FLIPPED=true: the mapping is swapped (the heavy direction took the mux).
	// With the per-leg Direct flag, a reader can tell which class carries which
	// direction without log-grepping. Both false on a non-directional mux.
	Directional bool
	Flipped     bool
	// FlipPinned is the operator's MANUAL direction pin on a directional group:
	// "auto" (the flip controller is in charge — the default), "default" or
	// "flipped" (the mapping is pinned to that state and the controller is
	// dormant until released via mode auto). Empty on a non-directional mux.
	FlipPinned string
	// Distribution names how the mux spreads outbound packets across its legs
	// (the transportSelector weight mode: "auto", "round-robin", "weighted",
	// "capacity", "latency-adaptive", "sticky:5tuple", "size-threshold",
	// "dscp-priority"). Empty for a non-mux group.
	Distribution string
	// ReorderPending is the number of received packets currently buffered
	// out-of-order (head-of-line-blocking depth); ReorderGapAge is how long the
	// current reorder frontier gap has stayed open (0 when contiguous). A rising
	// pending count with a growing gap age is a stalled/black-holing leg.
	ReorderPending int
	ReorderGapAge  time.Duration
	// WriteSeq is the total DATA frames this mux has emitted outbound — a cheap
	// aggregate send-progress counter across all legs.
	WriteSeq uint32
	// FEC telemetry (see routeMux fec* counters). FECEnabled is true when both
	// peers negotiated CapFEC. FECRepairBytesSent/Recv are cumulative repair-frame
	// bytes — the TRUE FEC overhead, separable from data and retransmit.
	// FECReconstructs counts frontier frames recovered from repair.
	FECEnabled         bool
	FECRepairBytesSent uint64
	FECRepairBytesRecv uint64
	FECReconstructs    uint64
	// Legs is in tps[] order. One entry per active mux leg.
	Legs []MuxLeg
	// Events is this group's most recent leg/group changes with their reasons,
	// oldest first (the last muxEventsPerGroup of the router's ring). It puts
	// the churn next to the legs, so a `proxy mux info --json` that shows a leg
	// missing also shows who took it and why. The full ring is
	// diag.mux_events in `visor state`.
	Events []MuxEvent
	// Recovery is the loss-recovery view (sender retransmit machinery +
	// receiver reorder frontier). Nil for a group with no mux.
	Recovery *MuxRecovery
	// TunnelRole is the DIALING app's label for this route group — "active"
	// (it carries streams) or "standby" (held open and measured, ready to take
	// over). Empty for any group that is not one of a multi-tunnel app's
	// tunnels, and ALWAYS empty on the accepting end: an exit knows how many
	// tunnels a client holds but not which of them are in standby, so read the
	// role on the local end.
	// AgeMS is how long this route group has existed. For a pooled STANDBY
	// tunnel it is its AUDITION age — how long it has been held open, pinged
	// and measured without carrying a stream.
	AgeMS      float64
	TunnelRole string
	// DisjointRoutes is how many routes to this group.s far end share no
	// intermediate and no first hop (router.disjointRouteBound). Set by the
	// router on the snapshots it hands out; 0 when not yet counted.
	DisjointRoutes int
	// LegReserve is a standby group a leg split built: a chain the pool may
	// compose back in as a leg, but not a tunnel the app can promote.
	LegReserve bool
	// Shape is the SESSION's measured multiplexing shape — every ACTIVE
	// tunnel this app holds to this exit with its live leg count, written
	// "<k>x<n>" when the tunnels are the same width and "n1,n2,…" when they
	// are not. "4x1" is pure stream level, "1x4" pure packet level, "2x2"
	// the default. ShapeTarget is the shape the session is being held at and
	// ShapeSource where that target came from: "auto" (tunnel.count tunnels
	// at pool.active_width legs, today's rule) or "mux.shape" when the knob
	// names one. The target is ADVISORY — reported, not yet converged toward
	// (docs/design/mux-shape-axis.md).
	//
	// All three are empty on any group that is not an active tunnel: a
	// standby is the pool rather than the shape, and an accepting visor
	// cannot see which of a client's tunnels are in standby.
	Shape       string
	ShapeTarget string
	ShapeSource string
	// ShapeTunnels is the k the target asks for — the number of ACTIVE tunnels
	// the session is converging to. 0 under mux.shape=auto, where the count is
	// the app's own tunnel.count and nothing here overrides it. It is published
	// so the dialing app can promote toward the shape rather than toward
	// tunnel.count (docs/design/mux-shape-axis.md step 6).
	ShapeTunnels int
	// LastMove is the most recent shape move this session made and MoveCounts
	// the running tally, keyed by the four move names (pool_leg_taken,
	// pool_leg_released, tunnel_promoted, tunnel_parked). They make a shape
	// history readable without walking the event ring. Both nil on a session
	// that has never moved.
	LastMove   *MuxShapeMove
	MoveCounts map[string]uint64
}

type MuxLeg struct {
	LegStats
	TransportID string `json:"transport_id"`
	TpType      string `json:"tp_type"`
	RemotePK    string `json:"remote_pk"`
	// Source names where a leg that is NOT this group's own dial came from —
	// "standby :4, re-homed in place" for a leg the pool arbiter took
	// (pool_arbiter.go). Empty for an ordinary dialed leg.
	Source string `json:"source,omitempty"`
	// LatencyMS is the FIRST-HOP transport RTT in ms (the same value
	// 'tp ls' shows). For a multihop leg this is only the near edge, NOT
	// the whole path — use RouteLatencyMS for the end-to-end route.
	LatencyMS float64 `json:"latency_ms"`
	// RouteLatencyMS is the leg's TRUE end-to-end route latency in ms —
	// the EWMA-smoothed round-trip of the per-leg liveness pong across
	// ALL hops (from legE2ELatency). This is the number a routing policy
	// judges a leg by; it can differ sharply from LatencyMS on a multihop
	// leg. Zero until the first pong lands.
	RouteLatencyMS float64 `json:"route_latency_ms"`
	// AckDelayMS is this leg's own EWMA send→ack delay in ms (0 = no sample):
	// the loaded feedback delay its retransmit threshold is judged by
	// (rackThresholdFor), distinct from the idle RTTs above.
	AckDelayMS float64 `json:"ack_delay_ms"`
	// InflightBytes / WindowBytes: the leg's real unacknowledged bytes and the
	// per-leg send window they are bounded by (0 when not a predictive mode).
	InflightBytes float64 `json:"inflight_bytes"`
	WindowBytes   float64 `json:"window_bytes"`
	// Direct is true when this leg's first hop goes straight to the route
	// group's destination (a 1-hop/direct route); false means the leg is
	// multihop (relayed through one or more intermediates). Lets a viewer
	// tell the direct leg from the multihop legs at a glance.
	Direct bool `json:"direct"`
	// Alive is false once the leg's transport is closed. Standby is true
	// when the leg is a WARM STANDBY: rules kept alive but not selected
	// for sending (see docs/warm_standby_legs_rfc.md). Together they are
	// the leg's gate_state for the per-leg telemetry harness.
	Alive   bool `json:"alive"`
	Standby bool `json:"standby"`
	// Hops is this leg's FULL forward route — every hop from this visor to
	// the destination, with full (untruncated) From/To PKs and per-hop
	// transport type. Per-hop LatencyMS is filled where known (first hop
	// owned; single-intermediate far hop derived from route−transport RTT).
	// Empty when the route path wasn't recorded (legacy/accepted routes).
	Hops []RouteHopInfo `json:"hops,omitempty"`
	// CapacityPriorBps is the pool arbiter's PRIOR throughput estimate for
	// this leg's transport (throughputPrior: the transport's live measured
	// rate if it has one, else its catalog entry) — the number a standby
	// tunnel is ranked by BEFORE it is measured. Distinct from GoodputBps,
	// which is the leg's own live EWMA once it has carried traffic.
	CapacityPriorBps float64 `json:"capacity_prior_bps,omitempty"`
}

type MuxLegController interface {
	SetMuxExplicitWeights(desc routing.RouteDescriptor, weights map[uuid.UUID]float64) (MuxWeightsView, error)
	ClearMuxExplicitWeights(desc routing.RouteDescriptor) (MuxWeightsView, error)
	MuxWeightsFor(desc routing.RouteDescriptor) (MuxWeightsView, error)
	AddMuxRouteByHopsForward(desc routing.RouteDescriptor, fwd, rev []routing.Hop) error
	MuxNegotiatedForApp(appName string) []MuxNegotiated
	// RehomeStandbyLeg moves a STANDBY group's whole built chain into the
	// target group as one more mux leg, in place, with no setup-node dial.
	// Returns ErrRehomeUnsupported when the peer did not negotiate
	// CapLegRehome. See leg_rehome.go.
	RehomeStandbyLeg(target, standby routing.RouteDescriptor) error
}

type MuxNegotiated struct {
	DstPort uint16 `json:"dst_port"`
	SrcPort uint16 `json:"src_port"`
	Remote  string `json:"remote"`
	// AppName is the dialing app's tag on the group, when it has one.
	AppName string `json:"app_name,omitempty"`
	Legs    int    `json:"legs"`
	// Negotiated capabilities — both ends advertised these.
	MuxEnabled     bool `json:"mux_enabled"`
	SACKEnabled    bool `json:"sack_enabled"`
	HOLRetxEnabled bool `json:"hol_retx_enabled"`
	PerFrameNoise  bool `json:"per_frame_noise"`
	FECEnabled     bool `json:"fec_enabled"`
	Directional    bool `json:"directional"`
	// Scheduler in force, and the explicit weights when it is that mode.
	Distribution    string      `json:"distribution"`
	ExplicitWeights []LegWeight `json:"explicit_weights,omitempty"`
	// Send-window shape in effect (the live router settings this end clamps to).
	EcfMinWindowBytes   int64   `json:"ecf_min_window_bytes"`
	EcfMaxWindowBytes   int64   `json:"ecf_max_window_bytes"`
	EcfWindowMargin     float64 `json:"ecf_window_margin"`
	SendWindowWaitMax   string  `json:"send_window_wait_max"`
	ForwardSpill        bool    `json:"forward_spill"`
	ForwardSwitchMargin float64 `json:"forward_switch_margin"`
	// PerLegWindowBytes is each leg's CURRENT send window, in tps[] order —
	// the negotiated shape as the scheduler is actually applying it.
	PerLegWindowBytes []float64 `json:"per_leg_window_bytes,omitempty"`
}

type MuxRecovery struct {
	// Sender side. WriteSeq is the next outgoing DATA sequence; RetxHeld /
	// RetxMinSeq / RetxMaxSeq are the unacknowledged window still retransmittable
	// (a peer's stuck frontier BELOW RetxMinSeq can never be healed); RetxSent is
	// retransmit packets put on the wire (summed across legs);
	// RetxSkippedMissing counts resend requests for sequences no longer held;
	// RetxSendErrors counts resends that failed to reach any leg; TLPProbes counts
	// tail-loss probes; SACKsRecv / LastSACKRecvMsAgo / LastSACKRecvContig are the
	// inbound feedback (ms-ago is -1 when no SACK has ever arrived).
	WriteSeq           uint32 `json:"write_seq"`
	RetxHeld           int    `json:"retx_held"`
	RetxMinSeq         uint32 `json:"retx_min_seq"`
	RetxMaxSeq         uint32 `json:"retx_max_seq"`
	RetxSent           uint64 `json:"retx_sent"`
	RetxSkippedMissing uint64 `json:"retx_skipped_missing"`
	RetxReqSACK        uint64 `json:"retx_req_sack"`
	RetxReqHOL         uint64 `json:"retx_req_hol"`
	RetxReqFlush       uint64 `json:"retx_req_flush"`
	// RetxDeferredYoung counts the holes a SACK named that were NOT resent
	// because the frame is still younger than the delay basis of the leg it
	// rode — the duplicate bytes kept off the wire.
	RetxDeferredYoung uint64 `json:"retx_deferred_young"`
	RetxSendErrors    uint64 `json:"retx_send_errors"`
	// SendWindowWaits / SendWindowTimeouts: writers parked because every ready
	// leg was at its per-leg send window, and the parks that gave up after
	// sendWindowWaitMax and sent anyway.
	SendWindowWaits    uint64  `json:"send_window_waits"`
	SendWindowTimeouts uint64  `json:"send_window_timeouts"`
	TLPProbes          uint64  `json:"tlp_probes"`
	SACKsRecv          uint64  `json:"sacks_recv"`
	LastSACKRecvMsAgo  float64 `json:"last_sack_recv_ms_ago"`
	LastSACKRecvContig uint32  `json:"last_sack_recv_contig"`
	// Receiver side. ReorderNextSeq is the frontier this end waits on,
	// ReorderPending how many packets are dammed behind it, GapAgeMS how long it
	// has been stuck. SACKsSent / SACKSendErrors / LastSACKSentMsAgo are the
	// outbound feedback (ms-ago -1 when none ever sent). WedgeTicks is the
	// CURRENT wedge's stall-tick count (0 = not wedged), Wedges how many have
	// cleared on this group, LongestWedgeMS the worst one seen. ReorderDrops
	// counts arrivals the reorder buffer discarded because the gap already held
	// a full window — they are deliberately NOT SACKed, so each one is owed a
	// retransmit.
	ReorderNextSeq    uint32  `json:"reorder_next_seq"`
	ReorderPending    int     `json:"reorder_pending"`
	ReorderDrops      uint64  `json:"reorder_drops"`
	GapAgeMS          float64 `json:"gap_age_ms"`
	SACKsSent         uint64  `json:"sacks_sent"`
	SACKSendErrors    uint64  `json:"sack_send_errors"`
	LastSACKSentMsAgo float64 `json:"last_sack_sent_ms_ago"`
	WedgeTicks        int64   `json:"wedge_ticks"`
	Wedges            uint64  `json:"wedges"`
	LongestWedgeMS    int64   `json:"longest_wedge_ms"`
}

type MuxShapeMove struct {
	Move   string    `json:"move"`
	From   string    `json:"from"`
	To     string    `json:"to"`
	Reason string    `json:"reason"`
	At     time.Time `json:"at"`
}

type MuxWeightsView struct {
	DstPort uint16      `json:"dst_port"`
	SrcPort uint16      `json:"src_port"`
	Mode    string      `json:"mode"`
	Weights []LegWeight `json:"weights,omitempty"`
}

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

type NoiseRouteGroup struct {
	net.Conn
	// contains filtered or unexported fields
}

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

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

type RelayPeersArgs struct{}

type RelayPeersReply struct {
	Peers []cipher.PubKey `json:"peers"`
}

type ReserveError struct {
	PK  cipher.PubKey
	Err error
}

type Role uint8

type RotationAction struct {
	// DropLegs is the list of current-tick leg indices to close.
	// Indices reference the legs slice passed to the hook —
	// they're NOT stable across ticks because the prune path
	// compacts the slice when a leg closes.
	DropLegs []int

	// AddLeg requests one more aux forward leg with ExcludeHops
	// as the disjoint-intermediate filter.
	AddLeg      bool
	ExcludeHops []string

	// DemoteToStandby / PromoteFromStandby move legs between the active set
	// and warm standby WITHOUT teardown: a demoted leg keeps its rules (the
	// keepalive/liveness loops keep them alive) but is no longer selected for
	// sending; promoting clears that instantly, with no route setup. This is
	// the cheap alternative to Drop+re-dial for policy-driven leg moves — see
	// docs/warm_standby_legs_rfc.md. Indices are current-tick leg indices, like
	// DropLegs. Applied before DropLegs (which compacts) so the indices stay
	// valid.
	DemoteToStandby    []int
	PromoteFromStandby []int

	// AddForwardLeg requests one more FORWARD-ONLY aux leg — appended
	// addFwd=true / addRev=false so it adds upstream send capacity without
	// enlarging the reverse/download set. The rotation loop dials it via the
	// forward-only add callback (router.addOneAuxSendLeg). The forward-
	// direction mirror of AddLeg; emitted by the adaptive preset under
	// sustained upload (SentBytes) saturation. ExcludeHops applies to it too.
	AddForwardLeg bool
}

type RotationHook interface {
	OnTick(info DialInfo, legs []LegInfo) RotationAction
}

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

type RouteGroupConfig struct {
	ReadChBufSize     int
	KeepAliveInterval time.Duration
	// FEC advertises CapFEC in the mux handshake so repair frames are striped
	// alongside data. Off by default (router Config.MuxFEC).
	FEC bool
}

type RouteGroupDialer interface {
	Dial(
		ctx context.Context,
		log *logging.Logger,
		dmsgC *dmsg.Client,
		setupNodes []cipher.PubKey,
		req routing.BidirectionalRoute,
	) (routing.EdgeRules, cipher.PubKey, error) // Returns rules and the connected setup node PK
}

type RouteGroupQueue struct {
	Desc     string `json:"desc"`
	App      string `json:"app,omitempty"`
	Queue    int    `json:"queue"`
	Capacity int    `json:"capacity"`
	// IntakeQueue/IntakeCapacity are the group's intake queue (see
	// RouteGroup.inCh), and IntakeDrops counts packets the router dropped
	// because it was full.
	IntakeQueue    int    `json:"intake_queue"`
	IntakeCapacity int    `json:"intake_capacity"`
	IntakeDrops    uint64 `json:"intake_drops"`
}

type RouteHopInfo struct {
	TpID   string `json:"tp_id"`   // Transport ID
	From   string `json:"from"`    // Source public key (full, never truncated)
	To     string `json:"to"`      // Destination public key (full, never truncated)
	TpType string `json:"tp_type"` // Transport type (stcpr, sudph, dmsg)
	// LatencyMS is this hop's transport RTT in ms, when known. The first
	// hop is owned locally (tp.GetLatency). For a single-intermediate leg
	// the far hop is derived (route RTT − first-hop RTT). Deeper hops are
	// 0 here until sourced from TPD / the setup node's per-transport data.
	LatencyMS float64 `json:"latency_ms,omitempty"`
}

type RouteSelectingHook interface {
	DialHook
	// SelectRoute is invoked synchronously after the route-finder
	// returns candidates and before route setup. forward and
	// reverse are the per-direction candidate lists (the same
	// path returned for both directions when the route-finder
	// query was symmetric). The hook may return Chosen / ReverseChosen
	// indices (into the respective lists) or -1 to defer per
	// direction. Drop=true refuses the dial with ErrDialPolicyDropped.
	SelectRoute(ctx context.Context, info DialInfo, forward, reverse []CandidateInfo) (RouteSelection, error)
}

type RouteSelection struct {
	// Chosen is the forward-direction index into the forward
	// candidates slice passed to SelectRoute, or -1 to defer.
	Chosen int
	// ReverseChosen is the reverse-direction index into the
	// reverse candidates slice, or -1 to defer (router uses its
	// built-in pickBestDirection latency rank for reverse).
	// Independent of Chosen — a script can override forward but
	// defer reverse, or vice versa.
	ReverseChosen int
	Drop          bool
	Distribution  DistributionConfig
}

type RouteSetupHook func(cipher.PubKey, *transport.Manager) error

type RouteSourceStats struct {
	// Requests is fetchBestRoutes calls; DirectHops is how many were served
	// by a transport this visor already holds.
	Requests   int64 `json:"requests"`
	DirectHops int64 `json:"direct_hops"`
	// OracleAttempts is 2-hop calculations from the destination's own list
	// through the setup node; OracleRoutes is how many found a route.
	OracleAttempts int64 `json:"oracle_attempts"`
	OracleRoutes   int64 `json:"oracle_routes"`
	// LocalAttached is routes built from the local graph before the route
	// finder was asked (Config.PreferLocalRouteTo): each one is a route-finder
	// query that did not happen.
	LocalAttached int64 `json:"local_attached"`
	// RouteFinderQueries is route-finder requests made (one per attempt).
	RouteFinderQueries int64 `json:"route_finder_queries"`
	// LocalFallback is routes built locally after the route finder missed or
	// ran out of retries.
	LocalFallback int64 `json:"local_fallback"`
	// DirectSetups is one-hop routes set up with the peer, without a setup node.
	DirectSetups int64 `json:"direct_setups"`
	// DirectSetupFallbacks is one-hop routes the peer could not set up
	// directly, sent to a setup node instead.
	DirectSetupFallbacks int64 `json:"direct_setup_fallbacks"`
	// ListAttempts is 3-hop calculations from other visors' own transport
	// lists; ListRoutes is how many found a route. The ListNo* counters say
	// why the rest did not: no usable first hop, no list from the destination,
	// no list from any neighbor, or no path through the lists that came back.
	ListAttempts       int64 `json:"list_attempts"`
	ListRoutes         int64 `json:"list_routes"`
	ListNoFirstHop     int64 `json:"list_no_first_hop"`
	ListNoDstList      int64 `json:"list_no_dst_list"`
	ListNoNeighborList int64 `json:"list_no_neighbor_list"`
	ListNoPath         int64 `json:"list_no_path"`
	// ListExcluded is list routes found but every candidate was a held or
	// recently dead first hop.
	ListExcluded int64 `json:"list_excluded"`
	// ListFetches is neighbor lists asked for; ListFetchFails is how many
	// did not come back.
	ListFetches    int64 `json:"list_fetches"`
	ListFetchFails int64 `json:"list_fetch_fails"`
}

type RouteStatus struct {
	// Connection identity
	LocalPK    cipher.PubKey `json:"local_pk"`
	RemotePK   cipher.PubKey `json:"remote_pk"`
	LocalPort  routing.Port  `json:"local_port"`
	RemotePort routing.Port  `json:"remote_port"`

	// Initiator is true when this visor dialed the route (called
	// router.DialRoutes). False when this visor accepted the route
	// from a remote setup-node request.
	Initiator bool `json:"initiator"`

	// Status
	Alive   bool          `json:"alive"`
	Latency time.Duration `json:"latency_ns"`

	// Traffic stats
	BandwidthSent     uint64 `json:"bandwidth_sent"`
	BandwidthReceived uint64 `json:"bandwidth_received"`
	UploadSpeed       uint32 `json:"upload_speed"`
	DownloadSpeed     uint32 `json:"download_speed"`

	// Mux info
	MuxEnabled bool             `json:"mux_enabled"`
	Transports []RouteTransport `json:"transports"`

	// Hops is the full forward path for this route group, populated from
	// rg.forwardHops. Empty if the path wasn't recorded (older routes or
	// the fallback reconstruction).
	Hops []RouteHopInfo `json:"hops,omitempty"`
}

type RouteTransport struct {
	ID        uuid.UUID       `json:"id"`
	Type      string          `json:"type"`
	RemotePK  cipher.PubKey   `json:"remote_pk"`
	Latency   float64         `json:"latency_ms"`
	FwdRuleID routing.RouteID `json:"fwd_rule_id"`
	// RvsRuleID is the matching reverse (Consume) rule on this side.
	// Paired by index with FwdRuleID.
	RvsRuleID routing.RouteID `json:"rvs_rule_id"`
}

type Router interface {
	io.Closer

	// DialRoutes dials to a given visor of 'rPK'.
	// 'lPort'/'rPort' specifies the local/remote ports respectively.
	// A nil 'opts' input results in a value of '1' for all DialOptions fields.
	// A single call to DialRoutes should perform the following:
	// - Find routes via RouteFinder (in one call).
	// - Setup routes via SetupNode (in one call).
	// - Save to routing.Table and internal RouteGroup map.
	// - Return RouteGroup if successful.
	DialRoutes(ctx context.Context, rPK cipher.PubKey, lPort, rPort routing.Port, opts *DialOptions) (net.Conn, error)
	PingRoute(ctx context.Context, rPK cipher.PubKey, lPort, rPort routing.Port, opts *DialOptions) (net.Conn, error)

	// DialRoutesDatagram dials a faithful-UDP (#2607) route. It performs a
	// normal DialRoutes (forcing opts.Datagram=true so the reliable route's
	// Noise handshake also keys a DatagramRouteGroup sibling), then returns
	// both the reliable conn (which the caller must keep alive — closing it
	// tears down the route and the sibling) and the datagram sibling. Errors
	// if the peer did not also register datagram intent for the port (no
	// sibling registered).
	DialRoutesDatagram(ctx context.Context, rPK cipher.PubKey, lPort, rPort routing.Port, opts *DialOptions) (net.Conn, *DatagramRouteGroup, error)

	// RegisterDatagramPort / UnregisterDatagramPort mark a local port as
	// faithful-UDP-capable (#2607). The accept side builds a datagram
	// sibling only for routes whose local port is registered.
	RegisterDatagramPort(port routing.Port)
	UnregisterDatagramPort(port routing.Port)

	// AcceptDatagram blocks until an accept-side datagram sibling is
	// available (or ctx/visor is done), returning it and the local port
	// it targets. Drained by the forwarded_ports.udp server loop.
	AcceptDatagram(ctx context.Context) (*DatagramRouteGroup, routing.Port, error)

	// AcceptRoutes should block until we receive an AddRules packet from SetupNode
	// that contains ConsumeRule(s) or ForwardRule(s).
	// Then the following should happen:
	// - Save to routing.Table and internal RouteGroup map.
	// - Return the RoutingGroup.
	AcceptRoutes(context.Context) (net.Conn, error)
	SaveRoutingRules(rules ...routing.Rule) error
	ReserveKeys(n int) ([]routing.RouteID, error)
	IntroduceRules(rules routing.EdgeRules) error
	Serve(context.Context) error
	SetupIsTrusted(cipher.PubKey) bool
	SetMinHop(uint16)

	// EffectiveMinHops resolves a dial's min-hops constraint from the
	// per-dial options and the visor-global setting together. Exposed
	// because callers OUTSIDE the router take dial shortcuts that bypass
	// route setup — appnet's direct dial above all — and cannot honor the
	// operator's constraint without being able to ask what it is.
	EffectiveMinHops(opts *DialOptions) uint16
	SetExistingTPOnly(bool)
	SetForceLocalRoutes(bool)
	// SetDstTransportOracle wires the RSN-oracle 2-hop route path's
	// destination-transport oracle (see rsn_oracle_routes.go). nil leaves the
	// path inert.
	SetDstTransportOracle(DstTransportOracle)
	SetMuxMode(WeightMode)
	// SetMuxFEC / GetMuxFEC mirror Config.MuxFEC at runtime; the setting is
	// read when a mux route group is BUILT, so it reaches new groups only.
	SetMuxFEC(bool)
	GetMuxFEC() bool
	GetExistingTPOnly() bool
	GetForceLocalRoutes() bool
	GetLastRouteCalcTime() time.Duration
	ActiveRouteStatuses() []RouteStatus
	RoutingTableStats() routing.RoutingTableStats
	AddMuxRouteByHops(desc routing.RouteDescriptor, fwd, rev []routing.Hop) error
	GrowMuxRoute(desc routing.RouteDescriptor, target, minHops int) (int, error)
	// GrowMuxFromPool grows the tunnel route group this visor dialed from
	// localPort by up to legs additional mux legs, taking the plans from the
	// app's STANDBY tunnels to the same exit (already ranked, first-hop
	// transport already up) and falling back to GrowMuxRoute's route-finder
	// path for whatever the pool cannot cover. See pool_legs.go.
	GrowMuxFromPool(localPort routing.Port, legs, minHops int) (int, error)
	RemoveMuxRouteByTransport(desc routing.RouteDescriptor, tpID uuid.UUID) error

	// SetMuxDirectionForApp applies a manual unidirectional direction pin
	// (routing.DirectionAuto / DirectionPinDefault / DirectionPinFlipped) to
	// EVERY active directional route group tagged with the named app (a proxy
	// session can hold several concurrent rg's). Returns how many groups the
	// pin was applied to; errors when the app has no active directional group.
	SetMuxDirectionForApp(appName string, mode byte) (int, error)

	// RouteGroupHops returns the stored forward route hops for the route group
	// matching the given descriptor (or its inversion). Returns nil if no
	// matching route group is found.
	RouteGroupHops(desc routing.RouteDescriptor) []RouteHopInfo

	// DialHook returns the configured routing-policy hook (nil
	// if none configured). Visor wiring uses this to bridge the
	// policy into non-router dial paths like VStreamMux's direct
	// dial — the policy script's BeforeDial fires there too with
	// ctx.is_direct_dial=true.
	DialHook() DialHook

	// RouteGroupMuxInfo returns a snapshot of per-leg mux state for
	// the rg matching desc (or its inversion). Returns false when no
	// matching active rg is found. Used by 'cli proxy mux-info' to
	// surface per-leg bandwidth + latency for diagnostic purposes.
	RouteGroupMuxInfo(desc routing.RouteDescriptor) (MuxInfo, bool)

	// RouteGroupMuxInfoForApp returns mux snapshots for every active
	// rg whose source port maps (via AppLookup) to the named app.
	// One app may have multiple rg's at once (e.g. each SOCKS5
	// client connection to skysocks-client gets its own rg). Returns
	// an empty slice if no rg's are active for the app.
	RouteGroupMuxInfoForApp(appName string) []MuxInfo

	// RouteGroupMuxInfoAll returns mux snapshots for EVERY active
	// route group, regardless of the app it is tagged with. Powers the
	// whole-runtime `cli visor state` view where the per-leg mux shape
	// of all route groups (not just one app's) is wanted at once.
	RouteGroupMuxInfoAll() []MuxInfo

	// CloseRouteGroupsForApp closes and de-registers every route group
	// tagged with appName — the app's own tunnels plus the sibling groups
	// a multi-tunnel dial (--tunnels N) created alongside them. Returns
	// the number of groups closed. Called when the app stops, so a group
	// the app will never read from again does not keep refreshing its
	// rules by keep-alive and does not show up in `proxy mux info` (or
	// the --route reconcile count) for a stopped app.
	CloseRouteGroupsForApp(appName string) int

	// MuxEvents returns the bounded history of route-group and mux-leg
	// changes — each add, removal, park, re-home and group close with the
	// reason the code gave and who initiated it. This is where to look when
	// a leg that was in `proxy mux info` is gone: the visor log ring holds
	// minutes, this holds the events.
	MuxEvents() []MuxEvent

	// MuxCounters returns the whole-router cumulative counters (tunnel
	// promotions, leg re-homes sent/received/acked/failed, forward fan-out
	// engage/release) that the bounded MuxEvents ring above does not retain
	// once it wraps.
	MuxCounters() MuxCounters

	// NoteTunnelEvent records an event the APP that holds a tunnel decided —
	// a standby tunnel promoted into the active set, an active one parked, a
	// dead one retired — on the route group dialed from localPort, and
	// updates that group's TunnelRole when role is non-empty.
	//
	// It exists because the two halves of the answer live in different
	// processes. Only the app knows which of its tunnels carries streams;
	// only the router knows which transport and route the tunnel leaves over,
	// and only the router owns the event ring `visor state --select diag`
	// reads. The app names the tunnel by the local port it dialed from — the
	// one identifier it is handed at dial time (DialResp.LocalPort) — and the
	// router fills in the rest.
	//
	// Reports whether a route group with that local port was found. Both
	// sides of the descriptor are tried, so it works for a group keyed by
	// either the dialing or the mirrored descriptor.
	NoteTunnelEvent(localPort routing.Port, event, reason, role string) bool

	// Routing table related methods
	RoutesCount() int
	Rules() []routing.Rule
	Rule(routing.RouteID) (routing.Rule, error)
	SaveRule(routing.Rule) error
	DelRules([]routing.RouteID)
}