usenet

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

type Conn struct {

	// PostingAllowed reports a 200 (vs 201) greeting.
	PostingAllowed bool
	// Greeting is the server's welcome text.
	Greeting string
	// contains filtered or unexported fields
}

type DialOptions struct {
	Host     string
	Port     int // 0 = 563 with TLS, 119 without
	TLS      bool
	Username string
	Password string
	// TLSConfig is the base TLS configuration (e.g. custom roots in tests).
	// ServerName defaults to Host.
	TLSConfig *tls.Config
	// Timeout bounds dial, TLS handshake, greeting and authentication.
	Timeout time.Duration
	// CommandTimeout bounds each command including reading its response.
	CommandTimeout time.Duration
	// IdleReadTimeout bounds a stalled read; progress renews it. Negative disables.
	IdleReadTimeout time.Duration
	// DialContext overrides the network dialer.
	DialContext func(ctx context.Context, network, addr string) (net.Conn, error)
	// BytesRead, when set, is incremented with every byte read off the wire.
	BytesRead *atomic.Int64
	// OnPhase receives durations for tcp, tls, greeting, and auth setup phases.
	OnPhase func(string, time.Duration)
	// OnStatus receives the raw server status line for trace diagnostics.
	OnStatus func(string)
	// OnCommand receives a protocol command before it is sent. AUTHINFO
	// credentials are redacted so trace logging cannot expose them.
	OnCommand func(string)
}

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

type Options struct {
	// BodyPipelineDepth bounds queued BODY commands per socket (default 4,
	// maximum 16). One disables pipelining. Readahead normally uses at most two,
	// with a reserved live connection; explicit short bursts can borrow idle
	// capacity and use this depth. Prefetch, recovery probes and single-connection readahead
	// use one. Speculative batches stop growing when live work waits.
	BodyPipelineDepth int
	Logger            *slog.Logger
	// PrefetchFraction is the share of each provider's connections that
	// PriorityPrefetch requests may hold at once (at least one).
	PrefetchFraction float64
	// DialTimeout bounds connect + TLS + greeting + login.
	DialTimeout time.Duration
	// CommandTimeout bounds one command, including reading an article body.
	CommandTimeout time.Duration
	// IdleReadTimeout bounds stalled command/body reads; default 5 seconds.
	IdleReadTimeout time.Duration
	// MinIdle keeps this many primary (non-backfill) connections per
	// provider warm at all times: established in the background, held
	// past IdleTimeout and DATE-pinged so Play never pays a cold dial.
	// 0 = DefaultMinIdle; negative disables. A provider's own
	// config.UsenetProvider.MinIdle overrides it.
	MinIdle int
	// IdleTimeout closes excess connections unused for this long.
	IdleTimeout time.Duration
	// KeepAlive pings (DATE) connections idle for this long so servers do not
	// drop them; negative disables pings.
	KeepAlive time.Duration
	// MissTTL is how long a 430 from a provider is remembered per article;
	// negative disables the miss cache.
	MissTTL       time.Duration
	MissCacheSize int
	// Retries is how many extra attempts a provider gets, each on another
	// connection, after transient (network/protocol) errors.
	Retries int
	// Circuit breaker: after FailThreshold consecutive failed connects a
	// provider is skipped for BackoffMin, doubling up to BackoffMax.
	BackoffMin    time.Duration
	BackoffMax    time.Duration
	FailThreshold int
	// AuthRetryMin/Max: a provider that rejected the credentials (481/482)
	// is re-probed with one login after AuthRetryMin, doubling per failed
	// probe up to AuthRetryMax, so transient auth outages self-heal.
	AuthRetryMin time.Duration
	AuthRetryMax time.Duration
	// LimitCooloff: when a server refuses connections beyond some number
	// while others work, the pool shrinks to that number for this long.
	LimitCooloff time.Duration
	// TLSConfig is the base TLS client configuration (custom roots, e.g. in
	// tests). Nil uses the system roots.
	TLSConfig *tls.Config
	// DialContext overrides the network dialer.
	DialContext func(ctx context.Context, network, addr string) (net.Conn, error)
	// UseGroup issues GROUP (first of the segment's groups) before BODY. Most
	// providers serve BODY <message-id> without it.
	UseGroup bool
	// MaxArticleSize caps a decoded article; 0 = yenc.DefaultMaxSize.
	MaxArticleSize int64
	// TraceProtocol emits raw NNTP status lines at debug level.
	TraceProtocol bool
}

type ProtocolError struct {
	Cmd  string // command verb, e.g. "BODY"
	Code int
	Msg  string
}

type ProviderError struct {
	Kind    string
	Message string
	Err     error // underlying error
}

type ProviderStats struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Host     string `json:"host"`
	Priority int    `json:"priority"`
	Backfill bool   `json:"backfill"`

	// State is StateOK, StateBackoff or StateAuthFail.
	State        string    `json:"state"`
	BackoffUntil time.Time `json:"backoffUntil,omitempty"`
	LastError    string    `json:"lastError,omitempty"`
	LastErrorAt  time.Time `json:"lastErrorAt,omitempty"`

	// MaxConnections is the effective limit; it drops below
	// ConfiguredConnections for a while when the server refuses more.
	MaxConnections        int `json:"maxConnections"`
	ConfiguredConnections int `json:"configuredConnections"`
	LiveConnections       int `json:"liveConnections"`   // open sockets
	ActiveConnections     int `json:"activeConnections"` // slots in use
	IdleConnections       int `json:"idleConnections"`
	// MinIdle is the configured warm floor (0 = none for this pool);
	// WarmIdleConnections is how much of it is currently held idle.
	MinIdle             int   `json:"minIdle"`
	WarmIdleConnections int   `json:"warmIdleConnections"`
	BackgroundRedials   int64 `json:"backgroundRedials"` // floor janitor dials
	RedialFailures      int64 `json:"redialFailures"`
	PrefetchActive      int   `json:"prefetchActive"`
	WaitingLive         int   `json:"waitingLive"`
	WaitingReadahead    int   `json:"waitingReadahead"`
	WaitingPrefetch     int   `json:"waitingPrefetch"`
	// NodeShare is this node's part of ConfiguredConnections when the
	// account's connections are divided among cluster nodes (0 otherwise).
	NodeShare int `json:"nodeShare,omitempty"`

	Bytes         int64 `json:"bytes"` // received off the wire
	Articles      int64 `json:"articles"`
	Misses        int64 `json:"misses"`
	BodyMisses    int64 `json:"bodyMisses"`    // BODY responses unavailable on this provider
	BodyTakedowns int64 `json:"bodyTakedowns"` // subset of BodyMisses with status 451
	BackfillSaves int64 `json:"backfillSaves"` // body fetches saved after earlier provider misses
	Errors        int64 `json:"errors"`
	Dials         int64 `json:"dials"`

	AvgLatency       time.Duration `json:"avgLatency"`   // command round trip (EWMA)
	AvgFetchTime     time.Duration `json:"avgFetchTime"` // whole article (EWMA)
	TCPDialTime      time.Duration `json:"tcpDialTime"`
	TLSHandshakeTime time.Duration `json:"tlsHandshakeTime"`
	GreetingTime     time.Duration `json:"greetingTime"`
	AuthTime         time.Duration `json:"authTime"`
	BODYBatches      int64         `json:"bodyBatches"`
	BODYPipelined    int64         `json:"bodyPipelined"`
	STATBatches      int64         `json:"statBatches"`
	STATBatchTime    time.Duration `json:"statBatchTime"`
}