data

type Circuit struct {
	Code         string `json:"code"`
	OriginDevice Device `json:"origin_device"`
	TargetDevice Device `json:"target_device"`
	Link         Link   `json:"link"`
}

type CircuitLatencySample struct {
	Timestamp string `json:"timestamp"`
	RTT       uint32 `json:"rtt"`
}

type CircuitLatencyStat struct {
	Circuit   string `json:"circuit"`
	Timestamp string `json:"timestamp"` // Start timestamp of the window this stat represents, in RFC3339 format.

	// RTT metrics (in microseconds)
	RTTMean     float64 `json:"rtt_mean"`     // Arithmetic mean of all successful round-trip times (RTTs); overall latency average.
	RTTMedian   float64 `json:"rtt_median"`   // Median RTT; more robust to outliers than the mean.
	RTTMin      float64 `json:"rtt_min"`      // Minimum observed RTT in the window; represents best-case latency.
	RTTMax      float64 `json:"rtt_max"`      // Maximum observed RTT; reflects outliers or transient spikes.
	RTTP95      float64 `json:"rtt_p95"`      // 95th percentile RTT; indicates tail latency for most users.
	RTTP99      float64 `json:"rtt_p99"`      // 99th percentile RTT; captures rare extreme latency events.
	RTTStdDev   float64 `json:"rtt_stddev"`   // Standard deviation of RTTs; reflects latency variability over the window.
	RTTVariance float64 `json:"rtt_variance"` // Variance of RTTs (square of RTTStdDev); useful in modeling or advanced analysis.
	RTTMAD      float64 `json:"rtt_mad"`      // Mean absolute deviation of RTTs; measures deviation from the mean.

	// Jitter metrics (in microseconds)
	JitterAvg         float64 `json:"jitter_avg"`          // Average jitter between packets (IPDV mean); commonly reported as "jitter" in network systems.
	JitterEWMA        float64 `json:"jitter_ewma"`         // Smoothed jitter (RFC3550): exponentially-weighted moving average of per-packet RTT deltas.
	JitterDeltaStdDev float64 `json:"jitter_delta_stddev"` // Stddev of inter-packet RTT deltas (IPDV); measures jitter burstiness.
	JitterPeakToPeak  float64 `json:"jitter_peak_to_peak"` // Max-min RTT spread; worst-case jitter window.
	JitterMax         float64 `json:"jitter_max"`          // Maximum inter-packet jitter observed (max of |RTT[i] - RTT[i-1]|)

	// Success/failure counts and ratios
	SuccessCount uint64  `json:"success_count"` // Number of RTT samples with a valid (positive) value; successful responses.
	SuccessRate  float64 `json:"success_rate"`  // Proportion of successful responses out of total samples.
	LossCount    uint64  `json:"loss_count"`    // Number of RTT samples with zero/missing values; interpreted as loss or timeout.
	LossRate     float64 `json:"loss_rate"`     // Proportion of lost packets out of total samples.
}

type Device struct {
	PK       solana.PublicKey `json:"pk"`
	Code     string           `json:"code"`
	Location Location         `json:"location"`
}

type Link struct {
	PK   solana.PublicKey `json:"pk"`
	Code string           `json:"code"`
}

type Location struct {
	PK        solana.PublicKey `json:"pk"`
	Name      string           `json:"name"`
	Country   string           `json:"country"`
	Latitude  float64          `json:"latitude"`
	Longitude float64          `json:"longitude"`
}

type Provider interface {
	GetCircuits(ctx context.Context) ([]Circuit, error)
	GetCircuitLatencies(ctx context.Context, circuitCode string, from, to time.Time) ([]CircuitLatencySample, error)
	GetCircuitLatenciesDownsampled(ctx context.Context, circuitCode string, from, to time.Time, maxPoints uint64, unit Unit) ([]CircuitLatencyStat, error)
	GetCircuitLatenciesForEpoch(ctx context.Context, circuitCode string, epoch uint64) ([]CircuitLatencySample, error)
}

type ProviderConfig struct {
	Logger               *slog.Logger
	ServiceabilityClient ServiceabilityClient
	TelemetryClient      TelemetryClient

	CircuitsCacheTTL               time.Duration
	HistoricEpochLatenciesCacheTTL time.Duration
	CurrentEpochLatenciesCacheTTL  time.Duration
	GetCircuitLatenciesPoolSize    int
}

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

type ServiceabilityClient interface {
	GetProgramData(ctx context.Context) (*serviceability.ProgramData, error)
}

type TelemetryClient interface {
	GetDeviceLatencySamples(ctx context.Context, originDevicePubKey, targetDevicePubKey, linkPubKey solana.PublicKey, epoch uint64) (*telemetry.DeviceLatencySamples, error)
}

type Unit string