Documentation
¶
Overview ¶
Package proxypool adapts the proxypool library to router policy and storage.
Index ¶
- Variables
- func EnsureBuiltinFreePool(ctx context.Context, database *db.Database) error
- func TransportFor(proxyURL string, timeout time.Duration) (*http.Transport, error)
- type Candidate
- type DemandStat
- type LaneStat
- type NetStatus
- type Proxy
- type Service
- func (s *Service) AdmitProxyURL(ctx context.Context, proxyURL string) error
- func (s *Service) ApplyConfiguration(configuration models.RouterConfiguration) error
- func (s *Service) ClearData(ctx context.Context) error
- func (s *Service) DataCounts(ctx context.Context) (pools, proxies int, err error)
- func (s *Service) DeleteCustomPool(ctx context.Context, identifier string) error
- func (s *Service) ExportData(ctx context.Context) (*models.ProxyDataBundle, error)
- func (s *Service) ForceForeground() int
- func (s *Service) Get(id string) (*Proxy, error)
- func (s *Service) ImportData(ctx context.Context, bundle *models.ProxyDataBundle) error
- func (s *Service) KnownIDs() ([]string, error)
- func (s *Service) List() ([]*Proxy, error)
- func (s *Service) ListCustomPools(ctx context.Context) ([]*models.CustomProxyPool, error)
- func (s *Service) MarkDead(proxyURL, reason string) bool
- func (s *Service) Query(pool, country string, limit int) ([]models.ProxyView, error)
- func (s *Service) RecheckBanned(reason, source string) (int, error)
- func (s *Service) RequestIngest() bool
- func (s *Service) Require(ctx context.Context, request models.ProxyRequire) (models.ProxyRequireResult, error)
- func (s *Service) SaveCustomPool(ctx context.Context, pool *models.CustomProxyPool) (*models.CustomProxyPool, error)
- func (s *Service) SetLogger(logger *slog.Logger)
- func (s *Service) SetMaxChecks(maxChecks int) error
- func (s *Service) SetSourceHandlers(keys func() ([]string, error), ...)
- func (s *Service) SourceInfos() []SourceInfo
- func (s *Service) Start(ctx context.Context)
- func (s *Service) Status() (Status, error)
- type SourceInfo
- type SourceStat
- type Status
Constants ¶
This section is empty.
Variables ¶
var ( ErrNoProxies = errors.New("proxy pool has no usable proxy") ErrInvalidBanReason = errors.New("invalid proxy ban reason") )
var ErrProxyNotAdmitted = errors.New("proxy URL is not held by any router pool")
ErrProxyNotAdmitted reports a proxy URL that no router pool holds.
Functions ¶
func EnsureBuiltinFreePool ¶ added in v0.4.0
EnsureBuiltinFreePool inserts the built-in free-pool row when missing. Existing rows stay untouched: reruns never rewrite timestamps. Call it wherever provider rows with proxy references write without the proxypool service in the stack; server wiring seeds it through New.
func TransportFor ¶
TransportFor builds an HTTP transport for a library-supported proxy URL (http/https/socks4/socks5, with optional userinfo credentials). Dialing lives in the proxypool library; this wrapper keeps the router-internal call boundary stable.
Types ¶
type Candidate ¶ added in v0.3.8
Candidate is one proxy endpoint produced by a Lua proxy-source feed.
type DemandStat ¶ added in v0.3.8
type DemandStat struct {
Countries []string `json:"countries"`
State string `json:"state"`
Waiters int `json:"waiters"`
Alive int `json:"alive"`
Target int `json:"target"`
Served int64 `json:"served"`
CreatedAt time.Time `json:"created_at,omitempty"`
ExpiresAt time.Time `json:"expires_at,omitempty"`
ReplenishUntil time.Time `json:"replenish_until,omitempty"`
LastSatisfiedAt time.Time `json:"last_satisfied_at,omitempty"`
}
DemandStat reports one registered country demand.
type Proxy ¶ added in v0.3.7
type Proxy struct {
ID string `json:"id"`
URL string `json:"url"`
Location string `json:"location"`
Latency time.Duration `json:"latency"`
Score float64 `json:"score"`
LastChecked time.Time `json:"last_checked"`
}
Proxy is the stable router-facing view of a validated library entry.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service owns the adapter boundary, persistence and pool lifecycle. Proxy health and lifecycle remain in the proxypool library. Provider request routing never consults this service: plugins select proxies through Query and assign proxy_url per request.
func New ¶
New constructs the library-backed pool and restores its persistent cache from SQLite. The built-in free-pool row seeds idempotently into the durable database so provider proxy references to "auto" satisfy the foreign key; proxy states load from the cache file.
func (*Service) AdmitProxyURL ¶ added in v0.6.9
AdmitProxyURL accepts a plugin proxy_url only when a router pool holds it: the free pool cache (public candidates only) or a custom pool entry (operator-configured, so private addresses there stay valid).
func (*Service) ApplyConfiguration ¶ added in v0.4.2
func (s *Service) ApplyConfiguration(configuration models.RouterConfiguration) error
ApplyConfiguration applies the proxy fields of a saved router configuration. Nil fields keep the current value. Switching discovery on or off happens in the background so the caller never waits for in-flight checks to finish.
func (*Service) ClearData ¶ added in v0.4.2
ClearData deletes every manual pool and every discovered proxy with its queues. The switches and the check cap stay. Pools that providers still reference survive and are reported in the error.
func (*Service) DataCounts ¶ added in v0.4.2
DataCounts reports the number of manual pools and healthy discovered proxies for the data management overview.
func (*Service) DeleteCustomPool ¶ added in v0.3.8
DeleteCustomPool removes a custom pool by ID. Entries cascade from the pool foreign key. Built-in rows refuse: the free pool is not custom. A zero-row delete reports the not-found sentinel.
func (*Service) ExportData ¶ added in v0.4.2
ExportData packages the switches, the manual pools and the healthy discovered proxies.
func (*Service) ForceForeground ¶ added in v0.4.2
ForceForeground makes candidate checks run at foreground speed until the candidate queue is drained. It returns the number of queued candidates; zero means nothing was started (empty queue or pool not running).
func (*Service) ImportData ¶ added in v0.4.2
ImportData restores manual pools, the switches and the check cap, and queues the exported proxies for a fresh check. Existing pools with the same ID are replaced. Proxies are never trusted as healthy: they join the candidate queue on the next ingest, which runs now when discovery is on.
func (*Service) KnownIDs ¶ added in v0.3.7
KnownIDs returns IDs for all cached proxies, including dead entries.
func (*Service) ListCustomPools ¶ added in v0.3.8
ListCustomPools returns every manually managed proxy pool by name order. Built-in rows (the free pool) stay out: they are not custom pools.
func (*Service) MarkDead ¶ added in v0.3.8
MarkDead applies the router failure mapping before updating proxy health.
func (*Service) Query ¶ added in v0.3.8
Query returns proxy endpoints for plugin selection. Pool "auto" reads the library free pool in rank order; empty pool means direct and returns no endpoints; any other name reads a custom pool by ID or name. Country filters case-insensitively; limit caps the result (<=0 means all).
func (*Service) RecheckBanned ¶ added in v0.3.8
RecheckBanned queues manual rechecks for banned proxies matching the filters.
func (*Service) RequestIngest ¶ added in v0.3.8
RequestIngest requests an immediate source ingest when the service is running.
func (*Service) Require ¶ added in v0.3.8
func (s *Service) Require(ctx context.Context, request models.ProxyRequire) (models.ProxyRequireResult, error)
Require serves proxies.require. The free pool waits for a matching live proxy up to request.Timeout; an empty pool means direct; a custom pool answers from its own entries without waiting.
func (*Service) SaveCustomPool ¶ added in v0.3.8
func (s *Service) SaveCustomPool(ctx context.Context, pool *models.CustomProxyPool) (*models.CustomProxyPool, error)
SaveCustomPool creates or replaces a custom pool. IDs are slugified from the name when empty; entries with empty URLs are dropped. One transaction holds the pool upsert, the entry wipe, and the entry inserts on the transaction handle only.
func (*Service) SetMaxChecks ¶ added in v0.4.2
SetMaxChecks applies the operator cap on parallel proxy checks. Zero restores the adaptive default range. It does not persist the value.
func (*Service) SetSourceHandlers ¶ added in v0.3.7
func (s *Service) SetSourceHandlers(keys func() ([]string, error), fetch func(context.Context, string) ([]Candidate, error))
SetSourceHandlers connects registered Lua proxy-source feeds.
func (*Service) SourceInfos ¶ added in v0.0.5
func (s *Service) SourceInfos() []SourceInfo
SourceInfos returns last-fetch diagnostics for currently registered feeds.
type SourceInfo ¶ added in v0.0.5
type SourceInfo struct {
Key string `json:"key"`
Name string `json:"name"`
LastFetchAt time.Time `json:"last_fetch_at,omitempty"`
Total int `json:"total"`
Unsupported int `json:"unsupported"`
LastError string `json:"last_error,omitempty"`
}
SourceInfo reports feed diagnostics for registered Lua proxy sources.
type SourceStat ¶ added in v0.3.8
type Status ¶ added in v0.3.7
type Status struct {
Mode string `json:"mode"`
Net NetStatus `json:"net"`
Limit int `json:"limit"`
Inflight int `json:"inflight"`
Total int `json:"total"`
Alive int `json:"alive"`
Suspect int `json:"suspect"`
Banned int `json:"banned"`
Queued int `json:"queued"`
Lanes []LaneStat `json:"lanes"`
Sources []SourceStat `json:"sources"`
BanReasons map[string]int `json:"ban_reasons"`
Demands []DemandStat `json:"demands"`
LastIngestAt time.Time `json:"last_ingest_at,omitempty"`
LastError string `json:"last_error,omitempty"`
// ForcedForeground is true while a manual force speeds up candidate checks.
ForcedForeground bool `json:"forced_foreground"`
// Enabled is the proxy subsystem switch; PoolEnabled is the free pool
// switch. Discovery runs only while both are on.
Enabled bool `json:"enabled"`
PoolEnabled bool `json:"pool_enabled"`
}