Documentation
¶
Overview ¶
Package proxypool implements the proxy pool service.
Responsibilities:
- Storage of manual and list-sourced proxies
- Health checks with immediate culling of dead list-sourced entries
- Per-provider health memory (a proxy region-locked by one provider may still work for others)
- Best-proxy selection given plugin location preferences
Index ¶
- Constants
- Variables
- func DetectExitCountry(ctx context.Context, proxyURL string) (string, error)
- func ListSource(typeKey string) string
- func NormalizeCountryCode(raw string) string
- func ParseProxyMode(providerConfig map[string]any) (mode string, ids []string)
- func ResolveProxy(s *Service, mode string, ids []string, location string, forceOnMismatch bool, ...) (proxyID, proxyURL string, err error)
- func TransportFor(proxyURL string, timeout time.Duration) (*http.Transport, error)
- type Service
- func (s *Service) AddManual(rawURL, country string) (*models.Proxy, error)
- func (s *Service) Check(ctx context.Context, id string) (*models.Proxy, error)
- func (s *Service) CheckAll(ctx context.Context)
- func (s *Service) Delete(id string) error
- func (s *Service) Get(id string) (*models.Proxy, error)
- func (s *Service) List() ([]*models.Proxy, error)
- func (s *Service) RecordOutcome(proxyID, providerType string, ok bool, latencyMs int64)
- func (s *Service) Select(prefs models.ProxyPreferences, providerType string) *models.Proxy
- func (s *Service) SelectManual(ids []string, providerType string) *models.Proxy
- func (s *Service) SyncFromSource(sourceKey string, candidates []models.ProxyCandidate) (int, error)
Constants ¶
const ManualSource = "manual"
ManualSource marks user-registered proxies.
Variables ¶
var ErrProxyPoolExhausted = errors.New("proxy pool exhausted")
ErrProxyPoolExhausted reports that every pooled proxy failed for one request; the wrapped cause is the last attempt's error.
Functions ¶
func DetectExitCountry ¶
DetectExitCountry resolves the country a proxyegresses from by querying the detection endpoint through the proxy. It reports ground truth for the exit IP; list-supplied country metadata is only a seed value. A probe failure returns an error and the caller keeps the stored value.
func ListSource ¶
ListSource builds the source tag for a list plugin.
func NormalizeCountryCode ¶
NormalizeCountryCode canonicalizes a country code to uppercase ISO 3166-1 alpha-2. Alpha-3 input maps through the ISO table; anything else passes through uppercased so selection never mismatches on case alone.
func ParseProxyMode ¶
ParseProxyMode reads the provider-level proxy config from ProviderInstance.Config. Unknown shapes fall back to disabled.
func ResolveProxy ¶
func ResolveProxy(s *Service, mode string, ids []string, location string, forceOnMismatch bool, serverCountry, providerType string) (proxyID, proxyURL string, err error)
ResolveProxy picks the pool proxy for one provider call and reports it as (id, url). It returns ("", "", nil) when the call goes direct: proxying disabled, or auto mode with no usable proxy pooled. A nil proxy is a legitimate direct route, never a silent fallback: every explicit proxy demand that cannot be satisfied (manual pick, forced exit with an empty pool) fails loudly instead.
The plugin's preferred location is a preference, never a gate: matching proxies lead the ranking, others follow, and the retry layer falls through them when the upstream rejects one.
Types ¶
type Service ¶
type Service struct {
// CheckURL is the lightweight endpoint used for generic health checks.
CheckURL string
// DialTimeout bounds a single health-check dial.
DialTimeout time.Duration
// contains filtered or unexported fields
}
Service manages the proxy pool.
func (*Service) Check ¶
Check probes one proxy through the generic check URL and records the outcome. Dead list-sourced proxies are culled immediately; manual entries are kept but marked not alive.
func (*Service) CheckAll ¶
CheckAll probes every pooled proxy with a bounded worker pool. Geo detection rides along inside Check; both run checkConcurrency-wide.
func (*Service) RecordOutcome ¶
RecordOutcome stores per-provider health after a real routed request.
func (*Service) Select ¶
Select returns the best proxy for a provider given plugin preferences. Ranking: the freshest known-good proxy for this provider (sticky — repeat traffic keeps one working exit instead of re-walking the pool) > location match > known-good > latency. A proxy known-bad for this provider is demoted, never excluded: it stays a fallback when nothing better is pooled.
func (*Service) SelectManual ¶
SelectManual returns the first alive proxy from the given IDs. Proxies known-bad for this provider sink to the end of the order instead of being skipped: an explicit manual pick is still honored when nothing better answers.
func (*Service) SyncFromSource ¶
SyncFromSource replaces all list-sourced entries of one source with the fresh candidates. Health memory survives for proxies present in both sets.