fix: let assembly defects pierce the gate wrappers
Independent verification caught that the split shipped in the previous commit did not actually hold on the only path production uses. The gate wrappers re-raise GovernanceBackendError but nothing else, so SourceNotConfiguredError fell into the following `except Exception` and came back out as a governance_backend_down failure with retry_after_s=5.0. A misconfigured source name would still retry forever and never surface. The existing tests missed it because both of them call the private _cfg() directly, one layer below the wrapper the governance loops actually go through. The regression test goes through QuotaGate. telemetry.py has to widen its terminal catch in the same commit: once the wrapper stops relabeling the error, it is no longer a GovernanceBackendError, and it is raised before any attempt exists, so the path would have recorded no telemetry at all. Also corrects the leak path count from three to five. QuotaGate.stats and BreakerGate.retry_after_s are not wrapped by _record_quietly either.
This commit is contained in:
@@ -107,7 +107,7 @@ class BreakerGate:
|
||||
|
||||
## 任务清单
|
||||
|
||||
### - [ ] T1: ARCHITECTURE §6.1 回补(必须先行)
|
||||
### - [x] T1: ARCHITECTURE §6.1 回补(必须先行)
|
||||
|
||||
**文件**: `research-wiki/ARCHITECTURE.md`(§6.1,约 372-380 行)
|
||||
|
||||
@@ -125,7 +125,7 @@ class BreakerGate:
|
||||
|
||||
---
|
||||
|
||||
### - [ ] T2: errors.py 纯增量(新常量、新 reason、新类)+ 导出
|
||||
### - [x] T2: errors.py 纯增量(新常量、新 reason、新类)+ 导出
|
||||
|
||||
**文件**: 改 `src/polygateway/errors.py`、`src/polygateway/__init__.py`;改 `tests/unit/test_errors.py`
|
||||
|
||||
@@ -148,7 +148,7 @@ class BreakerGate:
|
||||
|
||||
---
|
||||
|
||||
### - [ ] T3: `GovernanceBackendError` 归位 + 22 处构造点 + scope 注入(原子)
|
||||
### - [x] T3: `GovernanceBackendError` 归位 + 22 处构造点 + scope 注入(原子)
|
||||
|
||||
**文件**: 改 `src/polygateway/errors.py`、`backends/redis/limiter.py`、`backends/redis/breaker.py`、`backends/memory/limiter.py`、`middleware/ratelimit.py`、`middleware/breaker.py`、`middleware/retry.py`、`ocr.py`、`embedding.py`;改 `tests/unit/test_errors.py`、`tests/unit/test_backpressure.py`、`tests/unit/test_redis_key_layout.py`、`tests/integration/test_redis_cross_connection.py`
|
||||
|
||||
@@ -170,7 +170,7 @@ class BreakerGate:
|
||||
- `backends/redis/breaker.py` 的 `:370 / :388 / :410 / :422 / :432`(5 处)
|
||||
|
||||
4. **两个 gate 包装器**: 构造函数改为上文"关键接口"的签名;`QuotaGate` 4 处(`ratelimit.py:30/38/46/54`)与 `BreakerGate` 5 处(`breaker.py:26/36/46/54/62`)的 `raise` 补 `scope=self._scope`。
|
||||
- 各方法开头的 `except GovernanceBackendError: raise` **保持不变**(后端层已填好 scope,重建实例只会重复构造,设计 §3.3)。
|
||||
- ~~各方法开头的 `except GovernanceBackendError: raise` **保持不变**~~ **← 这条是错的,2026-08-06 独立验证时炸出(见 §T6)**。正确做法: 该放行必须扩为 `except (GovernanceBackendError, SourceNotConfiguredError): raise`,否则新增的兄弟类型会落进下一行的 `except Exception` 被**重新包成** `GovernanceBackendError`,使 Q1 的拆分在唯一的生产路径上完全失效。
|
||||
|
||||
5. **三处装配各传 scope**(三处的 `self._scope` 均已在装配前赋值,无需调整顺序):
|
||||
|
||||
@@ -211,7 +211,7 @@ class BreakerGate:
|
||||
|
||||
---
|
||||
|
||||
### - [ ] T4: 公开错误面文档(issue #7 第二诉求)
|
||||
### - [x] T4: 公开错误面文档(issue #7 第二诉求)
|
||||
|
||||
**文件**: 改 `README.md`(§"错误模型(四分类)",约 114-125 行)、`research-wiki/migrations/chsanalyzer.md`
|
||||
|
||||
@@ -238,7 +238,7 @@ class BreakerGate:
|
||||
|
||||
---
|
||||
|
||||
### - [ ] T5: 版本 1.1.0 + CHANGELOG + Wiki 同步
|
||||
### - [x] T5: 版本 1.1.0 + CHANGELOG + Wiki 同步
|
||||
|
||||
**文件**: 改 `pyproject.toml`(version)、`src/polygateway/__init__.py`(`__version__`)、`CHANGELOG.md`;按 `research-wiki/docs-convention.md` §2 同步 Gitea Wiki
|
||||
|
||||
@@ -258,6 +258,33 @@ class BreakerGate:
|
||||
|
||||
---
|
||||
|
||||
### - [x] T6: 修复独立验证炸出的阻塞缺陷(计划外,2026-08-06)
|
||||
|
||||
T1–T5 全绿、全部门禁通过之后,全新上下文的 verifier 用一个**走 `QuotaGate` 的**端到端用例炸出:装配缺陷在唯一的生产路径上根本没有拆出去。
|
||||
|
||||
**缺陷**: `QuotaGate`/`BreakerGate` 的 `except GovernanceBackendError: raise` 只放行了旧类型,新增的 `SourceNotConfiguredError` 落进下一行 `except Exception` 被重新包成 `GovernanceBackendError`(`reason=governance_backend_down`、`retry_after_s=5.0`)。实证:
|
||||
|
||||
```
|
||||
RAISED: GovernanceBackendError | isGatewayUnavailable=True | isSourceNotConfigured=False
|
||||
| 限流后端故障(source_stats): 未知源 's1'(scope=llm)
|
||||
```
|
||||
|
||||
即配置写错的任务照样落进"可延期重投"家族,**永远重投、永不进死信、无人告警**——正是 Q1 要防的镜像 bug,G2 等于没做。
|
||||
|
||||
**为什么原有测试测不出来**: T3 写的两条用例(`test_backpressure.py`、`test_redis_key_layout.py`)都直接打私有 `_cfg()`,绕过了包装器;而治理循环只经包装器访问后端。**盲区在于测试打的层次比生产路径低一层。**
|
||||
|
||||
**修复**(三处):
|
||||
|
||||
| 文件 | 改动 |
|
||||
|---|---|
|
||||
| `middleware/ratelimit.py` | 4 个方法的放行扩为 `except (GovernanceBackendError, SourceNotConfiguredError): raise` |
|
||||
| `middleware/breaker.py` | 同上,5 个方法 |
|
||||
| `middleware/telemetry.py:254` | 终态捕获元组加 `SourceNotConfiguredError`。**连带坑**: 放行生效后该异常不再是 `GovernanceBackendError`,而它在任何 attempt 之前抛出,若不显式捕获则 `emit_terminal_failure` 不触发、该路径**遥测归零**,违反"遥测必录"铁律 |
|
||||
|
||||
**回归测试**: `test_backpressure.py::TestUnknownSourceIsAssemblyDefect::test_survives_the_quota_gate_wrapper`(参数化覆盖 `try_acquire` / `stats`),**走包装器而非私有方法**。修前 2 failed,修后 PASS。
|
||||
|
||||
**同批文档订正**: 泄漏路径由"三条"改为**五条**(遗漏了 `QuotaGate.stats` 与 `BreakerGate.retry_after_s`,判据是该调用点是否被 `_record_quietly` 包裹);CHANGELOG 的 `per_source_reasons` 表述改为"属性存在但恒为 `{}`"。
|
||||
|
||||
## 完成后
|
||||
|
||||
按 CLAUDE.md §3 Phase 2,合并前须派**全新上下文**的 verifier subagent 做独立验证(`verification-before-completion`),并按新规则**前台运行**。随后走 `finishing-a-development-branch` 决定合并方式,并在 Gitea 关闭 issue #7。
|
||||
|
||||
Reference in New Issue
Block a user