store

type BandwidthAggregation struct {
	TransportID string `json:"transport_id"`
	Period      string `json:"period"`     // "daily", "weekly", "monthly"
	PeriodKey   string `json:"period_key"` // e.g., "2026-02-10", "2026-W06", "2026-02"
	Bandwidth   uint64 `json:"bandwidth"`  // total bytes (sent + recv)
	UpdatedAt   int64  `json:"updated_at"`
}

type BatchStore interface {
	// TouchTransports extends the lifetime of registered transports that are
	// still listed: the entry keys, and the reporter's edge index. Nothing is
	// rewritten.
	TouchTransports(ctx context.Context, reporter cipher.PubKey, ids []uuid.UUID) error
	// DeregisterTransports removes transports and returns the ones that
	// existed.
	DeregisterTransports(ctx context.Context, ids []uuid.UUID) ([]*transport.Entry, error)
	// RecordTransportHeartbeats records an uptime heartbeat for each entry.
	RecordTransportHeartbeats(ctx context.Context, entries []*transport.Entry, at time.Time) error
}

type CumulativeAggregate struct {
	Bandwidth uint64                          `json:"bandwidth,omitempty"`
	Latency   float64                         `json:"latency,omitempty"`
	ByType    map[string]*TypeMetricAggregate `json:"by_type,omitempty"`
}

type DailyAggregate struct {
	Date      string                          `json:"date"`
	Bandwidth uint64                          `json:"bandwidth,omitempty"`
	Latency   float64                         `json:"latency,omitempty"`
	ByType    map[string]*TypeMetricAggregate `json:"by_type,omitempty"`
}

type DailyBandwidthEntry struct {
	Date      string `json:"date"` // "2006-01-02"
	Bandwidth uint64 `json:"bw"`   // total bytes (sent + recv)
}

type DailyEdgeBandwidth struct {
	Date string         `json:"date"`
	A    *EdgeBandwidth `json:"a,omitempty"`
	B    *EdgeBandwidth `json:"b,omitempty"`
	// SameNetwork: an edge reported that day that the other is on its own
	// network (one IP). The bytes are real, but the reward system does not
	// pay for them.
	SameNetwork bool `json:"same_network,omitempty"`
}

type DailyVisorAggregate struct {
	Date      string                   `json:"date"`
	Bandwidth *VisorBandwidthAggregate `json:"bandwidth,omitempty"`
	Latency   float64                  `json:"latency,omitempty"`
}

type EdgeBandwidth struct {
	Sent uint64 `json:"sent"` // Cumulative bytes sent
	Recv uint64 `json:"recv"` // Cumulative bytes received
}

type LatencyRecord struct {
	Min       int64 `json:"min"` // microseconds
	Max       int64 `json:"max"` // microseconds
	Avg       int64 `json:"avg"` // microseconds
	UpdatedAt int64 `json:"updated_at"`
}

type MetricsQuery struct {
	Days      int    // 0 = all available (max 35)
	Type      string // Filter by transport type (stcpr, sudph, dmsg, stcp)
	Live      string // Filter by liveness: "true", "false", "all" (default: "all")
	Edges     bool   // Include actual public keys in response
	Bandwidth bool   // Include bandwidth data (default: true)
	Latency   bool   // Include latency data (default: true)
}

type NetworkMetricResponse struct {
	Daily      []DailyAggregate     `json:"daily"`
	Cumulative *CumulativeAggregate `json:"cumulative"`
}

type Store interface {
	TransportStore
}

type TelemetryBatchStore interface {
	ApplyTelemetry(ctx context.Context, updates []TelemetryUpdate) error
}

type TelemetryUpdate struct {
	ID                     uuid.UUID
	Reporter               cipher.PubKey
	Sent, Recv             uint64
	ThroughputBps          float64
	LatMin, LatMax, LatAvg float64
	Type                   string
	// SameNetwork: the reporter marked the peer as on its own network, so
	// the transport's bytes that day are not paid for.
	SameNetwork bool
}

type ThroughputRecord struct {
	Bps       float64 `json:"bps"`
	UpdatedAt int64   `json:"updated_at"`
}

type TransportData struct {
	ID         string `json:"id"`
	EdgeA      string `json:"edge_a"`
	EdgeB      string `json:"edge_b"`
	Type       string `json:"type"`
	Label      string `json:"label"`
	LatencyMin int64  `json:"lat_min"`     // Minimum latency in microseconds
	LatencyMax int64  `json:"lat_max"`     // Maximum latency in microseconds
	LatencyAvg int64  `json:"lat_avg"`     // Average latency in microseconds
	Bandwidth  uint64 `json:"bandwidth"`   // Total bytes (sent + recv)
	LastUpdate int64  `json:"last_update"` // Unix timestamp of last update
}

type TransportLatency struct {
	Min int64 `json:"min"` // Minimum observed latency in microseconds
	Max int64 `json:"max"` // Maximum observed latency in microseconds
	Avg int64 `json:"avg"` // Average latency in microseconds
}

type TransportMetric struct {
	ID      string               `json:"id"`
	Type    string               `json:"type"`
	Live    bool                 `json:"live"`
	Edges   []string             `json:"edges,omitempty"`   // Only included if query.Edges=true
	Latency *TransportLatency    `json:"latency,omitempty"` // Transport-level latency stats
	Daily   []DailyEdgeBandwidth `json:"daily"`             // Per-day bandwidth by edge
}

type TransportStore interface {
	// RegisterTransport registers/refreshes a transport. reporter is the
	// authenticated registering edge: only that edge's per-edge index TTL is
	// refreshed, so an offline edge's index expires even while its live peer
	// keeps re-registering the shared transport. A zero reporter (or one that
	// is not an edge) falls back to refreshing both edges (legacy behavior).
	RegisterTransport(context.Context, cipher.PubKey, *transport.SignedEntry) error
	RegisterTransportsBatch(context.Context, cipher.PubKey, []*transport.SignedEntry) error
	DeregisterTransport(context.Context, uuid.UUID) error
	GetTransportByID(context.Context, uuid.UUID) (*transport.Entry, error)
	GetTransportsByEdge(context.Context, cipher.PubKey) ([]*transport.Entry, error)
	// GetTransportsByEdgeNoLatency is the cheap variant for callers
	// (DHT mirror, transport-count stats) that don't need the
	// durable latency overlay. Skips the per-call MGET on lat:<id>
	// keys and the JSON decode that follows.
	GetTransportsByEdgeNoLatency(context.Context, cipher.PubKey) ([]*transport.Entry, error)
	GetNumberOfTransports(context.Context) (map[types.Type]int, error)
	// GetTransportSummary returns network-wide aggregate counts (total,
	// per-type, unique visors) computed in a single index+MGET pass that
	// never materializes []*transport.Entry — the cheap path behind GET
	// /all-transports/stats, so a client counting transports doesn't have
	// to fetch every entry. selfTransports=false excludes loopback
	// self-transports (Edges[0]==Edges[1]), matching GetAllTransports.
	GetTransportSummary(ctx context.Context, selfTransports bool) (*TransportSummary, error)
	GetAllTransports(context.Context, bool) ([]*transport.Entry, error)
	// Bandwidth ingest (called by the CXO aggregator with the
	// reporter's cumulative counters; deltas are computed
	// internally against the per-reporter previous snapshot).
	UpdateBandwidth(ctx context.Context, transportID string, reporterPK cipher.PubKey, sent, recv uint64, tpType string) error
	// Latency ingest (called by the CXO aggregator with the
	// reporter's window min/max/avg in milliseconds). RTT-symmetric,
	// so last-writer-wins across the two edges is acceptable.
	UpdateLatency(ctx context.Context, transportID string, minMS, maxMS, avgMS float64, tpType string) error
	// Throughput ingest (called by the CXO aggregator with the
	// reporter's passively-observed PEAK goodput estimate in bytes/sec,
	// carried on the sharded telemetry feed). Recorded per-transport with
	// a peak-preserving max so the higher of the two edges' observations
	// survives; overlaid onto Entry.ThroughputBps on read.
	UpdateThroughput(ctx context.Context, transportID string, reporterPK cipher.PubKey, bps float64) error
	// Bandwidth query methods (legacy)
	GetTransportBandwidth(ctx context.Context, tpID uuid.UUID, period string, limit int) ([]BandwidthAggregation, error)
	GetVisorBandwidth(ctx context.Context, pk cipher.PubKey, period string, limit int) ([]BandwidthAggregation, error)
	GetAllVisorSummaries(ctx context.Context, v2 bool, timeline bool) ([]VisorSummary, error)
	RecordHeartbeat(ctx context.Context, pk cipher.PubKey, version string) error
	GetDailyTimeline(ctx context.Context, pkHex string, now time.Time) map[string]string
	// Transport uptime tracking (stcpr/sudph only).
	// at is the time the heartbeat was *observed* on the visor side
	// (snap.SampledAt for the CXO path, time.Now() for the HTTP
	// register path); the slot bit and date bucket derive from it,
	// so leaf-arrival skew that crosses a 5-minute boundary still
	// credits the correct slot. Zero time falls back to time.Now().
	RecordTransportHeartbeat(ctx context.Context, tpID uuid.UUID, tpType string, at time.Time) error
	// IngestTransportTimeline OR-merges a visor-supplied per-transport
	// uptime bitmap into the persistent timeline. Used by the CXO
	// aggregator to absorb the visor's locally-tracked bitmap, which
	// captures slots TPD's heartbeat path never observed (e.g.
	// during TPD downtime). bitmap must be 36 bytes; date is the
	// UTC YYYY-MM-DD the bitmap covers.
	IngestTransportTimeline(ctx context.Context, tpID uuid.UUID, date string, bitmap []byte) error
	GetTransportUptimeSummaries(ctx context.Context, tpIDs []uuid.UUID, v2 bool, timeline bool) ([]TransportUptimeSummary, error)
	GetTransportUptimeByVisor(ctx context.Context, pk cipher.PubKey, v2 bool, timeline bool) ([]TransportUptimeSummary, error)
	GetTransportDailyTimeline(ctx context.Context, tpID string, now time.Time) map[string]string
	BackupAndCleanOldBandwidth(ctx context.Context, backupPath string) error
	// New metrics methods
	GetNetworkMetrics(ctx context.Context, query MetricsQuery) (*NetworkMetricResponse, error)
	GetVisorAggregateMetrics(ctx context.Context, pks []cipher.PubKey, query MetricsQuery) (map[string]*VisorMetricResponse, error)
	GetAllTransportMetrics(ctx context.Context, query MetricsQuery) ([]TransportMetric, error)
	GetTransportMetricsByIDs(ctx context.Context, ids []uuid.UUID, query MetricsQuery) ([]TransportMetric, error)
	GetTransportMetricsByVisors(ctx context.Context, pks []cipher.PubKey, query MetricsQuery) ([]TransportMetric, error)
	Close()
}

type TransportSummary struct {
	Total        int            `json:"total_transports"`
	ByType       map[string]int `json:"by_type"`
	UniqueVisors int            `json:"unique_visors"`

	// Partial reports that at least one batch of the underlying read failed,
	// so Total and ByType undercount by an unknown amount.
	//
	// This exists because the counts are assembled from batched MGETs over the
	// transport index, and a failed batch used to be skipped with a bare
	// `continue` — silently removing up to mgetBatch transports from the
	// answer while still returning a plausible-looking number. A consumer had
	// no way to tell "there are N transports" from "N is what I managed to
	// read", which is indistinguishable from the network shrinking.
	//
	// Callers that publish or chart these numbers must treat Partial as
	// "do not trust this sample" rather than as data.
	Partial bool `json:"partial,omitempty"`
	// MissingBatches counts the failed batches, for logging and for judging
	// how far off Total might be.
	MissingBatches int `json:"missing_batches,omitempty"`
}

type TransportUptimeSummary struct {
	ID       uuid.UUID         `json:"id"`
	Online   bool              `json:"on"`
	Type     string            `json:"type,omitempty"`
	EdgeA    string            `json:"edge_a,omitempty"`
	EdgeB    string            `json:"edge_b,omitempty"`
	Daily    map[string]string `json:"daily,omitempty"`
	Timeline map[string]string `json:"timeline,omitempty"`
}

type TypeMetricAggregate struct {
	Bandwidth uint64  `json:"bandwidth,omitempty"`
	Latency   float64 `json:"latency,omitempty"`
}

type VisorBWDay struct {
	Version int    `json:"version"`
	Date    string `json:"date"`
	// Transports is how many transports moved bytes that day, and
	// SameNetworkExcluded how many of them were left out because an edge
	// marked the other as on its own network.
	Transports          int `json:"transports"`
	SameNetworkExcluded int `json:"same_network_excluded"`
	// Visors maps a visor's public key (hex) to the bytes it sent that day,
	// by transport type.
	Visors map[string]map[string]uint64 `json:"visors"`
}

type VisorBandwidthAggregate struct {
	Sent  uint64 `json:"sent"`
	Recv  uint64 `json:"recv"`
	Total uint64 `json:"total"`
}

type VisorCumulativeAggregate struct {
	Bandwidth *VisorBandwidthAggregate `json:"bandwidth,omitempty"`
	Latency   float64                  `json:"latency,omitempty"`
}

type VisorMetricResponse struct {
	Daily      []DailyVisorAggregate     `json:"daily"`
	Cumulative *VisorCumulativeAggregate `json:"cumulative"`
}

type VisorSummary struct {
	PK       cipher.PubKey     `json:"pk"`
	Online   bool              `json:"on"`
	Version  string            `json:"version,omitempty"`
	Daily    map[string]string `json:"daily,omitempty"`
	Timeline map[string]string `json:"timeline,omitempty"`
}