intelligence

Documentation

Overview

Package intelligence implements the HiVoid adaptive decision engine. It monitors network conditions in real-time and selects operating modes to balance security, performance, and stealth requirements.

Package intelligence — real-time network metrics collection. These are fed into the decision engine for adaptive mode switching.

Package intelligence — active network probing.

Index

• type Engine
  • func NewEngine(mode Mode) *Engine
  • func (e *Engine) ActiveMode() Mode
  • func (e *Engine) ActiveState() State
  • func (e *Engine) BestTarget() string
  • func (e *Engine) ExportState() ([]byte, error)
  • func (e *Engine) ImportState(data []byte) error
  • func (e *Engine) Metrics() *Metrics
  • func (e *Engine) OnModeChange(fn func(Mode, TuningParams))
  • func (e *Engine) ProbeResults() []ProbeResult
  • func (e *Engine) SaveState() error
  • func (e *Engine) SetMode(mode Mode)
  • func (e *Engine) SetProbeTargets(targets []string)
  • func (e *Engine) SetStatePath(path string)
  • func (e *Engine) Start()
  • func (e *Engine) Stop()
  • func (e *Engine) ThreatLevel() int
  • func (e *Engine) Tuning() TuningParams
• type Metrics
  • func NewMetrics() *Metrics
  • func (m *Metrics) RecordBytes(n int64)
  • func (m *Metrics) RecordPacketLost()
  • func (m *Metrics) RecordPacketSent()
  • func (m *Metrics) RecordRTT(rtt time.Duration)
  • func (m *Metrics) Snapshot() MetricsSnapshot
• type MetricsSnapshot
• type Mode
  • func ModeFromString(s string) Mode
  • func (m Mode) String() string
• type ProbeResult
• type Prober
  • func NewProber(timeout time.Duration) *Prober
  • func (p *Prober) Probe(ctx context.Context, target string) ProbeResult
  • func (p *Prober) ProbeBatch(ctx context.Context, targets []string) []ProbeResult
• type State
  • func (s State) String() string
• type TuningParams
  • func DefaultTuning() TuningParams

Types

type Engine

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

Engine is the HiVoid intelligence decision engine. It continuously samples network metrics and adjusts tuning parameters.

func NewEngine

func NewEngine(mode Mode) *Engine

NewEngine creates a new intelligence engine with the given base mode.

func (*Engine) ActiveMode

func (e *Engine) ActiveMode() Mode

ActiveMode returns the currently active mode.

func (*Engine) ActiveState

func (e *Engine) ActiveState() State

ActiveState returns the currently detected network state.

func (*Engine) BestTarget

func (e *Engine) BestTarget() string

BestTarget selects the healthiest server from probe results using a ranking algorithm.

func (*Engine) ExportState

func (e *Engine) ExportState() ([]byte, error)

func (*Engine) ImportState

func (e *Engine) ImportState(data []byte) error

func (*Engine) Metrics

func (e *Engine) Metrics() *Metrics

Metrics returns the network metrics sampler.

func (*Engine) OnModeChange

func (e *Engine) OnModeChange(fn func(Mode, TuningParams))

OnModeChange registers a callback invoked when the mode changes.

func (*Engine) ProbeResults

func (e *Engine) ProbeResults() []ProbeResult

ProbeResults returns the latest results from active probing.

func (*Engine) SaveState

func (e *Engine) SaveState() error

SaveState writes the current engine state to the configured file.

func (*Engine) SetMode

func (e *Engine) SetMode(mode Mode)

SetMode updates the configured mode at runtime. It is safe for concurrent use.

func (*Engine) SetProbeTargets

func (e *Engine) SetProbeTargets(targets []string)

SetProbeTargets sets the server addresses to periodically check.

func (*Engine) SetStatePath

func (e *Engine) SetStatePath(path string)

SetStatePath configures the file path for automatic persistence.

func (*Engine) Start

func (e *Engine) Start()

Start begins the background decision loop.

func (*Engine) Stop

func (e *Engine) Stop()

Stop halts the background decision loop.

func (*Engine) ThreatLevel

func (e *Engine) ThreatLevel() int

ThreatLevel returns the current threat score (0-100).

func (*Engine) Tuning

func (e *Engine) Tuning() TuningParams

Tuning returns the current tuning parameters (safe for concurrent use).

type Metrics

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

Metrics is a thread-safe collector of QUIC-level network statistics. Values are updated by the transport layer via RecordRTT / RecordLoss / RecordBytes.

func NewMetrics

func NewMetrics() *Metrics

NewMetrics creates a zeroed Metrics instance.

func (*Metrics) RecordBytes

func (m *Metrics) RecordBytes(n int64)

RecordBytes records n bytes transferred for throughput calculation.

func (*Metrics) RecordPacketLost

func (m *Metrics) RecordPacketLost()

RecordPacketLost increments the lost packet counter.

func (*Metrics) RecordPacketSent

func (m *Metrics) RecordPacketSent()

RecordPacketSent increments the sent packet counter.

func (*Metrics) RecordRTT

func (m *Metrics) RecordRTT(rtt time.Duration)

RecordRTT updates the RTT exponential moving average. rtt should be the measured round-trip time for a recent packet.

func (*Metrics) Snapshot

func (m *Metrics) Snapshot() MetricsSnapshot

Snapshot returns a point-in-time view of all metrics. It refreshes the throughput window if needed.

type MetricsSnapshot

type MetricsSnapshot struct {
	RTT        time.Duration
	RTTStdDev  time.Duration
	Jitter     time.Duration
	PacketLoss float64 // [0, 1]
	Throughput int64   // bytes/sec
	SampledAt  time.Time
}

MetricsSnapshot is a point-in-time view of the collected metrics.

type Mode

type Mode uint8

Mode represents an operating mode for the HiVoid protocol.

const (
	// ModePerformance maximizes throughput, minimal overhead.
	ModePerformance Mode = iota
	// ModeStealth enables full obfuscation to avoid traffic analysis.
	ModeStealth
	// ModeBalanced balances performance and security (default).
	ModeBalanced
	// ModeAdaptive auto-switches based on network metrics.
	ModeAdaptive
)

func ModeFromString

func ModeFromString(s string) Mode

ModeFromString parses a mode name string.

func (Mode) String

func (m Mode) String() string

type ProbeResult

type ProbeResult struct {
	Target  string
	RTT     time.Duration
	Success bool
	Error   error
}

ProbeResult represents the outcome of a single active probe.

type Prober

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

Prober performs active health checks on HiVoid servers.

func NewProber

func NewProber(timeout time.Duration) *Prober

NewProber creates a Prober with the given timeout.

func (*Prober) Probe

func (p *Prober) Probe(ctx context.Context, target string) ProbeResult

Probe checks the health of a target HiVoid server using a lightweight QUIC handshake. It doesn't perform full authentication, just tests path reachability and RTT.

func (*Prober) ProbeBatch

func (p *Prober) ProbeBatch(ctx context.Context, targets []string) []ProbeResult

ProbeBatch performs concurrent probes on multiple targets. ProbeBatch checks multiple targets concurrently and returns results in the same order as input.

type State

type State uint8

State represents the detected network condition state.

const (
	StateOptimal State = iota
	StateCongested
	StateUnstable
	StateThrottled
	StateBlocked
	StateFallback
)

func (State) String

func (s State) String() string

type TuningParams

type TuningParams struct {
	// EnableObfuscation activates the obfuscation layer.
	EnableObfuscation bool
	// PaddingPct is the fraction of frames that get random padding [0,1].
	PaddingPct float64
	// MaxPaddingBytes is the maximum padding to add per frame.
	MaxPaddingBytes int
	// StreamConcurrency is the max number of concurrent QUIC streams.
	StreamConcurrency int
	// RekeyInterval controls how often keys are rotated.
	RekeyInterval time.Duration
	// RTOMultiplier scales the retransmission timeout.
	RTOMultiplier float64
}

TuningParams holds the output parameters from engine decisions. These are applied to the transport and obfuscation layers.

func DefaultTuning

func DefaultTuning() TuningParams

DefaultTuning returns sane defaults for ModeBalanced.