Skip to content

feat(gateway): add optional per-key proxy binding with fail-closed routing (#149) - #170

Merged
jasonxu114514 merged 1 commit into
jasonxu114514:mainfrom
NekomyaDev:feat/per-key-proxy-binding
Nov 5, 2026
Merged

jasonxu114514 merged 1 commit into
jasonxu114514:mainfrom
NekomyaDev:feat/per-key-proxy-binding

Conversation

@NekomyaDev

Copy link
Copy Markdown
Contributor

Summary

Implements opt-in per-key proxy binding with fail-closed routing as requested in #149.

Key Capabilities

  • Explicit, Stable Bindings: Operators can associate configured upstream Zen or Go credentials with configured proxy routes via optional proxy_bindings in config.json or WebUI config.
  • No Secret Duplication: During normalization, key references are resolved and canonicalized to their 16-hex Fingerprint(key). Raw secrets are never stored twice in configuration or exposed in diagnostics.
  • Fail-Closed Isolation: When a bound proxy fails health checks or becomes unavailable, its bound credentials do not silently migrate to another proxy or fall back to direct egress. They remain pinned to their designated route and observe ordinary cooldowns.
  • Automatic Recovery: When an unavailable proxy recovers connectivity, bound credentials immediately clear their outage cooldowns and resume traffic on the assigned route without requiring manual rebinding or restarting.
  • Validation & Safe Hot Reload: A missing or removed proxy reference produces a clear validation error during startup and hot reload. An invalid reload leaves the previous active runtime completely intact.
  • Backward Compatibility: Deployments without proxy_bindings continue to use existing round-robin distribution and dynamic proxy rebinding without any behavioral change. Anonymous traffic is completely unaffected.
  • Egress Clarification: Clarified in config documentation that binding to a proxy route with a #pool fragment pins requests to that proxy transport endpoint and does not guarantee a static public egress IP if the underlying provider rotates exits.

Verification & Testing

Added comprehensive unit and acceptance tests covering all acceptance criteria from #149:

  • internal/config/binding_test.go:

    • TestNormalizeProxyBindings_Valid: verifies canonicalization to fingerprint and raw key resolution.
    • TestNormalizeProxyBindings_UnknownKeyRejected: verifies rejection of unknown credential references.
    • TestNormalizeProxyBindings_UnknownProxyRejected: verifies rejection of unknown proxy references.
    • TestNormalizeProxyBindings_SecretNotExposedInJSON: verifies raw secrets never leak into proxy_bindings serialization.
    • TestNormalizeProxyBindings_ReorderingKeysPreservesBindings: verifies stability across key reordering.
    • TestClone_PreservesProxyBindings: verifies config cloning isolation.
  • internal/gateway/binding_test.go:

    • TestNodePool_PerKeyBinding: verifies bound vs unbound assignment, fail-closed non-migration during proxy outage, and immediate resumption on proxy recovery.
    • TestNodePool_ReorderingKeysPreservesBindings: verifies binding persistence regardless of array order.
    • TestKeyStatuses_ReportsBoundFieldWithoutSecrets: verifies Bound: true reporting in diagnostics with masked IDs and zero secret exposure.
    • TestGateway_BoundKeyFailsClosed: verifies end-to-end fail-closed routing in Gateway instance.
    • TestGateway_AnonymousUnaffectedByBindings: verifies anonymous pool independence.
  • go test -count=1 -v ./...: PASS.

  • go vet ./...: Clean.

  • go build ./cmd/opencode2api: Clean.

…uting (fixes jasonxu114514#149)

- Allow operators to associate Zen and Go credentials with configured proxy
  routes via optional proxy_bindings in config.
- Keys are mapped to their 16-hex fingerprint during normalization so
  secrets are never stored twice or exposed in diagnostics.
- Bound credentials fail closed: when their assigned proxy becomes unavailable,
  they do not silently migrate to other proxies or fall back to direct egress.
- When an assigned proxy recovers, traffic resumes immediately without
  changing bindings.
- Removed or invalid proxy references fail config validation, leaving the
  previous running runtime untouched on failed reloads.
- Unbound configurations, anonymous routing, and session affinity continue
  to behave exactly as before.
- Note in config documentation that binding to a #pool proxy endpoint pins the
  transport route and does not guarantee a static public egress IP.
- Add unit and acceptance tests covering binding resolution, fail-closed isolation,
  persistence, and secret masking.
@jasonxu114514
jasonxu114514 merged commit 6fbe12c into jasonxu114514:main Nov 5, 2026
jasonxu114514 added a commit that referenced this pull request Nov 5, 2026
#169 called anonymousNodes.CursorForOffset, warp.Pool.ReportWithRetryAfter and
warp.Pool.HasUntriedActive without defining them, so main did not compile.
Add the three methods: an attempt offset shifts the anonymous start node, a
longer Retry-After extends the egress cooldown, and HasUntriedActive matches
the pool's egress keys.

Also:
- rewrite title.go in house style: named limits, a prompt table, no issue
  numbers in comments, and a titleFallback helper shared by both lanes
- document the held-back tool-call helpers in protocol/stream.go
- gofmt internal/admin/server.go
- drop the _test.go files from #169, #170 and #171
jasonxu114514 pushed a commit that referenced this pull request Nov 5, 2026
Resolved against #170 so a relay pin clears the per-attempt WARP choice
(attemptUseWARP). The relay list is now credential-redacted, and a pin may
name a relay by its redacted URL.
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.

2 participants