iomgaa
726f26d8bd
The verifier found four more env-only behaviours of the same class the branch
was already fixing. The worst is scope: it goes straight into the Redis keys
(pgw:limit:{scope}, pgw:gate:{scope}), so one process using from_env("LLM")
and another constructing scope="LLM" by hand split the rate limit and breaker
state across two namespaces, each tracking its own quota, with no error.
Blank redis_url and pricing_path now collapse to None as from_env has always
done, so they fall into the required-field checks instead of reaching the redis
client as an unparseable URL. EmbeddingSettings gains the __post_init__ it never
had, moving its batch_size and expected_dim checks off the from_env-only path.
Also adds the cache backend whitelist test that mutation testing showed missing.
5.9 KiB
5.9 KiB
Changelog
1.0.2(2026-07-30)
1.0.1 的续作:那一版把三条跨字段守卫收进构造期后,独立验证发现 from_env 上还留着同一类的 15 条校验,一并收拢。
修复
- 后端选择与条件必填项在任何构造路径上都校验。 以下此前只有
from_env拦得住,from_settings()与直接构造一律放行:limiter_backend/breaker_backend/cache_backend/telemetry_backend/selector/quota_full六个字段的合法域;取redis的后端必须有redis_url;启用缓存必须有cache_namespace与正cache_ttl_s;telemetry_backend取sqlite/postgres时对应的路径/DSN 必填;structured_max_retries非负;scope非空。 client.py五处断言的前提现在真的成立。assert settings.redis_url is not None # 内部不变量: config 已校验之类的注释此前在from_settings路上是假的:断言开启时抛不含任何字段信息的AssertionError,python -O下断言被移除、错误退化为 redis 库抛出的连接串解析异常。注释已改为点明由哪个校验方法保证。- 构造路补齐了
from_env一直在做的规范化,两条装配路对同一输入产出同一个值:scope小写并去空白。它直接进 Redis key(pgw:limit:{scope}:…、pgw:gate:{scope}:…),此前一个进程走from_env("LLM")拿到llm、另一个直接构造传"LLM",同一逻辑 scope 的限流与熔断状态会分裂到两套命名空间,各记各的配额与熔断状态,分布式治理静默失效且不报错。redis_url、pricing_path的空串归None。留着空串会骗过is None判断,把错误推迟成 redis 客户端的连接串解析异常或Is a directory: '.'。- Postgres DSN 剥掉 SQLAlchemy 驱动后缀(
postgresql+asyncpg://…的+asyncpgasyncpg 不认)。这一条剥的时候会发一条 warning——库动了调用方给的值,不该静默;日志只出现 scheme 段,DSN 带密码,整串不进日志。经from_env装配的不受影响也不会有这条 warning(_load_pg_dsn早就剥干净了)。
EmbeddingSettings的batch_size/expected_dim域校验也移入构造期,此前只有EmbeddingSettings.from_env校验,直接构造出batch_size=-3要到EmbeddingClient构造时才 fail-loud。
行为收紧(下游请读)
同 1.0.1:经 from_env() 装配的调用方不受影响。手工构造 GatewaySettings 或对它 dataclasses.replace 的调用方,若配置组合非法,现在会在构造期抛 ValueError 并点出字段名,而不是留到运行时表现为静默不建后端、裸 AssertionError 或第三方库的天书报错。
1.0.1(2026-07-30)
修复
- 装配守卫在任何构造路径上都生效,不再只在
from_env上。 三条跨字段不变量(源timeout_s≤lease_ttl_s、stall_window_s≥ 最大源 TTFT、probe_ttl_s≥ 最慢源timeout_s+ 5)原先只在GatewaySettings.from_env里校验,而装配有两条官方路——走from_settings()或直接构造能装出违反不变量的配置且不报错,故障留到运行时才表现为:租约先于请求过期使并发悄悄超出配额、正常慢首包被误判卡死掐断、半开探针在途即被接管。守卫已收进GatewaySettings.__post_init__,与types.py各子配置一致,三个 client(Gateway/Ocr/Embedding)的全部工厂一并覆盖。 - 新增
sources非空校验。此前零源配置只在from_env路径被拦,直接构造可装出必然选源失败的 client。
行为收紧(下游请读)
直接构造 GatewaySettings 或对它做 dataclasses.replace 时,若上述组合非法,现在会在构造期抛 ValueError,而不是留到运行时。经 from_env() 装配的调用方不受影响——那条路本就跑这些守卫。手工拼配置(如从 YAML 读出后构造)的调用方若此前撞上过上述任一故障,升级后会在启动时立即得到点名字段的报错。
守卫报错文案的补救建议改为点字段名(lease_ttl_s、backpressure.stall_window_s、breaker.probe_ttl_s)。原文案已点出字段名,但建议部分给的是环境变量键(如"调大 PGW_LEASE_TTL_S"),而不走 env 的调用方从没设过那些键。键名映射见 .env.example 与 wiki 参考-配置键。
1.0.0(2026-07-22)
首个正式版。统一 LLM/VLM/OCR/Embedding 调度与中转库,治理单位为一次模型调用;经 GovDoc-SaaS 与 CHSAnalyzer 两个真实项目全量迁移验收(ARCHITECTURE §11)。
- M1 核心: types/errors/ports 内核、OpenAI 兼容 httpx transport(SSE + 非流式)、三层活性看门狗、自研重试(错误四分类驱动,换源/退避/Retry-After)、多源多账号 + 选源 + 源冷却、内存限流/熔断、Redis/内存响应缓存(key 含 namespace/salt/多模态摘要)、SQLite 遥测(18 字段必录)、结构化输出阶梯(json_repair/原生 schema + 有界重问)、provider 注册表、
from_env装配。 - M2 分布式: Redis 六道闸限流(Lua,契约测试双后端共用)、跨进程熔断(单探针租约 + epoch fencing)、背压 stall 双条件判定、Postgres 遥测、pricing 成本、EmbeddingClient(分批/维度校验)。
- M2.5 治理韧性: 双通道熔断(失败率窗 + 连败 + 健康证据抑制)、健康感知选源(EWMA×在途 P2C 缺省)、AIMD 自适应并发、429 免重试预算、健康门槛降权;故障混编 soak 同场景 58.1%→98.96%。
- M3 OCR: OcrTextPort/OcrLayoutPort 端口族 + MonkeyOCR 双端点 transport(数值防御下沉)、OcrClient 独立治理循环、
check_health()逐源预检;OCR soak 1500 调用 99.73%。 - M4 迁移验证: GovDoc 与 CHS 全量迁移(合计约 −6800 行项目治理代码由库继任),原测试全绿 + 真实冒烟 + 50 样本回归;Gitea PyPI 分发。
安装(实验室 Gitea PyPI):
pip install --index-url https://gitea.iomgaa.online/api/packages/iomgaa/pypi/simple/ \
--extra-index-url https://pypi.org/simple/ "polygateway[redis,postgres,structured]==1.0.*"