policy

type Candidate struct {
	// Hops is the ordered list of intermediate visor PKs from
	// source (excluded) to destination (excluded). Empty list means
	// a direct transport.
	Hops []string

	// HopsGeo mirrors Hops with ISO-3166 country codes for each
	// intermediate, resolved via the embedded geoip database.
	// Unknown / unresolvable hops appear as "??". Policies use
	// this for geographic filtering ("only routes through ID").
	HopsGeo []string

	// EstLatencyMs is the visor's best estimate of round-trip
	// latency along this route, from the transport-tracker's
	// recent measurements. Zero when no recent measurement is
	// available — policies should treat zero as "unknown" rather
	// than "fast."
	EstLatencyMs int

	// TransportKinds is the set of transport types along the
	// route (e.g. ["stcpr"], ["dmsg"], ["stcpr", "sudph"] for
	// mixed-transport routes). Used by policies that want to
	// prefer direct-tcp paths over relayed-dmsg paths.
	TransportKinds []string
}

type Clock interface {
	Now() time.Time
}

type Engine interface {
	Decide(ctx context.Context, rctx RoutingContext, candidates []Candidate) (RouteSpec, error)
	OnLegChange(ctx context.Context, rctx RoutingContext, legs []LegInfo, change LegChange) (RouteSpec, error)
	OnTick(ctx context.Context, rctx RoutingContext, legs []LegInfo) (RotationAction, error)
	IsActive() bool
	Source() string
	Close() error
}

type EngineSnapshot struct {
	Source string
	Active bool
}

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

type FailureMode int

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

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

type HookOption func(*Hook)

type HookSnapshot struct {
	Default *EngineSnapshot
	PerApp  map[string]*EngineSnapshot
}

type LegChange struct {
	Event    string
	LegIndex int
}

type LegInfo struct {
	Index       int
	Kind        string
	TransportID string
	LatencyMs   int
	Alive       bool
	// Standby mirrors router.LegInfo.Standby: true when the leg is a
	// warm standby (rules kept alive, not selected for sending).
	Standby bool
	// Direct mirrors router.LegInfo.Direct: true when the leg is the
	// forward-only DIRECT (1-hop) leg of a unidirectional route group, so a
	// download-sizing controller keeps it out of the reverse-active budget.
	Direct bool
	// Flipped mirrors router.LegInfo.Flipped: the route group's current
	// unidirectional flip state (same on every leg). A leg carries the download
	// direction when Direct == Flipped.
	Flipped     bool
	SentBytes   uint64
	RecvBytes   uint64
	Retransmits uint64
	Hops        []string
}

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

type Option func(*Evaluator)

type Provider interface {
	// Geo returns the ISO-3166 country code for a peer PK, or
	// "??" when unknown. Operators use this for geographic
	// routing filters ("only routes through ID").
	Geo(pk string) string

	// Latency returns the most recent measured round-trip in
	// milliseconds to this peer. Zero means "no recent
	// measurement" — scripts should treat zero as unknown, not
	// fast.
	Latency(pk string) int

	// Kind returns the transport family of the most recent
	// connection to this peer ("stcpr", "sudph", "dmsg"). Empty
	// when unknown.
	Kind(pk string) string

	// IsTrusted reports whether the peer's PK is in the
	// operator-configured trust list. Used by policies that want
	// "trusted peers get direct routes, untrusted peers go
	// through 2+ hops" style rules.
	IsTrusted(pk string) bool

	// IsHypervisor reports whether the peer's PK is one of the
	// visor's configured hypervisors. Policies typically want to
	// dial hypervisors with minimum hops + maximum mux for low-
	// latency control-plane traffic.
	IsHypervisor(pk string) bool

	// HasTransport reports whether the visor already holds a live
	// transport to this peer (of any type). Policies use it to
	// prefer routing over peers we're already connected to —
	// reusing existing plumbing instead of paying the setup cost of
	// a fresh transport (handshake + AR register + route-finder) on
	// the dial hot path. False when the peer is only reachable
	// through intermediates, or unknown.
	HasTransport(pk string) bool
}

type RotationAction struct {
	DropLegs    []int
	AddLeg      bool
	ExcludeHops []string
	// DemoteToStandby / PromoteFromStandby move legs to/from warm standby
	// without teardown (kept alive, just not selected for sending). See
	// router.RotationAction and docs/warm_standby_legs_rfc.md.
	DemoteToStandby    []int
	PromoteFromStandby []int
	// AddForwardLeg requests one more FORWARD-ONLY aux leg (router appends it
	// addFwd=true / addRev=false): extra upstream send capacity that does not
	// enlarge the reverse/download set. The forward-direction mirror of AddLeg,
	// emitted by the adaptive preset on sustained upload saturation.
	AddForwardLeg bool
}

type RouteSpec struct {
	// Chosen is the forward-direction candidate the policy picked.
	// Nil means "fall back to the visor's built-in default" —
	// either because the policy returned an explicit None or
	// because every candidate was filtered out. For directional-
	// asymmetric policies, set ReverseChosen separately.
	Chosen *Candidate

	// ReverseChosen is the reverse-direction candidate, when the
	// policy wants different forward and reverse routes (e.g.
	// "stcpr upstream, sudph downstream"). Nil means "no override;
	// let the router pick the lowest-latency reverse independently."
	// The script accesses reverse candidates via ctx.reverse_candidates
	// in SelectRoute.
	ReverseChosen *Candidate

	// Mux is the symmetric number of parallel mux legs to open.
	// Zero or 1 means a single route. The router caps it at the
	// number of disjoint candidates the route-finder returned —
	// scripts that want to know that count up-front should read
	// `len(candidates)` in SelectRoute. Overridden per-direction
	// by ForwardMux / ReverseMux when those are non-zero.
	Mux int

	// ForwardMux and ReverseMux are per-direction overrides for
	// Mux. The common use case is asymmetric workloads — a
	// download-heavy app benefits from ReverseMux=N (multiple
	// download paths aggregated) and ForwardMux=1 (one cheap
	// upstream). Zero falls back to Mux.
	ForwardMux int
	ReverseMux int

	// MinHops is the symmetric minimum acceptable intermediate
	// count. Honored as a hint by the router. Overridden per-
	// direction by ForwardMinHops / ReverseMinHops when those
	// are non-zero.
	MinHops int

	// ForwardMinHops and ReverseMinHops are per-direction
	// overrides for MinHops. Useful when one direction needs more
	// hops than the other for compliance or trust reasons. Zero
	// falls back to MinHops.
	ForwardMinHops int
	ReverseMinHops int

	// Fallback names the backup strategy when Chosen is nil or
	// rejected. Recognized values:
	//   ""       — use the visor's built-in default (router's
	//              disjoint-path pick on the unfiltered candidates,
	//              or direct-transport short-circuit if one exists)
	//   "drop"   — fail the dial loudly with ErrDialPolicyDropped
	//              (operator notices; app sees a connection error)
	//   "direct" — skip the route-finder, force the direct-transport
	//              short-circuit. If no direct transport exists,
	//              the dial fails. Useful when a script's filter
	//              wipes all multihop candidates but a direct
	//              transport would still satisfy the operator
	//              (e.g. "Indonesia transit only, else direct").
	//
	// Any other value is treated as "".
	Fallback string

	// Distribution is the per-packet distribution descriptor for
	// the per-packet code path (deferred Phase 5 in the RFC).
	// Recognized values: "" (round-robin, default),
	// "weighted: a,b,c", "size-threshold:N". The per-packet path
	// stays compiled Go; this field configures it from Starlark.
	Distribution string

	// RotationIntervalSeconds, when > 0, configures the router to
	// fire the policy's on_tick hook on this route group every
	// N seconds. The hook returns a RotationAction describing
	// which legs to drop and whether to add a fresh one — the
	// mechanism behind continuous bandwidth-spreading policies
	// that rotate through the eligible-peer set. Set at dial time
	// via decide_route; cannot be changed mid-flight (drop + redial
	// to reconfigure).
	RotationIntervalSeconds int
}

type RoutingContext struct {
	// App is the registered app name making this dial — "skychat",
	// "vpn-client", etc. Policies can branch on this to apply
	// different rules per app.
	App string

	// PeerPK is the destination visor's public key (66-hex-char).
	PeerPK string

	// Port is the routing port being dialed on the remote.
	Port uint16

	// Now is the current wall-clock time at policy invocation, in
	// the operator's configured timezone. Used by datetime stdlib;
	// injectable for tests via the Evaluator's Clock.
	Now time.Time

	// CLIOverrides surfaces any per-invocation flags the operator
	// passed on the CLI (--routes N, --min-hops K, etc.). The
	// policy can choose to honor or override them. Empty map when
	// the dial came from a launched app rather than a CLI command.
	CLIOverrides map[string]string

	// IsDirectDial signals the dial is going through the
	// sky_forward_conn / VStreamMux short-circuit (an existing
	// direct transport) rather than the overlay route-finder.
	// Mux / distribution are no-ops on direct dials; the most
	// useful return from the script in this case is
	// fallback="drop" to refuse, or a bare RouteSpec() to allow.
	// Surfaced as `ctx.is_direct_dial` in Starlark.
	IsDirectDial bool

	// TransportKind is the network type ("stcpr"/"sudph"/"stcp"/
	// "dmsg") of the direct transport when IsDirectDial is true.
	// Surfaced as `ctx.transport_kind`.
	TransportKind string

	// ReverseCandidates is the reverse-direction candidate list
	// when SelectRoute is invoked, exposed to Starlark as
	// `ctx.reverse_candidates`. Empty during BeforeDial (no
	// candidates yet) and during SelectRoute when the dial used
	// a symmetric route-finder query (forward and reverse share
	// the same path candidates — same list). Scripts that want
	// per-direction filtering iterate this list separately and
	// set RouteSpec.reverse_chosen.
	ReverseCandidates []Candidate
}