pool

type HeadroomPolicy struct {
	// MaxTotalCostPct is how much aggregate pool throughput may be given up to
	// protect playback. Zero — the default — means "free only": stop at the
	// knee and never trade throughput for latency, which is the safe default
	// for a deployment whose link rate is unknown.
	//
	// Setting it non-zero buys the larger win. Measured at 400 MB/s: allowing a
	// ~9% aggregate cost took stream p50 from 190ms to 146ms and p99 from 245ms
	// to 167ms — playback at 95% of its completely-unloaded speed while a full
	// import ran.
	MaxTotalCostPct int
}

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

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

type Manager interface {
	// GetPool returns the current connection pool or error if not available.
	// The returned client exposes the narrow NntpClient surface so tests can
	// substitute a fake (see internal/testsupport/fakepool). In production it
	// is backed by *nntppool.Client.
	GetPool() (NntpClient, error)

	// SetProviders creates/recreates the pool with new providers
	SetProviders(providers []nntppool.Provider) error

	// ClearPool shuts down and removes the current pool
	ClearPool() error

	// HasPool returns true if a pool is currently available
	HasPool() bool

	// GetMetrics returns the current pool metrics with calculated speeds
	GetMetrics() (MetricsSnapshot, error)

	// ResetMetrics resets specific cumulative metrics
	ResetMetrics(ctx context.Context, resetPeak bool, resetTotals bool) error

	// ResetProviderErrors zeroes all per-provider error counts without
	// affecting bytes downloaded, peak speed, or history.
	ResetProviderErrors(ctx context.Context) error

	// IncArticlesDownloaded increments the count of articles successfully downloaded
	IncArticlesDownloaded()

	// UpdateDownloadProgress updates the bytes downloaded for a specific stream
	UpdateDownloadProgress(id string, bytesDownloaded int64)

	// IncArticlesPosted increments the count of articles successfully posted
	IncArticlesPosted()

	// AddProvider adds a single provider to the running pool.
	// If no pool exists, a new one is created with this provider.
	AddProvider(provider nntppool.Provider) error

	// RemoveProvider removes a provider by its stable configuration ID.
	// If the last provider is removed, the pool is closed.
	RemoveProvider(name string) error

	// ResetProviderQuota resets the download quota counter for a provider,
	// clearing its consumed-bytes counter and exceeded flag in-place.
	ResetProviderQuota(ctx context.Context, poolName string) error

	// SetProviderIDs sets a mapping between pool names and configuration IDs.
	SetProviderIDs(mapping map[string]string)

	// AcquireImportSlot blocks until an admission slot is available for an
	// NZB import to start, or ctx is cancelled. The returned release function
	// must be called exactly once when the import has finished (success or
	// failure). When the admission cap is unconfigured (0) it is a no-op.
	AcquireImportSlot(ctx context.Context) (release func(), err error)

	// SetAdmissionCap configures the cap on concurrently running NZB imports.
	// A cap of 0 means unlimited.
	SetAdmissionCap(cap int)

	// AcquireImportConnection blocks until the global import connection
	// budget grants a token for one segment (body) fetch, or ctx is
	// cancelled. The returned release function must be called exactly once
	// when the fetch is done. No-op while the budget capacity is unset (0).
	AcquireImportConnection(ctx context.Context) (release func(), err error)

	// SetImportConnCapacity sets the import connection budget to the pool's
	// total connection count (sum of provider max connections).
	SetImportConnCapacity(total int)

	// SetStreamHeadroom sets how many connections the import budget holds back
	// per active stream. See config.Config.StreamHeadroomConnections.
	SetStreamHeadroom(perStream int)
	// SpeculativeBudget bounds read-ahead fetches across every stream; nil
	// (as returned by test fakes) means unlimited.
	SpeculativeBudget() *SpeculativeBudget

	// ImportConnCapacity returns the current budget capacity snapshot,
	// useful for sizing import worker pools.
	ImportConnCapacity() int

	// SetStreamSource wires the activity signal so the import connection
	// budget can shrink while streams are active.
	SetStreamSource(src StreamActivitySource)

	// NotifyStreamChange must be called by the stream source whenever its
	// active stream count changes, so the budget can re-evaluate.
	NotifyStreamChange()

	// StatSweepConcurrency returns how many STATs an availability sweep
	// (import fast-fail, health check) should keep in flight. While streams
	// are active it returns the caller's conservative bound — typically one
	// connection's STAT pipeline depth, so sweeps never crowd playback — and
	// on an idle pool it opens up to the pool's aggregate STAT pipeline
	// capacity (nntppool's StatCapacity), where STAT's one-line replies make
	// the extra width nearly free. Falls back to conservative when no pool
	// exists or its capacity is below the conservative bound.
	StatSweepConcurrency(conservative int) int
}

type MetricsSnapshot struct {
	BytesDownloaded             int64                            `json:"bytes_downloaded"`
	BytesUploaded               int64                            `json:"bytes_uploaded"`
	ArticlesDownloaded          int64                            `json:"articles_downloaded"`
	ArticlesPosted              int64                            `json:"articles_posted"`
	TotalErrors                 int64                            `json:"total_errors"`
	ProviderErrors              map[string]int64                 `json:"provider_errors"`
	ProviderBytes               map[string]int64                 `json:"provider_bytes"`
	ProviderBytes24h            map[string]int64                 `json:"provider_bytes_24h"`
	ProviderStartedAt           map[string]time.Time             `json:"provider_started_at"`
	ProviderQuotas              map[string]ProviderQuotaSnapshot `json:"provider_quotas,omitempty"`
	DownloadSpeedBytesPerSec    float64                          `json:"download_speed_bytes_per_sec"`
	MaxDownloadSpeedBytesPerSec float64                          `json:"max_download_speed_bytes_per_sec"`
	UploadSpeedBytesPerSec      float64                          `json:"upload_speed_bytes_per_sec"`
	Timestamp                   time.Time                        `json:"timestamp"`
	StartedAt                   time.Time                        `json:"started_at"`
	ProviderMissingRates        map[string]float64               `json:"provider_missing_rates"`
	ProviderMissingWarning      map[string]bool                  `json:"provider_missing_warning"`
	ProviderSpeeds              map[string]float64               `json:"provider_speeds"`
}

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

type NntpClient interface {
	// Fetch downloads and decodes an article body. Req.Lane selects the queue
	// (normal for imports, priority for playback reads, background for PAR2
	// repair), and Req.Writer streams the decoded bytes instead of buffering
	// them. A streamed fetch that has delivered bytes is not failed over, so
	// callers retrying it must supply a fresh writer.
	Fetch(ctx context.Context, r nntppool.Req) (*nntppool.ArticleBody, error)

	// FetchAsync is Fetch on its own goroutine; the returned channel yields
	// exactly one BodyResult. The importer uses it to overlap a segment
	// download with its own bookkeeping.
	FetchAsync(ctx context.Context, r nntppool.Req) <-chan nntppool.BodyResult

	// Exists checks whether an article is retrievable from at least one
	// provider without downloading the body. Used by health checks, import
	// validation, and the mid-stream miss re-check (which passes
	// LanePriority, since a playback read is blocked on the answer and on the
	// normal lane could spend its whole budget queued behind a large body).
	Exists(ctx context.Context, r nntppool.Req) (*nntppool.StatResult, error)

	// ExistsMany checks many articles concurrently, streaming a result per
	// message-id as each completes. Used by health checks and fast-fail import
	// validation to batch existence sweeps instead of issuing one Exists per
	// segment.
	ExistsMany(ctx context.Context, messageIDs []string, opts nntppool.ManyOptions) <-chan nntppool.ExistsResult

	// Stats returns a snapshot of pool/provider statistics used by the metrics
	// tracker and the system handlers.
	Stats() nntppool.ClientStats
}

type ProviderQuotaSnapshot struct {
	QuotaBytes    int64     `json:"quota_bytes"`
	QuotaUsed     int64     `json:"quota_used"`
	QuotaResetAt  time.Time `json:"quota_reset_at,omitempty"`
	QuotaExceeded bool      `json:"quota_exceeded"`
}

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

type StatsRepository interface {
	UpdateSystemStat(ctx context.Context, key string, value int64) error
	BatchUpdateSystemStats(ctx context.Context, stats map[string]int64) error
	MigrateSystemStats(ctx context.Context, stats map[string]int64, deleteKeys []string) error
	GetSystemStats(ctx context.Context) (map[string]int64, error)
	AddBytesDownloadedToDailyStat(ctx context.Context, bytes int64) error
	AddProviderBytesToHourlyStat(ctx context.Context, providerID string, bytes int64) error
	RecordProviderSpeedTest(ctx context.Context, providerID string, speedMbps float64) error
	GetProviderHourlyStats(ctx context.Context, hours int) (map[string]int64, error)
	ClearProviderHourlyStats(ctx context.Context) error
	GetOldestStatDate(ctx context.Context) (time.Time, error)
	GetOldestProviderStatDates(ctx context.Context) (map[string]time.Time, error)
}

type StreamActivitySource interface {
	ActiveStreams() int
}