fuzhengwei / fuzhengwei/WaLiAPI
上游非 2xx 的重试语义在多端点不一致(3xx/402/418/501 行为相反;401/403 下游呈现不统一)
- Dominant language
- Rust
- Stars
- 128
- Forks
- 39
- Avg merge
- 15h 25m
- Merged PRs (30d)
- 44
Description
### 现状
同一个「上游返回非 2xx 时是否切换渠道、下游收到什么状态码」的判定,目前存在三套实现,边缘状态码行为相反(以 v0.2.3 `9232d6d` 为准):
| 上游状态码 | legacy 代理循环(PR #46) | server handlers 循环 | T00 决策 5(attempt.rs 分类器) |
|---|---|---|---|
| 400 / 422 | 停 + 原样透传 | 停 | caller_terminal 停 |
| 401 / 403 | 停 + **原样透传** | 停 + 流式路径**原样透传**(`openai_error_response` 一处映射 502,native 路径透传) | 同组下一渠道、禁跨组;下游 502 |
| 404 | 停 + 原样 | 停 | 模糊(仅证明路径缺失才算 endpoint_unsupported) |
| 405 | 停 | 停 | endpoint_unsupported 停 |
| **501** | 停(EndpointUnsupported) | **换渠道重试**(`is_server_error()` 命中) | endpoint_unsupported 停 |
| 408 / 409 / 429 / 529 | 换渠道 | 换渠道 | retryable |
| 500–599(除 501) | 换渠道 | 换渠道 | retryable |
| **3xx / 402 / 418 / 未列 4xx** | **换渠道**(分类器保守默认) | **停** | retryable(保守,不硬停) |
后果:同一个上游 501(或 3xx/402/418),走不同端点一个立即停止、一个静默轮询全部渠道后报 502;渠道 401/403 原样透传会让 Claude Code 用户误以为自己的 key 错了(与 #39 修复的误报同类)。
### 想确认的两个语义点
1. **上游 401/403 的下游呈现**:建议按 T00 决策 5 的 `terminal_status`(ChannelAuthTerminal → 502)与 `openai_error_response` 已有行为统一为 **502 + api_error**,日志/审计保留真实 401/403 与渠道名——避免调用方误判为自己的密钥问题。
2. **401/403 是否继续换渠道**:设计允许「同组下一渠道、不跨组」;legacy 扁平循环没有组概念,PR #46 选择了直接停。建议**维持停**(避免刚合入的行为再翻转),等新 track(RoutePlan)落地后再按组语义放开。
### 建议方案(已按此实现,随后提 PR)
以 `core/attempt.rs` 的 `classify_http_status` 为唯一事实来源,新增纯函数决策 API(`FailoverDecision`:`Failover` / `Stop { downstream_status }`),删除 proxy 与 handlers 各自私有判定,七个循环点(legacy 代理、chat 流式、responses 流式、embeddings、native Messages、Messages 经 OpenAI Chat 转换、count_tokens)全部薄委托;语义对齐上表 T00 列。想听一下维护者对两个确认点的意见,PR 描述里有完整真值表与测试输出。
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with core/attempt.rs and its classify_http_status implementation, then inspect the legacy proxy and server handler loops named in the issue. Run the existing status-classification and endpoint tests before tracing the seven listed loop points. Done means one shared FailoverDecision API governs those paths and the documented status matrix is covered by tests.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- api, backend-api-design
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100