proxytron

func (Config) Enabled ¶

func (c Config) Enabled() bool

Enabled reports whether static routes or discovery are configured.

func (Config) Validate ¶

func (c Config) Validate() error

Validate checks scheduling, selection and cooldown settings.

func (DeadlineConn) Read ¶

func (c DeadlineConn) Read(p []byte) (int, error)

Read reads from Conn under a read deadline Timeout from now.

func (DeadlineConn) Write ¶

func (c DeadlineConn) Write(p []byte) (int, error)

Write writes to Conn under a write deadline Timeout from now.

func (Detector) Compare ¶

func (d Detector) Compare(ctx context.Context, endpoint string) (EgressComparison, error)

Compare explicitly probes both Direct and endpoint, failing if either fails.

func (Detector) Detect ¶

func (d Detector) Detect(ctx context.Context, endpoint string) (Egress, error)

Detect measures the route's externally observed IPv4 or IPv6 address. Replies are bounded to 4 KiB; malformed, ambiguous and unspecified addresses fail.

func (Dialer) DialContext ¶

func (d Dialer) DialContext(ctx context.Context, network, address string) (conn net.Conn, err error)

DialContext opens a TCP stream through HTTP CONNECT or SOCKS. An empty ProxyURL or Direct selects a direct connection. SOCKS5 resolves locally; SOCKS5h and SOCKS4a resolve at the proxy. Context cancellation closes a connection still negotiating, and successful connections have no deadlines.

func (EgressComparison) SameIP ¶

func (c EgressComparison) SameIP() bool

SameIP reports that the proxy and direct connection used the same exit IP.

func (*Live) Close ¶

func (l *Live) Close() error

Close closes the live pool's database, if one is attached, and drops the pool; a later Pool builds a new one. It waits for a refresh in progress. Closing a nil Live does nothing.

func (*Live) Current ¶

func (l *Live) Current() *Pool

Current is the live pool as it stands, nil before the first Pool or Override (and for a nil Live). It never waits for a refresh in progress: it is what the status endpoints read.

func (*Live) Override ¶

func (l *Live) Override(ctx context.Context, urls []string, cfg *Config, marketplaces []string) (*Pool, error)

Override replaces the live pool's endpoints with urls right now, from outside a pass, and returns the pool. This is what backs POST /api/proxies: the list changes mid-flight without a restart, and anything still on it keeps its health, because the pool is refreshed rather than rebuilt.

cfg is the config in force, so that the override sticks: Pool reconciles with the config at the start of every pass, and without knowing that cfg is what the override was made under, the very next pass would read the override as a config change and undo it. With it, the override holds until someone actually edits [proxies], and that edit wins. cfg may be nil. Explicit URL spelling is preserved, as in Config.Endpoints.

func (*Live) Pool ¶

func (l *Live) Pool(ctx context.Context, cfg *Config, marketplaces []string, database string) (*Pool, error)

Pool is the live pool brought into line with cfg (nil when [proxies] is not enabled, which closes and drops any pool there was), with database ("" = none) attached.

Country URL templates use uppercase scope codes, and each source keeps its last good list if a later download fails. Health survives list updates. A different database path than the attached one reopens the pool from that database; feeds are downloaded only when due. Once ctx has ended nothing is built or refreshed, and ctx's error is returned.

func (*Live) RefreshLoop ¶

func (l *Live) RefreshLoop(ctx context.Context, loadCfg func() (*Config, []string, error), database string, logs ...*slog.Logger)

RefreshLoop brings the pool into line once a minute until ctx ends, so feeds refresh even between scans: each tick re-reads the config with loadCfg, so an edit applies without a restart, and downloads only the feeds that are due. database "" is none. A tick that fails, or panics, is logged and the next one runs.

func (*Pacer) Delay ¶ added in v0.2.0

func (p *Pacer) Delay() time.Duration

Delay estimates the wait for this host without taking a slot. It never waits for a sleeping request and can be used in Pool.Acquire's wait callback.

func (*Pacer) ForRoute ¶ added in v0.2.0

func (p *Pacer) ForRoute(endpoint string) *Pacer

ForRoute returns the pacer shared by endpoint's host, ignoring credentials, protocol and port. Empty and Direct select the root pacer; this is only a pacing key and never authorizes direct routing. Invalid URLs use their full string as a private key and remain subject to transport validation.

func (*Pacer) OK ¶ added in v0.2.0

func (p *Pacer) OK()

OK eases this host's request floor toward its configured minimum.

func (*Pacer) Penalty ¶ added in v0.2.0

func (p *Pacer) Penalty() float64

Penalty returns this host's current multiplier on MinInterval. It starts at one and remains observable when pacing is disabled, for health diagnostics.

package main

import (
	"fmt"

	"github.com/JohanLindvall/proxytron"
)

func main() {
	pacer := proxytron.NewPacer(proxytron.PacerConfig{SlowFactor: 2, Decay: 0.5}, nil)
	route := pacer.ForRoute("http://proxy.example.test:8080")
	route.Refused()
	fmt.Println(route.Penalty())
	route.OK()
	fmt.Println(route.Penalty())
}

Output:
2
1

func (*Pacer) Refused ¶ added in v0.2.0

func (p *Pacer) Refused()

Refused widens this host's request floor, without affecting other hosts.

func (*Pacer) Wait ¶ added in v0.2.0

func (p *Pacer) Wait(ctx context.Context) error

Wait takes the next slot for this host. Cancellation while sleeping or queued returns promptly without consuming a slot. Different hosts wait independently.

func (*Pool) Acquire ¶

func (p *Pool) Acquire(site string, allowDirect bool, exclude map[string]bool,
	wait func(url string) time.Duration) string

Acquire is the route for this scope's next attempt, or "" when every route it may use is benched.

Cooling routes and forbidden direct/foreign routes are never handed out, and a retry prefers a route it has not tried for this page (exclude). Among the rest, the default selection = "throughput" maximises valid responses per second. A scope's fetcher sends one request at a time, so its throughput is what an attempt yields over what it costs, and the best route is the one with the highest P(valid) / E[seconds] (a renewal-reward argument: the long-run rate of a sequence of attempts is E[reward] / E[time] per attempt).

P(valid) is a Beta posterior over this route's recent attempts on this site, and seconds is its mean attempt time whatever the outcome, plus what wait(url) says its host's pacing floor would add right now. wait may be nil; it runs under the pool's lock, so it must not call back into the pool. Each candidate's P(valid) is drawn from its posterior rather than taken at the mean (Thompson sampling), so a route that looks slightly worse still gets the occasional turn its uncertainty earns, and a route that starts failing loses its share within a few attempts. Untried routes are interchangeable until tried: one draw from the site's prior stands for all of them, and the next one in list order is the one tried. Drawing once per untried route instead would let four hundred of them, three in four dead, outbid a route known to work by sheer number of lottery tickets.

selection = "round_robin" restores the rotation this replaced: each scope keeps its own position in the list, the last URL rather than an index, so a feed refresh that reorders entries does not reset it.

func (*Pool) Close ¶

func (p *Pool) Close() error

Close detaches (and closes) the database, if one is attached.

func (*Pool) Demote ¶

func (p *Pool) Demote(ctx context.Context, site, url, reason string, took time.Duration)

Demote sends a route that site refused to cooldown on that site alone, after an attempt that took took. A url not in the pool is ignored.

Refusal is a per-domain verdict: it cools the route for that site and leaves the other four using it, since letting `se` evict an endpoint everywhere would throw away a path that four other sites are being served by perfectly well. The cooldown grows geometrically from Settings.BaseCooldown (a minute) per refusal in a row, up to half an hour. A failed connection is DemoteTransport's and an WAF challenge Punish's.

func (*Pool) DemoteTransport ¶

func (p *Pool) DemoteTransport(ctx context.Context, site, url, reason string, took time.Duration)

DemoteTransport benches a route that did not carry the request at all — a dead tunnel, a refused connection — after an attempt for site that took took. That is endpoint-wide, so it cools the route for every site, but the record is kept until age-based cleanup. A url not in the pool is ignored.

A failed connection is punished far harder than a refusal, because a rotation gives every endpoint off its bench a full turn: on c016fcf's first pass one destination spent 429 of its 500 requests and another 396 on proxies that never connected, because each came back after a minute. A feed entry that has never served a page is a dead entry and sits out Settings.DeadCooldown (a day) at once. One that has served, or a static endpoint or Direct (the operator's own routes, not a list's guesses), sits out Settings.BrokenCooldown (ten minutes), doubling per failure in a row up to the same day.

func (*Pool) DetectEgress ¶

func (p *Pool) DetectEgress(ctx context.Context, d Detector, endpoint string) (Egress, error)

DetectEgress probes a configured endpoint without holding the pool lock and persists the resulting identity with its scores. Failures leave prior data intact.

func (*Pool) Do ¶ added in v0.2.0

func (p *Pool) Do(ctx context.Context, scope string, options RequestOptions, attempt func(context.Context, string) AttemptResult) error

Do rotates routes, waits for cooldowns, paces request starts and scores the outcomes returned by attempt. The callback owns request construction, session state, response classification and body cleanup. Close or consume bodies before returning; a result can be retained in the callback's closure. Only retry operations the application can safely replay.

Do invokes callbacks synchronously, outside pool locks, and owns no clients or goroutines. Cancellation of ctx or a context.Canceled attempt is never scored. An empty pool never permits direct egress. Failed routes are avoided while alternatives are ready, then may be reused after their cooldowns, like Acquire.

package main

import (
	"context"
	"errors"
	"fmt"

	"github.com/JohanLindvall/proxytron"
)

func main() {
	pool := proxytron.FromURLs([]string{"http://first.example.test:8080", "http://second.example.test:8080"})
	defer pool.Close()
	attempts := 0
	var body string
	err := pool.Do(context.Background(), "catalog", proxytron.RequestOptions{Attempts: 1},
		func(ctx context.Context, endpoint string) proxytron.AttemptResult {
			attempts++
			// An application sends and classifies the request here. These
			// synthetic results demonstrate the two independent retry budgets.
			if endpoint == "http://first.example.test:8080" {
				return proxytron.AttemptResult{Outcome: proxytron.TransportFailed,
					Err: errors.New("connection failed"), Retry: true, RouteFailure: true}
			}
			body = "response data"
			return proxytron.AttemptResult{Outcome: proxytron.Succeeded}
		})
	fmt.Println(body, attempts, err)
}

Output:
response data 2 <nil>

func (*Pool) Egress ¶

func (p *Pool) Egress(endpoint string) (Egress, bool)

Egress returns the latest stored exit address, false if none was measured.

func (*Pool) Health ¶

func (p *Pool) Health() []HealthRow

Health is one row per endpoint: the endpoint-wide picture plus a per-site breakdown.

The breakdown is the point: a single blended refusal rate reads as "this endpoint is half-refused" when the truth is "one scope refuses everything and the other four are clean".

func (*Pool) Len ¶

func (p *Pool) Len() int

Len is the number of routes the pool hands out; 0 for a nil pool, so `pool.Len() > 0` is the test for a pool worth asking.

func (*Pool) NewPass ¶

func (p *Pool) NewPass()

NewPass starts every site's count of refusals in a row afresh.

That count doubles a route's cooldown per refusal and resets only on a served page, and the pool outlives the pass, so a pass whose warm-up was refused twice handed the next one, two hours later, a count of two. Its first 503 then benched the tunnel for 240 s instead of 60, the warm-up's second chance one minute later found no route, and the pass was lost as "refused" without a second request: one destination on 2026-10-03, 10-04 and 10-05 alike. Two hours is four times the longest cooldown, so the count carries nothing a new pass should inherit. What does carry over is kept: a cooldown still running is still honoured, and the refusal rate that describes the endpoints is evidence, not a streak.

func (*Pool) PathCount ¶

func (p *Pool) PathCount(site string, allowDirect bool) int

PathCount counts this scope's routes, including ones cooling down.

func (*Pool) Punish ¶

func (p *Pool) Punish(ctx context.Context, site, url, reason string, took time.Duration) time.Duration

Punish benches an endpoint on one scope after that site's WAF challenged it, in an attempt that took took. It returns the bench, 0 if url is not in the pool.

A challenge is the one verdict that is about the route rather than the request or the site: the WAF looked at the address and asked it to prove it is a browser, which it cannot. On 2026-10-09 seven routes in one destination's feed drew it on most requests, pass after pass, while the route carrying all 151 of a working destination's pages drew none — and because a challenge page is small, it came back fast and had been *raising* those routes' share. So the bench is hours rather than the minute a refusal earns (Settings.ChallengeCooldown, doubling per challenge in a row up to a day), the challenge counts in the site's refusal rate so its history remains visible once it is back, and only a page it actually serves clears the doubling. Per site: another scope's WAF has not judged it. Nothing is dropped — it can still prove it came back.

func (*Pool) Refresh ¶

func (p *Pool) Refresh(ctx context.Context, urls []string, marketplaces map[string][]string, feed []string) (added, removed int)

Refresh replaces the endpoint list, preserving health state for carry-overs. scopes restricts endpoints (url -> codes; nil = every endpoint shared) and feed names the ones that came from a refresh feed.

Returns (added, removed). An endpoint present before and after keeps its fail count and cooldown, so a periodic refresh from the same source does not reset the cooldown on something that has been failing all along.

func (*Pool) RefusedCooling ¶

func (p *Pool) RefusedCooling(site string, allowDirect bool) bool

RefusedCooling reports whether a route site may use is cooling right now because site refused it (Demote), rather than benched for a failed connection (DemoteTransport) or an WAF challenge (Punish): the difference the proxy list draws between "kyls ned" and "spärrad … (WAF)" (benchOf, whose endpoint-wide benches do not hide a refusal here). A site that runs out of routes while one of them is cooling for its refusal has been refused into stopping, whatever benched the rest; see fetch's HaltRefused. A route on a single-route site that WAF challenged was demoted, not punished, and counts.

func (*Pool) ReportOK ¶

func (p *Pool) ReportOK(ctx context.Context, site, url string, took time.Duration)

ReportOK records that a real page came back through url for site, in an attempt that took took (the whole request, body read included). It clears the failure state for this site and updates the latency measurement. Transport health is cleared too: the endpoint demonstrably carries traffic. A url not in the pool is ignored.

The outcome methods log, and persist, under ctx tagged with site.

func (*Pool) Save ¶

func (p *Pool) Save(ctx context.Context) error

Save checkpoints all state and reports errors synchronously. Outcome methods already persist individual records; Save also retries any previously failed save.

func (*Pool) SiteHealth ¶

func (p *Pool) SiteHealth(site string) []SiteHealth

SiteHealth is one row per endpoint site may use, with that scope's own numbers.

func (*Pool) WaitFor ¶

func (p *Pool) WaitFor(site string, allowDirect bool, exclude map[string]bool) (time.Duration, bool)

WaitFor is how long until an endpoint site may use comes off cooldown: 0 when one is usable now; ok is false when the pool holds none it may use at all.

This lets callers wait for a route instead of spending attempts that send nothing; Pool.Do uses it for cooldown waits. Both cooldowns count, the endpoint-wide one (transport) and the site's own (refusal), since either keeps Acquire from handing the endpoint out.

func (*ProbeResponseError) Error ¶ added in v0.2.0

func (e *ProbeResponseError) Error() string

Error describes the rejected response without including its contents.