Skip to content

feat(cmd): add poolclean to prune unusable entries from a proxy file - #147

Open
leonsong09 wants to merge 2 commits into
jasonxu114514:mainfrom
leonsong09:feat/poolclean
Open

leonsong09 wants to merge 2 commits into
jasonxu114514:mainfrom
leonsong09:feat/poolclean

Conversation

@leonsong09

Copy link
Copy Markdown

What this adds

A new command, cmd/poolclean, that removes proxy entries which are provably
unusable from a proxy file.

The gateway already marks a failing proxy unhealthy at runtime, but the file it
was loaded from is never touched. Every restart therefore retries the same dead
entries and pays their connect timeouts again before reaching a working one.
With a file assembled from public subscription lists this is not a rare case.

How it decides

The failure rule is deliberately the gateway's own (isProxyFailure in
internal/gateway), not a new one:

  • Any HTTP response keeps the entry. A proxy that reaches opencode.ai and
    gets 403 or 429 is a working proxy that is being rate limited. Removing
    it would discard exactly the entries a pool needs most.
  • Only a route failure (dial refused, timeout, no tunnel) counts.
  • direct and #pool entries are never touched.

Two guards against false positives:

  1. An entry must fail every round (-rounds, default 2).
  2. A candidate is then re-tested alone (-confirm, default 2), with no other
    probe competing for bandwidth. Any pass keeps it. In a real run over a
    120-entry pool, 3 candidates were flagged by the batch pass and all 3 were
    saved here - batch probing alone would have removed working proxies.

Safety

  • Nothing is written without --write.
  • Comments, blank lines and every other line are preserved verbatim.
  • The file is replaced atomically (os.Rename), so an interrupted run cannot
    truncate the pool.

One small addition to internal/config

ProxyFileOf(path) reads only the proxyfile field, reusing the existing
stripJSONComments. config.Load validates the whole gateway configuration,
which pruning has no business requiring - a list can be cleaned before the
gateway has keys or a listen address, and cleaning must not fail on an unrelated
field. No existing behaviour changes.

Verification

$ go build ./...          # ok
$ go vet ./...            # ok
$ gofmt -l .              # clean

Manual run against a synthetic file (# comment, a dead port, direct, a live
proxy with a trailing comment, a #pool entry):

ok=1 dead=1 skipped=2
  dead  http://127.0.0.1:1   proxyconnect tcp: dial tcp 127.0.0.1:1: connectex: No connection could be made...

After --write, the file kept the comment, direct, the live entry with its
trailing comment, and the #pool entry; only the dead line was removed.

Scope

New command plus one additive helper. No changes to the gateway's runtime
behaviour, so this does not interact with the in-flight streaming PRs (#133,
#137).

leonsong09 and others added 2 commits November 7, 2026 17:07
The gateway marks a failing proxy unhealthy at runtime, but the file it was
loaded from is left untouched. Every restart therefore retries the same dead
entries and pays their connect timeouts again before reaching a working one,
and a file assembled from public subscription lists can carry dozens of them.

poolclean is the offline counterpart. It probes each entry and rewrites the
file without the ones that failed.

The failure rule is the gateway's own: only a route failure counts. Any HTTP
response, including 403 and 429, keeps the entry, because reaching opencode.ai
and being rate limited proves the proxy works. Deleting on 429 would discard
exactly the entries the pool needs most. direct and #pool entries are never
touched.

A candidate must fail every round and then also fail when re-tested on its own,
so a proxy that is merely busy survives. Nothing is written without --write,
comments and other lines are preserved, and the file is replaced atomically.

config.ProxyFileOf reads just the proxyfile field, so pruning does not require
the rest of the configuration to be valid: a list can be cleaned before the
gateway has keys.

Co-Authored-By: GenericAgent <bot@gaagent.ai>
A run that suddenly calls most of the pool dead is far more likely to be a
network or upstream problem than a genuine mass failure, and rewriting the file
on that signal would be unrecoverable without a backup. Refuse the write when
the confirmed-dead share crosses --max-drop-ratio (default 0.5), leave the file
untouched, and exit 2 so a wrapper can tell this verdict apart from a crash.
--force overrides it for the case where the pool really is down.

Every run now ends with a single summary line so a scheduled job can gate on
the shape of the pool instead of scraping the per-entry listing:

    summary: entries=120 ok=107 dead=12 skipped=1 confirmed=7 ratio=6% remaining=113

The line is printed on all three exits (nothing to remove, candidates all
survived confirmation, and the normal write path), so its absence means the run
died rather than that it found nothing.

Also document what the default probe target can and cannot see: /zen/v1/models
answers 200 even to an exit whose IP the free tier already blocks, so a
blocked-but-reachable proxy is deliberately kept. Pointing --target at
/zen/v1/chat/completions gives a stricter answer at the cost of treating every
shared-exit 403 as a reason to delete.

Co-Authored-By: GenericAgent <bot@gaagent.ai>
@leonsong09

Copy link
Copy Markdown
Author

Rebased onto main (b296a61) and force-pushed — PR is now 0 behind / mergeable.

Local verification (same commands as .github/workflows):

  • go vet ./... ✅
  • go build -trimpath ./cmd/opencode2api ✅
  • go build -trimpath ./cmd/poolclean ✅

The workflow shows check_runs: 0 / combined: pending — the run needs a maintainer approval on this fork PR, so nothing else is blocking on my side. Happy to adjust the --max-drop-ratio default (currently 0.5) or the summary-line format if you'd prefer something else.

Suydev added a commit to Suydev/opencode2api that referenced this pull request Nov 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant