mirror of
https://github.com/zyycn/codex-proxy-rs.git
synced 2026-11-21 16:01:32 +00:00
Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
188a6817d1 | ||
|
|
d44bc64d1a | ||
|
|
6006cc8394 | ||
|
|
e7f8b5a354 | ||
|
|
d62868b692 | ||
|
|
0922f3486c | ||
|
|
f4058c1d2e | ||
|
|
8253fbc497 | ||
|
|
193e83f9f3 | ||
|
|
a9e8fa8a44 | ||
|
|
437322ee4b | ||
|
|
843e1367bd | ||
|
|
ab1bf4372c | ||
|
|
dca9806961 | ||
|
|
15ed54d452 | ||
|
|
050214860e | ||
|
|
d917f948cf | ||
|
|
3d834c9e93 | ||
|
|
8d282dcdf9 | ||
|
|
38446e8a0c |
@@ -12,7 +12,7 @@
|
||||
[](https://github.com/zyycn/codex-proxy-rs/pkgs/container/codex-proxy-rs)
|
||||
[](LICENSE)
|
||||
|
||||
[快速预览](#快速预览) · [快速开始](#快速开始) · [客户端接入](#客户端接入) · [文档](#文档) · [社区](#社区) · [许可证](#许可证)
|
||||
[快速预览](#快速预览) · [快速开始](#快速开始) · [文档](#文档) · [社区](#社区) · [贡献者](#贡献者) · [Star History](#star-history) · [支持项目](#支持项目) · [许可证](#许可证)
|
||||
|
||||
</div>
|
||||
|
||||
@@ -21,105 +21,28 @@
|
||||
|
||||
## 快速预览
|
||||
|
||||
无需部署即可体验管理端的系统概览、账号分组、代理管理与用量统计:
|
||||
|
||||
| 登录信息 | 默认值 |
|
||||
| --- | --- |
|
||||
| 地址 | <https://codex-proxy-rs.ainz.cc> |
|
||||
| 登录身份 | 管理员 |
|
||||
| 账号 | `admin@cpr.local` |
|
||||
| 密码 | `039c18de2aeac46d23ead7766bb07bbbe3747233c66a128e` |
|
||||
|
||||
预览服务运行已发布版本,展示的账号、代理与使用记录均为模拟数据,每天北京时间 `00:00` 自动生成当天数据
|
||||
|
||||
这是公开共享的功能预览环境,不提供真实模型调用;请勿导入真实账号、密钥或其他敏感信息
|
||||
|
||||
## 快速开始
|
||||
|
||||
使用 Docker Compose 部署版本固定的发布镜像,同时启动 PostgreSQL 和 Redis
|
||||
|
||||
以下命令适用于 Linux amd64/arm64,需要 Docker Engine、Docker Compose Plugin、curl 和 OpenSSL
|
||||
|
||||
macOS 从[发行页](https://github.com/zyycn/codex-proxy-rs/releases)下载对应的归档:Intel 机型选 `darwin_amd64`,Apple Silicon 机型选 `darwin_arm64`。
|
||||
Windows x64 / ARM64 的安装步骤见 [Windows 二进制部署](deploy/README.md#windows-二进制部署)
|
||||
|
||||
已有部署请先看 [升级说明](deploy/README.md#镜像升级与源码构建),不要覆盖原配置
|
||||
|
||||
### 一键安装
|
||||
|
||||
请确保当前用户能访问 Docker,并可通过 `sudo` 或 root 设置目录权限
|
||||
在已安装 Docker Engine、Docker Compose Plugin、curl 和 OpenSSL 的 Linux amd64/arm64 主机上运行
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/zyycn/codex-proxy-rs/main/deploy/install.sh -o install.sh && bash install.sh
|
||||
```
|
||||
|
||||
[安装脚本](deploy/install.sh) 默认安装到当前目录下的 `codex-proxy-rs/`,下载同一正式 Release 的部署文件,
|
||||
自动生成密码、设置目录权限并启动服务
|
||||
|
||||
完成后保存显示的访问地址和管理员密码,再[登录管理端](#登录管理端)并[添加账号与客户端密钥](#添加账号与客户端密钥)
|
||||
|
||||
可在执行 `bash install.sh` 时传入环境变量:
|
||||
|
||||
| 变量 | 用途 | 默认值 |
|
||||
| --- | --- | --- |
|
||||
| `INSTALL_DIR` | 安装目录,建议使用绝对路径 | 当前目录下的 `codex-proxy-rs/` |
|
||||
| `CPR_RELEASE_TAG` | 指定发布标签 | 最新正式版本 |
|
||||
| `ADMIN_PASSWORD` | 管理员初始密码,至少 12 位,不能包含 `$`,不能使用常见弱口令 | 随机生成 |
|
||||
|
||||
例如,自定义安装目录:
|
||||
|
||||
```bash
|
||||
INSTALL_DIR="$HOME/services/codex-proxy-rs" bash install.sh
|
||||
```
|
||||
|
||||
重复运行时请使用同一安装目录,检测到 `deploy/config.yaml` 后,脚本保留现有配置和部署文件,
|
||||
忽略传入的管理员密码,也不执行版本升级
|
||||
|
||||
### 手动安装
|
||||
|
||||
自行下载部署文件、配置密码和启动服务的完整步骤见 [部署文档](deploy/README.md#手动安装)
|
||||
|
||||
### 登录管理端
|
||||
|
||||
部署完成后,打开 `http://127.0.0.1:8080`,使用 `admin@cpr.local` 和管理员密码登录
|
||||
|
||||
API Key 持有者可在登录页切换身份,查看自己的用量与额度,并通过「密钥配置」复制 Codex 配置或导入 CC Switch
|
||||
|
||||
默认地址只能在服务器本机访问,从其他设备使用时,需要配置
|
||||
[HTTPS 反向代理](deploy/README.md#公网访问)
|
||||
|
||||
### 添加账号与客户端密钥
|
||||
|
||||
1. 在「账号」中添加账号,完成授权或导入
|
||||
2. 按需建立账号分组,再创建客户端密钥并选择可用分组,**不选分组表示可使用全部账号**
|
||||
3. [连接客户端](#客户端接入)
|
||||
|
||||
## 客户端接入
|
||||
|
||||
**Codex CLI / 桌面端**:在「使用密钥」中按操作系统复制配置,合并配置后重启 Codex;也可通过「导入到」把服务连接与密钥添加到 CC Switch
|
||||
|
||||
完整步骤、生图配置与排障见[客户端配置](deploy/README.md#客户端配置)
|
||||
|
||||
**其他 API 客户端**:API Key 填写管理端创建的客户端密钥。按客户端自动追加的请求路径填写 Base URL;远程接入时将本机地址换成服务器的 HTTPS 地址
|
||||
|
||||
| 客户端自动追加的路径 | Base URL(本机部署) |
|
||||
| --- | --- |
|
||||
| OpenAI Responses:`/responses`;Chat Completions:`/chat/completions` | `http://127.0.0.1:8080/v1` |
|
||||
| Anthropic Messages:`/v1/messages` | `http://127.0.0.1:8080` |
|
||||
|
||||
查询该密钥可见的模型目录:
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:8080/v1/models \
|
||||
-H 'Authorization: Bearer <client-api-key>'
|
||||
```
|
||||
[安装脚本选项](deploy/README.md#安装脚本选项) · [macOS 发行包](https://github.com/zyycn/codex-proxy-rs/releases) · [Windows 安装](deploy/README.md#windows-二进制部署) · [已有部署升级](deploy/README.md#镜像升级与源码构建)
|
||||
|
||||
## 文档
|
||||
|
||||
| 任务 | 文档 |
|
||||
| 主题 | 文档 |
|
||||
| --- | --- |
|
||||
| 部署与使用 | [部署、备份与恢复](deploy/README.md) · [客户端接入与生图](deploy/README.md#客户端配置) |
|
||||
| 接口集成 | [API 参考](docs/api.md) · [模型定价](docs/api.md#模型定价) |
|
||||
| 部署与使用 | [部署、备份与恢复](deploy/README.md) · [客户端接入](deploy/README.md#客户端配置) |
|
||||
| 接口集成 | [API 参考](docs/api.md) · [模型目录](docs/api.md#模型目录) · [模型定价](docs/api.md#模型定价) |
|
||||
| 使用插件 | [安装、配置与使用](docs/plugins.md) |
|
||||
| 开发插件 | [SDK 与合同](backend/crates/gateway-plugin/sdk/README.md) · [打包工具](backend/apps/plugin-cli/README.md) · [官方示例](https://github.com/zyycn/codex-proxy-plugins/blob/main/README.md) |
|
||||
| 开发共用组件 | [组件库说明](https://github.com/zyycn/codex-proxy-ui/blob/main/README.md) · [组件参考](https://github.com/zyycn/codex-proxy-ui/blob/main/playground/components/index.md) · [Playground](https://zyycn.github.io/codex-proxy-ui/) |
|
||||
@@ -132,6 +55,28 @@ curl http://127.0.0.1:8080/v1/models \
|
||||
|
||||
感谢 [LINUX DO](https://linux.do) 社区提供开放、友善的技术交流平台
|
||||
|
||||
## 贡献者
|
||||
|
||||
[<img src="https://contrib.rocks/image?repo=zyycn/codex-proxy-rs&columns=10" alt="查看 GitHub 贡献者列表" width="480">](https://github.com/zyycn/codex-proxy-rs/graphs/contributors)
|
||||
|
||||
## Star History
|
||||
|
||||
<a href="https://simrepo.dera.page/#zyycn/codex-proxy-rs&Date">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://simrepo.dera.page/svg?repos=zyycn/codex-proxy-rs&type=Date&theme=dark">
|
||||
<img src="https://simrepo.dera.page/svg?repos=zyycn/codex-proxy-rs&type=Date" alt="Codex Proxy RS 的 GitHub Star 增长趋势" width="560">
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
## 支持项目
|
||||
|
||||
如果 Codex Proxy RS 帮助到你了,欢迎请我喝杯咖啡 ☕
|
||||
|
||||
[](https://ko-fi.com/zyycn)
|
||||
|
||||
[<img src="docs/donations/wechat-tips.png" alt="WeChat appreciation code" width="138">](docs/donations/wechat-tips.png)
|
||||
[<img src="docs/donations/alipay.png" alt="Alipay QR code" width="138">](docs/donations/alipay.png)
|
||||
|
||||
## 许可证
|
||||
|
||||
本项目基于 [Apache License 2.0](LICENSE) 开源
|
||||
|
||||
Generated
+6
-6
@@ -3006,9 +3006,9 @@ checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
|
||||
|
||||
[[package]]
|
||||
name = "openssl"
|
||||
version = "0.10.80"
|
||||
version = "0.10.82"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "a45fa2aa886c42762255da344f0a0d313e254066c46aad76f300c3d3da62d967"
|
||||
checksum = "4de8111e94a56adca7ebfe6c365b6d42f99deb69b74b6becacd4204e2f193aa2"
|
||||
dependencies = [
|
||||
"bitflags",
|
||||
"cfg-if",
|
||||
@@ -3052,9 +3052,9 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "openssl-sys"
|
||||
version = "0.9.116"
|
||||
version = "0.9.118"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f28a22dc7140cda5f096e5e7724a6962ca81a7f8bfd2979f9b18c11af56318c4"
|
||||
checksum = "19c413d6ec9ebaf5e1c829d355cb3e9f783778d700f135be0921d52fce3c60ae"
|
||||
dependencies = [
|
||||
"cc",
|
||||
"libc",
|
||||
@@ -4797,7 +4797,7 @@ dependencies = [
|
||||
[[package]]
|
||||
name = "tokio-tungstenite"
|
||||
version = "0.28.0"
|
||||
source = "git+https://github.com/openai-oss-forks/tokio-tungstenite?rev=0e5b2d73aa18dd9f0a50ee9ff199d5aef7594186#0e5b2d73aa18dd9f0a50ee9ff199d5aef7594186"
|
||||
source = "git+https://github.com/openai-oss-forks/tokio-tungstenite?rev=7447c427513cfe685f236e1ac0513c4ea3dd9c0b#7447c427513cfe685f236e1ac0513c4ea3dd9c0b"
|
||||
dependencies = [
|
||||
"futures-util",
|
||||
"log",
|
||||
@@ -5006,7 +5006,7 @@ checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
|
||||
[[package]]
|
||||
name = "tungstenite"
|
||||
version = "0.27.0"
|
||||
source = "git+https://github.com/openai-oss-forks/tungstenite-rs?rev=4fffad30fe373adbdcffab9545e9e9bf4f2fc19f#4fffad30fe373adbdcffab9545e9e9bf4f2fc19f"
|
||||
source = "git+https://github.com/openai-oss-forks/tungstenite-rs?rev=bc589d684755a8c02da0fc7e58d0861cbfc306f1#bc589d684755a8c02da0fc7e58d0861cbfc306f1"
|
||||
dependencies = [
|
||||
"bytes",
|
||||
"data-encoding",
|
||||
|
||||
@@ -1,7 +1,6 @@
|
||||
# Codex Proxy Plugin CLI
|
||||
|
||||
`cpr-plugin` 校验并规范化作者清单、收集声明的资源,生成可安装归档及 SHA-256 校验文件。
|
||||
输出合同与 [SDK 版本](../../crates/gateway-plugin/sdk/README.md)一致
|
||||
`cpr-plugin` 按 [SDK 合同](../../crates/gateway-plugin/sdk/README.md)校验清单,将插件可执行文件与声明的资源打包,并输出 SHA-256 校验文件
|
||||
|
||||
## 安装
|
||||
|
||||
@@ -11,7 +10,7 @@
|
||||
cargo +1.99.1 install --locked --path backend/apps/plugin-cli --root /path/to/local-tools
|
||||
```
|
||||
|
||||
将 `/path/to/local-tools/bin` 加入 `PATH`,或使用可执行文件的完整路径;工具链与宿主 [验证命令](../../../docs/architecture.md#验证命令)一致
|
||||
将 `/path/to/local-tools/bin` 加入 `PATH`,或使用可执行文件的完整路径
|
||||
|
||||
## 打包
|
||||
|
||||
@@ -26,24 +25,20 @@ cpr-plugin package \
|
||||
--output-dir /path/to/output
|
||||
```
|
||||
|
||||
`--resource-map web=web/dist` 将包内 `web/` 前缀映射到作者清单所在目录下的 `web/dist/`。
|
||||
可重复传入不同前缀,源目录必须位于项目内;没有对应资源时省略该参数,未使用的映射会被拒绝。
|
||||
未映射的资源按清单中的相对路径读取,只收集 `resources` 声明的文件
|
||||
资源文件须在 `resources` 中声明,默认从清单所在目录按相对路径读取。
|
||||
`--resource-map web=web/dist` 从项目内的 `web/dist/` 读取包内 `web/` 资源。可为不同前缀重复传参,未匹配任何资源的映射会报错
|
||||
|
||||
输出为 `<插件 ID>-<版本>-<目标 triple>.tar.gz` 及同名 `.tar.gz.sha256`;归档根目录直接包含 `plugin.json`、可执行文件和声明资源。
|
||||
输出为 `<插件 ID>-<版本>-<目标 triple>.tar.gz` 及对应的 `.tar.gz.sha256`。归档根目录包含 `plugin.json`、可执行文件和声明资源。
|
||||
输入清单及生成后的清单均不得超过 64 KiB,压缩包上限为 32 MiB,展开归档上限为 128 MiB
|
||||
|
||||
作者清单不填写 `package`;字段省略规则、能力版本和挂载阶段见 [SDK 扩展项声明](../../crates/gateway-plugin/sdk/docs/manifest.md#扩展项简写)。
|
||||
CLI 生成规范化后的 `plugin.json`,补入协议版本、目标平台和文件摘要。打包成功只证明输入符合包合同,实际启动与能力仍需在目标宿主验证
|
||||
作者清单须省略 `package`。CLI 将协议版本、目标平台和文件摘要写入 `plugin.json`。可省略的声明字段见 [SDK 扩展项声明](../../crates/gateway-plugin/sdk/docs/manifest.md#扩展项简写)
|
||||
|
||||
支持 `x86_64-unknown-linux-gnu`、`aarch64-unknown-linux-gnu` 和 `aarch64-apple-darwin`。
|
||||
完整开发示例在独立仓库 `codex-proxy-plugins` 的 `examples/workbench`,可通过[子模块](../../../docs/development.md#源码联调)检出;本工具不负责源码构建、上传或启用插件
|
||||
打包后在目标宿主验证启动和插件功能。完整示例见插件[子模块](../../../docs/development.md#源码联调)的 `examples/workbench`
|
||||
|
||||
### 图标资源
|
||||
|
||||
在作者清单的 `icon` 中指定图标,并在 `resources` 中登记对应路径与 MIME 类型,配置方式见
|
||||
[SDK 插件图标](../../crates/gateway-plugin/sdk/docs/manifest.md#插件图标)。图标与其他声明资源一样参与打包和摘要计算,
|
||||
无需额外命令参数;工具保留文件原始内容,宿主安装时验证图标内容与资源限制
|
||||
按 [SDK 插件图标](../../crates/gateway-plugin/sdk/docs/manifest.md#插件图标)填写 `icon` 和 `resources`。CLI 自动打包原文件并计算摘要,宿主在安装时校验
|
||||
|
||||
## 开发
|
||||
|
||||
|
||||
@@ -14,15 +14,25 @@ use super::{PageSize, Revision, observability::DecimalAmount};
|
||||
pub fn validate_group_fields(
|
||||
name: &str,
|
||||
description: Option<&str>,
|
||||
) -> Result<(), super::AdminModelError> {
|
||||
if name.trim() != name
|
||||
|| name.is_empty()
|
||||
|| name.chars().count() > 100
|
||||
|| name.chars().any(char::is_control)
|
||||
|| description
|
||||
.is_some_and(|value| value.len() > 4096 || value.chars().any(char::is_control))
|
||||
{
|
||||
return Err(super::AdminModelError::InvalidAccountGroupFields);
|
||||
) -> Result<(), super::AdminError> {
|
||||
if name.trim().is_empty() {
|
||||
return Err(super::AdminError::invalid("请输入账号组名称"));
|
||||
}
|
||||
if name.chars().count() > 100 {
|
||||
return Err(super::AdminError::invalid("账号组名称最多 100 个字符"));
|
||||
}
|
||||
if name.trim() != name || name.chars().any(char::is_control) {
|
||||
return Err(super::AdminError::invalid(
|
||||
"账号组名称不能包含首尾空白或控制字符",
|
||||
));
|
||||
}
|
||||
if let Some(description) = description {
|
||||
if description.len() > 4096 {
|
||||
return Err(super::AdminError::invalid("账号组描述最多 4096 字节"));
|
||||
}
|
||||
if description.chars().any(char::is_control) {
|
||||
return Err(super::AdminError::invalid("账号组描述不能包含控制字符"));
|
||||
}
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
@@ -236,8 +236,6 @@ pub enum AdminModelError {
|
||||
InvalidPageSize(u16),
|
||||
#[error("observability page size {0} is outside 1..=100")]
|
||||
InvalidObservabilityPageSize(u16),
|
||||
#[error("account group name or description is invalid")]
|
||||
InvalidAccountGroupFields,
|
||||
#[error("client key group IDs are duplicated or exceed 1000 entries")]
|
||||
InvalidClientKeyGroups,
|
||||
#[error("client key page size must be inside 1..=65535")]
|
||||
|
||||
@@ -180,7 +180,7 @@ pub struct UsageFilter {
|
||||
pub enum UsageRecordStatus {
|
||||
#[default]
|
||||
Success,
|
||||
Error,
|
||||
Error(Option<UsageErrorOrigin>),
|
||||
All,
|
||||
}
|
||||
|
||||
@@ -814,6 +814,17 @@ pub enum UsageErrorOrigin {
|
||||
Unknown,
|
||||
}
|
||||
|
||||
/// 来源规则所依赖的已保存事实,供内存投影与持久层分页查询共同解释
|
||||
#[derive(Clone, Copy)]
|
||||
pub enum UsageErrorEvidence {
|
||||
ProviderErrorCode,
|
||||
UpstreamStatusAtLeast(u16),
|
||||
SavedUpstreamErrorOrClose,
|
||||
ErrorKind(&'static [&'static str]),
|
||||
Continuation(&'static [&'static str]),
|
||||
ConnectionExit(&'static [&'static str]),
|
||||
}
|
||||
|
||||
impl UsageErrorOrigin {
|
||||
#[must_use]
|
||||
pub const fn as_str(self) -> &'static str {
|
||||
|
||||
@@ -480,6 +480,7 @@ pub trait AccountGroupStore: Send + Sync {
|
||||
context: &MutationContext,
|
||||
) -> AdminStoreResult<AccountGroupMutation>;
|
||||
|
||||
/// 仍有 API Key 引用分组时返回 Conflict
|
||||
async fn delete_account_group(
|
||||
&self,
|
||||
command: DeleteAccountGroup,
|
||||
|
||||
@@ -24,7 +24,7 @@ use crate::{
|
||||
NewAccountGroup, SetAccountGroupEnabled, UpdateAccountGroup,
|
||||
},
|
||||
},
|
||||
ports::store::{AccountGroupStore, AccountRuntimeStore},
|
||||
ports::store::{AccountGroupStore, AccountRuntimeStore, AdminStoreErrorKind},
|
||||
};
|
||||
|
||||
use super::{map_store_error, publish_committed};
|
||||
@@ -159,8 +159,7 @@ impl AccountGroupService for DefaultAccountGroupService {
|
||||
crate::model::account_groups::validate_group_fields(
|
||||
&command.name,
|
||||
command.description.as_deref(),
|
||||
)
|
||||
.map_err(|_| AdminError::invalid("账号组请求不合法"))?;
|
||||
)?;
|
||||
let id = AccountGroupId::new(format!("grp_{}", Uuid::now_v7().simple()))
|
||||
.map_err(|_| AdminError::internal("创建账号组 ID 失败"))?;
|
||||
self.publish(
|
||||
@@ -189,8 +188,7 @@ impl AccountGroupService for DefaultAccountGroupService {
|
||||
crate::model::account_groups::validate_group_fields(
|
||||
&command.name,
|
||||
command.description.as_deref(),
|
||||
)
|
||||
.map_err(|_| AdminError::invalid("账号组请求不合法"))?;
|
||||
)?;
|
||||
self.publish(self.store.update_account_group(command, context).await)
|
||||
.await
|
||||
}
|
||||
@@ -209,8 +207,12 @@ impl AccountGroupService for DefaultAccountGroupService {
|
||||
context: &MutationContext,
|
||||
command: DeleteAccountGroup,
|
||||
) -> Result<AccountGroupMutation, AdminError> {
|
||||
self.publish(self.store.delete_account_group(command, context).await)
|
||||
.await
|
||||
match self.store.delete_account_group(command, context).await {
|
||||
Err(error) if error.kind() == AdminStoreErrorKind::Conflict => {
|
||||
Err(AdminError::conflict("分组仍绑定 API Key,请先解除绑定").with_source(error))
|
||||
}
|
||||
result => self.publish(result).await,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -314,7 +314,6 @@ impl ClientKeyService for DefaultClientKeyService {
|
||||
|
||||
fn map_client_key_write_error(error: AdminStoreError) -> AdminError {
|
||||
match error.kind() {
|
||||
AdminStoreErrorKind::DuplicateName => AdminError::conflict("名称已存在"),
|
||||
AdminStoreErrorKind::Conflict => AdminError::conflict("API Key 已存在,请使用其他密钥"),
|
||||
_ => map_store_error(error, "client API key"),
|
||||
}
|
||||
|
||||
@@ -4,20 +4,15 @@ use crate::model::{AdminError, AdminErrorKind};
|
||||
use crate::ports::store::{AdminStoreError, AdminStoreErrorKind};
|
||||
|
||||
pub(super) fn map_store_error(error: AdminStoreError, resource: &'static str) -> AdminError {
|
||||
let kind = match error.kind() {
|
||||
AdminStoreErrorKind::Invalid => AdminErrorKind::Invalid,
|
||||
AdminStoreErrorKind::NotFound => AdminErrorKind::NotFound,
|
||||
AdminStoreErrorKind::StaleRevision
|
||||
| AdminStoreErrorKind::DuplicateName
|
||||
| AdminStoreErrorKind::Conflict => AdminErrorKind::Conflict,
|
||||
AdminStoreErrorKind::Unavailable => AdminErrorKind::Unavailable,
|
||||
};
|
||||
let message = match kind {
|
||||
AdminErrorKind::Invalid => "请求参数不合法",
|
||||
AdminErrorKind::NotFound => "请求的资源不存在",
|
||||
AdminErrorKind::Conflict => "当前资源状态冲突,请刷新后重试",
|
||||
AdminErrorKind::Unavailable => "依赖服务暂不可用",
|
||||
_ => "服务内部错误",
|
||||
let (kind, message) = match error.kind() {
|
||||
AdminStoreErrorKind::Invalid => (AdminErrorKind::Invalid, "请求参数不合法"),
|
||||
AdminStoreErrorKind::NotFound => (AdminErrorKind::NotFound, "请求的资源不存在"),
|
||||
AdminStoreErrorKind::StaleRevision => {
|
||||
(AdminErrorKind::Conflict, "数据已更新,请刷新后再操作")
|
||||
}
|
||||
AdminStoreErrorKind::DuplicateName => (AdminErrorKind::Conflict, "名称已存在"),
|
||||
AdminStoreErrorKind::Conflict => (AdminErrorKind::Conflict, "当前资源状态不允许此操作"),
|
||||
AdminStoreErrorKind::Unavailable => (AdminErrorKind::Unavailable, "存储服务暂不可用"),
|
||||
};
|
||||
AdminError::new(kind, message).with_source(OperationFailure {
|
||||
operation: resource,
|
||||
@@ -49,9 +44,8 @@ pub(super) fn map_provider_error(
|
||||
ProviderAdminErrorKind::Conflict => "服务商资源状态冲突,请刷新后重试",
|
||||
ProviderAdminErrorKind::BadGateway => "上游服务请求失败",
|
||||
ProviderAdminErrorKind::Ambiguous => "上游执行结果未知,请刷新状态后再决定是否重试",
|
||||
ProviderAdminErrorKind::Unavailable | ProviderAdminErrorKind::CredentialRefreshRequired => {
|
||||
"服务商暂不可用"
|
||||
}
|
||||
ProviderAdminErrorKind::Unavailable => "服务商暂不可用",
|
||||
ProviderAdminErrorKind::CredentialRefreshRequired => "账号凭据需要刷新",
|
||||
ProviderAdminErrorKind::Internal => "服务内部错误",
|
||||
};
|
||||
AdminError::new(kind, error.public_message().unwrap_or(message)).with_source(OperationFailure {
|
||||
|
||||
@@ -225,7 +225,7 @@ impl KeyUsageService for DefaultKeyUsageService {
|
||||
.list_usage_records(UsageQuery {
|
||||
status: match query.kind {
|
||||
KeyUsageRecordKind::Success => UsageRecordStatus::Success,
|
||||
KeyUsageRecordKind::Error => UsageRecordStatus::Error,
|
||||
KeyUsageRecordKind::Error => UsageRecordStatus::Error(None),
|
||||
KeyUsageRecordKind::All => UsageRecordStatus::All,
|
||||
},
|
||||
range: query.usage.range,
|
||||
|
||||
@@ -1,6 +1,8 @@
|
||||
//! 从已保存的错误事实投影管理端来源,不参与执行错误分类或重试
|
||||
|
||||
use crate::model::observability::{UsageErrorOrigin, UsageListRecord, UsageRecord};
|
||||
use crate::model::observability::{
|
||||
UsageErrorEvidence, UsageErrorOrigin, UsageListRecord, UsageRecord,
|
||||
};
|
||||
|
||||
impl UsageListRecord {
|
||||
#[must_use]
|
||||
@@ -47,107 +49,124 @@ fn error_origin(
|
||||
continuation_reason: Option<&str>,
|
||||
connection_exit_reason: Option<&str>,
|
||||
) -> UsageErrorOrigin {
|
||||
if has_upstream_error
|
||||
|| upstream_code.is_some_and(|code| !code.is_empty())
|
||||
|| websocket_close_code.is_some()
|
||||
|| upstream_status_code.is_some_and(|status| status >= 400)
|
||||
|| matches!(
|
||||
continuation_reason,
|
||||
Some("upstream_rejected" | "quota_exhausted")
|
||||
)
|
||||
|| matches!(
|
||||
error_kind,
|
||||
// 这里匹配内部 errorKind;message_too_big 只由收到的上游 close 1009 产生
|
||||
Some("permission_denied" | "message_too_big" | "upstream_capacity_unavailable")
|
||||
)
|
||||
{
|
||||
return UsageErrorOrigin::Upstream;
|
||||
}
|
||||
if matches!(
|
||||
continuation_reason,
|
||||
Some(
|
||||
"scope_unavailable"
|
||||
| "pool_unavailable"
|
||||
| "fresh_connection_required"
|
||||
| "connection_busy"
|
||||
| "latest_response_mismatch"
|
||||
| "reused_connection_lost"
|
||||
| "transport_payload_too_large"
|
||||
)
|
||||
) || matches!(
|
||||
error_kind,
|
||||
Some(
|
||||
"process_interrupted"
|
||||
| "process_terminated"
|
||||
| "internal_error"
|
||||
| "model_not_found"
|
||||
| "no_available_provider"
|
||||
| "no_eligible_account"
|
||||
| "account_capacity_unavailable"
|
||||
| "middleware_capacity_unavailable"
|
||||
| "concurrency_queue_full"
|
||||
| "concurrency_queue_timeout"
|
||||
| "provider_infrastructure_unavailable"
|
||||
| "session_policy_restricted"
|
||||
| "request_policy_denied"
|
||||
| "policy_denied"
|
||||
| "budget_exhausted"
|
||||
)
|
||||
) || matches!(
|
||||
connection_exit_reason,
|
||||
Some(
|
||||
"command_channel_closed"
|
||||
| "local_close"
|
||||
| "message_receiver_closed"
|
||||
| "client_cancelled"
|
||||
| "downstream_send_failed"
|
||||
| "downstream_connection_closed"
|
||||
| "downstream_rebound"
|
||||
| "pool_shutdown"
|
||||
| "max_age_expired"
|
||||
| "idle_timeout_expired"
|
||||
| "proxy_capacity_evicted"
|
||||
| "search_activation_required"
|
||||
)
|
||||
) {
|
||||
return UsageErrorOrigin::Proxy;
|
||||
}
|
||||
if matches!(
|
||||
connection_exit_reason,
|
||||
Some(
|
||||
"upstream_close"
|
||||
| "normal_close"
|
||||
| "unexpected_binary_event"
|
||||
| "incomplete_response"
|
||||
| "failed_response"
|
||||
)
|
||||
) {
|
||||
return UsageErrorOrigin::Upstream;
|
||||
}
|
||||
if error_kind == Some("transport")
|
||||
|| matches!(
|
||||
connection_exit_reason,
|
||||
Some(
|
||||
"eof"
|
||||
| "unexpected_eof"
|
||||
| "transport_error"
|
||||
| "connection_reset"
|
||||
| "connection_aborted"
|
||||
| "broken_pipe"
|
||||
| "tcp_reset"
|
||||
| "reset_without_closing_handshake"
|
||||
| "transport_timeout"
|
||||
| "outbound_transport_error"
|
||||
| "receive_idle_timeout"
|
||||
| "pong_timeout"
|
||||
| "ping_write_timeout"
|
||||
| "pong_write_timeout"
|
||||
)
|
||||
)
|
||||
{
|
||||
return UsageErrorOrigin::Connection;
|
||||
}
|
||||
// invalid_request、protocol、rate_limited 等分类同时用于本地和上游失败
|
||||
// 发送状态与笼统的连接退出摘要也不能替代缺失的来源事实
|
||||
UsageErrorOrigin::Unknown
|
||||
use UsageErrorEvidence::*;
|
||||
UsageErrorOrigin::RULES
|
||||
.iter()
|
||||
.find(|(evidence, _)| match evidence {
|
||||
ProviderErrorCode => upstream_code.is_some_and(|code| !code.is_empty()),
|
||||
UpstreamStatusAtLeast(min) => upstream_status_code.is_some_and(|status| status >= *min),
|
||||
SavedUpstreamErrorOrClose => has_upstream_error || websocket_close_code.is_some(),
|
||||
ErrorKind(values) => error_kind.is_some_and(|value| values.contains(&value)),
|
||||
Continuation(values) => {
|
||||
continuation_reason.is_some_and(|value| values.contains(&value))
|
||||
}
|
||||
ConnectionExit(values) => {
|
||||
connection_exit_reason.is_some_and(|value| values.contains(&value))
|
||||
}
|
||||
})
|
||||
.map_or(UsageErrorOrigin::Unknown, |(_, origin)| *origin)
|
||||
}
|
||||
|
||||
impl UsageErrorOrigin {
|
||||
/// 第一条命中的规则决定来源;含义不唯一的分类在缺少其他证据时保留 unknown
|
||||
pub const RULES: &'static [(UsageErrorEvidence, Self)] = {
|
||||
use UsageErrorEvidence::*;
|
||||
&[
|
||||
(ProviderErrorCode, Self::Upstream),
|
||||
(UpstreamStatusAtLeast(400), Self::Upstream),
|
||||
(
|
||||
Continuation(&["upstream_rejected", "quota_exhausted"]),
|
||||
Self::Upstream,
|
||||
),
|
||||
// message_too_big 只由收到的上游 close 1009 产生
|
||||
(
|
||||
ErrorKind(&[
|
||||
"permission_denied",
|
||||
"message_too_big",
|
||||
"upstream_capacity_unavailable",
|
||||
]),
|
||||
Self::Upstream,
|
||||
),
|
||||
(SavedUpstreamErrorOrClose, Self::Upstream),
|
||||
(
|
||||
Continuation(&[
|
||||
"scope_unavailable",
|
||||
"pool_unavailable",
|
||||
"fresh_connection_required",
|
||||
"connection_busy",
|
||||
"latest_response_mismatch",
|
||||
"reused_connection_lost",
|
||||
"transport_payload_too_large",
|
||||
]),
|
||||
Self::Proxy,
|
||||
),
|
||||
(
|
||||
ErrorKind(&[
|
||||
"process_interrupted",
|
||||
"process_terminated",
|
||||
"internal_error",
|
||||
"model_not_found",
|
||||
"no_available_provider",
|
||||
"no_eligible_account",
|
||||
"account_capacity_unavailable",
|
||||
"middleware_capacity_unavailable",
|
||||
"concurrency_queue_full",
|
||||
"concurrency_queue_timeout",
|
||||
"provider_infrastructure_unavailable",
|
||||
"session_policy_restricted",
|
||||
"request_policy_denied",
|
||||
"policy_denied",
|
||||
"budget_exhausted",
|
||||
]),
|
||||
Self::Proxy,
|
||||
),
|
||||
(
|
||||
ConnectionExit(&[
|
||||
"command_channel_closed",
|
||||
"local_close",
|
||||
"message_receiver_closed",
|
||||
"client_cancelled",
|
||||
"downstream_send_failed",
|
||||
"downstream_connection_closed",
|
||||
"downstream_rebound",
|
||||
"pool_shutdown",
|
||||
"max_age_expired",
|
||||
"idle_timeout_expired",
|
||||
"proxy_capacity_evicted",
|
||||
"search_activation_required",
|
||||
]),
|
||||
Self::Proxy,
|
||||
),
|
||||
(
|
||||
ConnectionExit(&[
|
||||
"upstream_close",
|
||||
"normal_close",
|
||||
"unexpected_binary_event",
|
||||
"incomplete_response",
|
||||
"failed_response",
|
||||
]),
|
||||
Self::Upstream,
|
||||
),
|
||||
(ErrorKind(&["transport"]), Self::Connection),
|
||||
(
|
||||
ConnectionExit(&[
|
||||
"eof",
|
||||
"unexpected_eof",
|
||||
"transport_error",
|
||||
"connection_reset",
|
||||
"connection_aborted",
|
||||
"broken_pipe",
|
||||
"tcp_reset",
|
||||
"reset_without_closing_handshake",
|
||||
"transport_timeout",
|
||||
"outbound_transport_error",
|
||||
"receive_idle_timeout",
|
||||
"pong_timeout",
|
||||
"ping_write_timeout",
|
||||
"pong_write_timeout",
|
||||
]),
|
||||
Self::Connection,
|
||||
),
|
||||
]
|
||||
};
|
||||
}
|
||||
|
||||
@@ -60,7 +60,7 @@ async fn explicit_service_calls_freeze_empty_plan_and_cancel_before_entering_ter
|
||||
)
|
||||
.await
|
||||
.unwrap();
|
||||
// 内部 pricing 不再单独进入插件链;显式调用只解析一次发布集合
|
||||
// 每次显式调价只解析一次插件发布集合
|
||||
assert_eq!(resolutions.load(Ordering::SeqCst), expected);
|
||||
}
|
||||
store.updated.lock().unwrap().take();
|
||||
|
||||
@@ -51,7 +51,6 @@ impl From<gateway_admin::model::account_groups::AccountGroupRef> for AccountGrou
|
||||
}
|
||||
|
||||
const DEFAULT_PAGE_SIZE: u32 = 50;
|
||||
const MAX_PAGE_SIZE: u32 = 200;
|
||||
|
||||
#[derive(Debug, Clone, Default, Deserialize)]
|
||||
#[serde(rename_all = "camelCase", deny_unknown_fields)]
|
||||
@@ -66,7 +65,7 @@ impl ListAccountGroupsQuery {
|
||||
fn into_command(self) -> Result<AccountGroupListQuery, WireValidationError> {
|
||||
let page = self.page.unwrap_or(1);
|
||||
let page_size = self.page_size.unwrap_or(DEFAULT_PAGE_SIZE);
|
||||
if page == 0 || page_size == 0 || page_size > MAX_PAGE_SIZE {
|
||||
if page == 0 {
|
||||
return Err(WireValidationError::new("page"));
|
||||
}
|
||||
let search = self
|
||||
@@ -507,11 +506,16 @@ fn group_color(value: &str) -> Result<AccountGroupColor, AdminError> {
|
||||
|
||||
fn validate_group_fields(name: &str, description: Option<&str>) -> Result<(), AdminError> {
|
||||
gateway_admin::model::account_groups::validate_group_fields(name, description)
|
||||
.map_err(|_| AdminError::bad_request("账号组请求不合法"))
|
||||
.map_err(map_admin_service_error)
|
||||
}
|
||||
|
||||
fn map_wire_error(_: WireValidationError) -> AdminError {
|
||||
AdminError::bad_request("账号组查询参数不合法")
|
||||
fn map_wire_error(error: WireValidationError) -> AdminError {
|
||||
match error.field() {
|
||||
"page" => AdminError::bad_request("页码须大于 0"),
|
||||
"pageSize" => AdminError::bad_request(format!("每页数量须为 1 至 {}", PageSize::MAX)),
|
||||
"search" => AdminError::bad_request("搜索内容最多 256 字节,不能包含控制字符"),
|
||||
field => AdminError::bad_request(format!("{field} 字段不合法")),
|
||||
}
|
||||
}
|
||||
|
||||
fn map_service_error(error: gateway_admin::model::AdminError) -> AdminError {
|
||||
|
||||
@@ -1092,7 +1092,7 @@ fn map_wire_error(error: WireValidationError) -> AdminError {
|
||||
"search" => "搜索内容过长或包含控制字符",
|
||||
"sortBy" => "排序字段不受支持",
|
||||
"sortDirection" => "排序方向必须为 asc(升序)或 desc(降序)",
|
||||
_ => "API Key 请求参数不合法",
|
||||
field => return AdminError::bad_request(format!("{field} 字段不合法")),
|
||||
};
|
||||
AdminError::bad_request(message)
|
||||
}
|
||||
|
||||
@@ -1410,7 +1410,14 @@ pub(crate) fn map_wire_error(error: WireValidationError) -> AdminError {
|
||||
"dimension" => "诊断维度不合法",
|
||||
"id" => "用量记录 ID 不能为空",
|
||||
"cursor" => "观测数据游标不合法",
|
||||
_ => "观测查询参数不合法",
|
||||
"currentPage" => "页码须大于 0",
|
||||
"pageSize" => {
|
||||
return AdminError::bad_request(format!("每页数量须为 1 至 {}", DomainPageSize::MAX));
|
||||
}
|
||||
"status" => "请求状态须为 success、error 或 all",
|
||||
"errorOrigin" => "错误来源须为 proxy、upstream、connection 或 unknown",
|
||||
"errorOriginStatus" => "仅错误请求支持按错误来源筛选",
|
||||
field => return AdminError::bad_request(format!("{field} 字段不合法")),
|
||||
};
|
||||
AdminError::bad_request(message)
|
||||
}
|
||||
|
||||
@@ -34,6 +34,7 @@ pub struct UsageQuery {
|
||||
pub client_api_key_name: Option<String>,
|
||||
pub account_search: Option<String>,
|
||||
pub status: Option<String>,
|
||||
pub error_origin: Option<String>,
|
||||
pub current_page: Option<u32>,
|
||||
pub page_size: Option<u16>,
|
||||
pub provider: Option<String>,
|
||||
@@ -354,11 +355,21 @@ pub(crate) fn usage_command(
|
||||
let page_size_value =
|
||||
DomainPageSize::new(page_size).map_err(|_| WireValidationError::new("pageSize"))?;
|
||||
Ok(domain::UsageQuery {
|
||||
status: match query.status.as_deref() {
|
||||
None | Some("success") => domain::UsageRecordStatus::Success,
|
||||
Some("error") => domain::UsageRecordStatus::Error,
|
||||
Some("all") => domain::UsageRecordStatus::All,
|
||||
Some(_) => return Err(WireValidationError::new("status")),
|
||||
status: match (query.status.as_deref(), query.error_origin.as_deref()) {
|
||||
(None | Some("success"), None) => domain::UsageRecordStatus::Success,
|
||||
(Some("all"), None) => domain::UsageRecordStatus::All,
|
||||
(Some("error"), origin) => domain::UsageRecordStatus::Error(match origin {
|
||||
None => None,
|
||||
Some("proxy") => Some(domain::UsageErrorOrigin::Proxy),
|
||||
Some("upstream") => Some(domain::UsageErrorOrigin::Upstream),
|
||||
Some("connection") => Some(domain::UsageErrorOrigin::Connection),
|
||||
Some("unknown") => Some(domain::UsageErrorOrigin::Unknown),
|
||||
Some(_) => return Err(WireValidationError::new("errorOrigin")),
|
||||
}),
|
||||
(None | Some("success" | "all"), Some(_)) => {
|
||||
return Err(WireValidationError::new("errorOriginStatus"));
|
||||
}
|
||||
(Some(_), _) => return Err(WireValidationError::new("status")),
|
||||
},
|
||||
range: usage_range(
|
||||
query.start_time.as_deref(),
|
||||
|
||||
@@ -215,12 +215,12 @@ const METHOD_NOT_ALLOWED: AdminErrorSpec = AdminErrorSpec::new(
|
||||
const TOO_MANY_LOGIN_ATTEMPTS: AdminErrorSpec = AdminErrorSpec::new(
|
||||
StatusCode::TOO_MANY_REQUESTS,
|
||||
AdminErrorCode::TOO_MANY_LOGIN_ATTEMPTS,
|
||||
"登录尝试过多,请稍后重试",
|
||||
"登录尝试过多",
|
||||
);
|
||||
const RATE_LIMITED: AdminErrorSpec = AdminErrorSpec::new(
|
||||
StatusCode::TOO_MANY_REQUESTS,
|
||||
AdminErrorCode::RATE_LIMITED,
|
||||
"请求过于频繁,请稍后重试",
|
||||
"请求过于频繁",
|
||||
);
|
||||
const INTERNAL: AdminErrorSpec = AdminErrorSpec::new(
|
||||
StatusCode::INTERNAL_SERVER_ERROR,
|
||||
|
||||
@@ -178,7 +178,7 @@ pub(crate) fn client_access_error_response(error: ClientAccessError) -> Response
|
||||
response
|
||||
}
|
||||
|
||||
/// Desktop 优先于内嵌 CLI/Core;未知客户端及未提供应用版本的手机远程客户端返回 `None`
|
||||
/// 识别 Desktop 应用或 CLI/Core;未知客户端及未提供应用版本的手机远程客户端返回 `None`
|
||||
#[must_use]
|
||||
pub fn identify_codex_client(headers: &HeaderMap) -> Option<IdentifiedCodexClient> {
|
||||
const MAXIMUM_HEADER_LENGTH: usize = 4096;
|
||||
@@ -196,25 +196,35 @@ pub fn identify_codex_client(headers: &HeaderMap) -> Option<IdentifiedCodexClien
|
||||
"codex_mcp_server",
|
||||
];
|
||||
|
||||
let originator = bounded_ascii_header(headers, "originator", MAXIMUM_HEADER_LENGTH);
|
||||
let user_agent = bounded_ascii_header(headers, "user-agent", MAXIMUM_HEADER_LENGTH);
|
||||
let is_desktop = originator.is_some_and(|value| value.eq_ignore_ascii_case("Codex Desktop"))
|
||||
let ascii_header = |name: &'static str| headers.get(name).and_then(|value| value.to_str().ok());
|
||||
let raw_user_agent = ascii_header("user-agent");
|
||||
// HeaderValue::to_str 只接受 ASCII,可以按字节截取搜索范围
|
||||
let user_agent = raw_user_agent.map(|ua| &ua[..ua.len().min(MAXIMUM_HEADER_LENGTH)]);
|
||||
let is_desktop = ascii_header("originator")
|
||||
.is_some_and(|value| value.eq_ignore_ascii_case("Codex Desktop"))
|
||||
|| user_agent.is_some_and(|value| contains_ascii_case_insensitive(value, "Codex Desktop"));
|
||||
if is_desktop {
|
||||
let explicit_version = bounded_ascii_header(headers, "version", MAXIMUM_HEADER_LENGTH);
|
||||
let version_header = headers.get("version");
|
||||
let user_agent_version = user_agent.and_then(desktop_version_from_user_agent);
|
||||
// 手机远程初始化会覆盖进程级 UA 后缀,保留的 Desktop/Core 前缀不代表应用版本
|
||||
// 仅缺失版本信息时免于门禁;已提供的版本即使非法,也继续按 Desktop 校验
|
||||
if !headers.contains_key("version")
|
||||
&& user_agent_version.is_none()
|
||||
&& headers
|
||||
.get("user-agent")
|
||||
.is_some_and(|value| value.as_bytes().len() <= MAXIMUM_HEADER_LENGTH)
|
||||
&& user_agent.is_some_and(has_chatgpt_remote_user_agent_suffix)
|
||||
if user_agent_version.is_none()
|
||||
&& let Some(ua) = raw_user_agent.filter(|ua| ua.len() <= MAXIMUM_HEADER_LENGTH)
|
||||
&& let Some(client) = user_agent_client_name(ua)
|
||||
{
|
||||
return None;
|
||||
// 共享 App Server 可保留 Desktop 进程名,TUI 请求的 version 头也可能重复 Core 版本
|
||||
if client.eq_ignore_ascii_case("codex-tui")
|
||||
&& let Some(core) = desktop_core_version(ua)
|
||||
&& version_header.is_none_or(|value| value.as_bytes() == core.as_bytes())
|
||||
{
|
||||
return Some(IdentifiedCodexClient {
|
||||
kind: CodexClientKind::Cli,
|
||||
version: CodexClientVersion::parse(core).ok(),
|
||||
});
|
||||
}
|
||||
if version_header.is_none() && is_chatgpt_remote_client(client) {
|
||||
return None;
|
||||
}
|
||||
}
|
||||
let version = match explicit_version {
|
||||
let version = match version_header.and_then(|value| value.to_str().ok()) {
|
||||
Some(value) => CodexClientVersion::parse(value).ok(),
|
||||
None => user_agent_version.and_then(|value| CodexClientVersion::parse(value).ok()),
|
||||
};
|
||||
@@ -244,18 +254,6 @@ pub fn identify_codex_client(headers: &HeaderMap) -> Option<IdentifiedCodexClien
|
||||
None
|
||||
}
|
||||
|
||||
fn bounded_ascii_header<'a>(
|
||||
headers: &'a HeaderMap,
|
||||
name: &'static str,
|
||||
maximum_length: usize,
|
||||
) -> Option<&'a str> {
|
||||
let value = headers.get(name)?.to_str().ok()?;
|
||||
if !value.is_ascii() {
|
||||
return None;
|
||||
}
|
||||
Some(&value[..value.len().min(maximum_length)])
|
||||
}
|
||||
|
||||
fn desktop_version_from_user_agent(user_agent: &str) -> Option<&str> {
|
||||
let marker = "Codex Desktop;";
|
||||
let start = find_ascii_case_insensitive(user_agent, marker)? + marker.len();
|
||||
@@ -266,27 +264,29 @@ fn desktop_version_from_user_agent(user_agent: &str) -> Option<&str> {
|
||||
.next()
|
||||
}
|
||||
|
||||
fn has_chatgpt_remote_user_agent_suffix(user_agent: &str) -> bool {
|
||||
let Some((_, suffix)) = user_agent
|
||||
.strip_suffix(')')
|
||||
.and_then(|value| value.rsplit_once(" ("))
|
||||
else {
|
||||
return false;
|
||||
};
|
||||
let Some((name, version)) = suffix.split_once("; ") else {
|
||||
return false;
|
||||
};
|
||||
let Some(platform) = name
|
||||
.strip_prefix("codex_chatgpt_")
|
||||
.and_then(|value| value.strip_suffix("_remote"))
|
||||
else {
|
||||
return false;
|
||||
};
|
||||
[platform, version].into_iter().all(|value| {
|
||||
fn desktop_core_version(user_agent: &str) -> Option<&str> {
|
||||
let (product, rest) = user_agent.split_once('/')?;
|
||||
let (version, _) = rest.split_once(' ')?;
|
||||
product
|
||||
.eq_ignore_ascii_case("Codex Desktop")
|
||||
.then_some(version)
|
||||
}
|
||||
|
||||
fn user_agent_client_name(user_agent: &str) -> Option<&str> {
|
||||
let (_, suffix) = user_agent.strip_suffix(')')?.rsplit_once(" (")?;
|
||||
let (name, version) = suffix.split_once("; ")?;
|
||||
let valid_token = |value: &str| {
|
||||
!value.is_empty()
|
||||
&& !value.contains(['(', ')', ';'])
|
||||
&& !value.bytes().any(|byte| byte.is_ascii_whitespace())
|
||||
})
|
||||
};
|
||||
(valid_token(name) && valid_token(version)).then_some(name)
|
||||
}
|
||||
|
||||
fn is_chatgpt_remote_client(name: &str) -> bool {
|
||||
name.strip_prefix("codex_chatgpt_")
|
||||
.and_then(|value| value.strip_suffix("_remote"))
|
||||
.is_some_and(|platform| !platform.is_empty())
|
||||
}
|
||||
|
||||
fn contains_ascii_case_insensitive(haystack: &str, needle: &str) -> bool {
|
||||
|
||||
@@ -19,8 +19,8 @@ use super::{
|
||||
|
||||
use crate::ApiState;
|
||||
|
||||
// 公开协议路径由 API 层统一定义;Core 使用操作类型,不根据这些路径分派业务
|
||||
pub(super) const RESPONSES_PATH: &str = "/v1/responses";
|
||||
// Core 使用操作类型,不根据这些协议路径分派业务
|
||||
pub(super) use gateway_protocol::openai::RESPONSES_PATH;
|
||||
pub(super) const MESSAGES_PATH: &str = "/v1/messages";
|
||||
pub(super) const MESSAGE_TOKENS_PATH: &str = "/v1/messages/count_tokens";
|
||||
pub(super) const CHAT_COMPLETIONS_PATH: &str = "/v1/chat/completions";
|
||||
|
||||
@@ -215,7 +215,7 @@ async fn mutation_route_should_reject_unknown_json_fields() {
|
||||
"name": "Unknown field",
|
||||
"description": null,
|
||||
"color": "#2563EBFF",
|
||||
"providerKind": "openai"
|
||||
"unknownField": true
|
||||
})),
|
||||
true,
|
||||
)
|
||||
@@ -232,7 +232,7 @@ async fn create_route_should_reject_six_digit_color_without_alpha() {
|
||||
Method::POST,
|
||||
"/api/admin/account-groups/create",
|
||||
Some(json!({
|
||||
"name": "Opaque legacy color",
|
||||
"name": "Color without alpha",
|
||||
"description": null,
|
||||
"color": "#2563EB"
|
||||
})),
|
||||
|
||||
@@ -341,7 +341,7 @@ async fn account_quota_refresh_time_uses_server_clock_and_deployment_timezone()
|
||||
));
|
||||
let future = now + Duration::days(1);
|
||||
let future_display = zone.local(future).format("%Y-%m-%d %H:%M:%S").to_string();
|
||||
for (observed_at, expected, legacy) in [
|
||||
for (observed_at, expected, display) in [
|
||||
(None, json!(null), "—"),
|
||||
(Some(now), json!({ "kind": "just_now" }), "刚刚"),
|
||||
(
|
||||
@@ -389,7 +389,7 @@ async fn account_quota_refresh_time_uses_server_clock_and_deployment_timezone()
|
||||
let value: serde_json::Value = serde_json::from_slice(&body).unwrap();
|
||||
let quota = &value["data"]["items"][0]["quota"];
|
||||
assert_eq!(quota["refreshedAtRelative"], expected);
|
||||
assert_eq!(quota["refreshedAtDisplay"], legacy);
|
||||
assert_eq!(quota["refreshedAtDisplay"], display);
|
||||
let refreshed_at = quota["refreshedAt"]
|
||||
.as_str()
|
||||
.map(|value| DateTime::parse_from_rfc3339(value).unwrap().to_utc());
|
||||
|
||||
@@ -610,7 +610,7 @@ fn xai_profile_override_distinguishes_omission_from_explicit_inheritance() {
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn generic_profile_overrides_accept_native_providers_and_reject_legacy_conflicts() {
|
||||
fn profile_overrides_accept_matching_native_values_and_reject_conflicts_and_unknown_providers() {
|
||||
let profile = json!({"preset":"desktop"});
|
||||
let xai = json!({"preset":"managed"});
|
||||
let request: CreateClientKeyRequest = serde_json::from_value(json!({
|
||||
@@ -676,7 +676,7 @@ fn generic_profile_overrides_accept_native_providers_and_reject_legacy_conflicts
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn generic_profile_override_clear_rejects_conflicting_legacy_update() {
|
||||
fn clearing_an_xai_profile_override_conflicts_with_an_explicit_xai_value() {
|
||||
let request: UpdateClientKeyRequest = serde_json::from_value(json!({
|
||||
"id":"key_profile",
|
||||
"name":"profile",
|
||||
|
||||
@@ -513,6 +513,12 @@ mod provider {
|
||||
(Kind::Unsupported, 400, 40001, "该服务商不支持此操作"),
|
||||
(Kind::BadGateway, 502, 50201, "上游服务请求失败"),
|
||||
(Kind::Unavailable, 503, 50301, "服务商暂不可用"),
|
||||
(
|
||||
Kind::CredentialRefreshRequired,
|
||||
503,
|
||||
50301,
|
||||
"账号凭据需要刷新",
|
||||
),
|
||||
(
|
||||
Kind::Ambiguous,
|
||||
502,
|
||||
|
||||
@@ -1726,6 +1726,8 @@ async fn observability_queries_reject_group_filters_and_analytics_search() {
|
||||
"routingGroupRefs=group-a",
|
||||
),
|
||||
("/api/admin/usage/records/summary", "search=request-prefix"),
|
||||
("/api/admin/usage/records/summary", "errorOrigin=proxy"),
|
||||
("/api/admin/usage/insights/overview", "errorOrigin=proxy"),
|
||||
(
|
||||
"/api/admin/usage/insights/overview",
|
||||
"search=request-prefix",
|
||||
@@ -1820,27 +1822,50 @@ pub(super) fn ops_error_record() -> gateway_admin::model::observability::OpsErro
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn usage_status_query_accepts_three_modes_and_rejects_unknown_values() {
|
||||
async fn usage_record_query_accepts_error_sources_only_for_error_status() {
|
||||
use crate::admin::{AdminTestFixture, AdminTestState};
|
||||
use axum::{
|
||||
body::{Body, to_bytes},
|
||||
http::{Request, StatusCode, header},
|
||||
};
|
||||
use gateway_admin::model::observability::{UsageErrorOrigin, UsageRecordStatus};
|
||||
use gateway_api::admin::observability;
|
||||
use tower::ServiceExt as _;
|
||||
let fixture = AdminTestFixture::new().await;
|
||||
fixture.auth.insert_session("valid-session");
|
||||
for (status, expected) in [
|
||||
("success", StatusCode::OK),
|
||||
("error", StatusCode::OK),
|
||||
("all", StatusCode::OK),
|
||||
("failed", StatusCode::BAD_REQUEST),
|
||||
for (query, expected) in [
|
||||
("", Some(UsageRecordStatus::Success)),
|
||||
("status=success", Some(UsageRecordStatus::Success)),
|
||||
("status=error", Some(UsageRecordStatus::Error(None))),
|
||||
("status=all", Some(UsageRecordStatus::All)),
|
||||
(
|
||||
"status=error&errorOrigin=proxy",
|
||||
Some(UsageRecordStatus::Error(Some(UsageErrorOrigin::Proxy))),
|
||||
),
|
||||
(
|
||||
"status=error&errorOrigin=upstream",
|
||||
Some(UsageRecordStatus::Error(Some(UsageErrorOrigin::Upstream))),
|
||||
),
|
||||
(
|
||||
"status=error&errorOrigin=connection",
|
||||
Some(UsageRecordStatus::Error(Some(UsageErrorOrigin::Connection))),
|
||||
),
|
||||
(
|
||||
"status=error&errorOrigin=unknown",
|
||||
Some(UsageRecordStatus::Error(Some(UsageErrorOrigin::Unknown))),
|
||||
),
|
||||
("status=failed", None),
|
||||
("errorOrigin=proxy", None),
|
||||
("status=success&errorOrigin=proxy", None),
|
||||
("status=all&errorOrigin=unknown", None),
|
||||
("status=error&errorOrigin=other", None),
|
||||
("status=error&errorOrigin=", None),
|
||||
] {
|
||||
let response = observability::router::<AdminTestState>()
|
||||
.with_state(fixture.state())
|
||||
.oneshot(
|
||||
Request::builder()
|
||||
.uri(format!("/api/admin/usage/records?status={status}"))
|
||||
.uri(format!("/api/admin/usage/records?{query}"))
|
||||
.header(header::COOKIE, "cpr_session=valid-session")
|
||||
.header("x-request-id", "usage_status_fixture")
|
||||
.body(Body::empty())
|
||||
@@ -1852,17 +1877,15 @@ async fn usage_status_query_accepts_three_modes_and_rejects_unknown_values() {
|
||||
let body = to_bytes(response.into_body(), 1024 * 1024).await.unwrap();
|
||||
assert_eq!(
|
||||
actual,
|
||||
expected,
|
||||
"{status}: {}",
|
||||
if expected.is_some() {
|
||||
StatusCode::OK
|
||||
} else {
|
||||
StatusCode::BAD_REQUEST
|
||||
},
|
||||
"{query}: {}",
|
||||
String::from_utf8_lossy(&body)
|
||||
);
|
||||
if expected == StatusCode::OK {
|
||||
use gateway_admin::model::observability::UsageRecordStatus;
|
||||
let status_value = match status {
|
||||
"success" => UsageRecordStatus::Success,
|
||||
"error" => UsageRecordStatus::Error,
|
||||
_ => UsageRecordStatus::All,
|
||||
};
|
||||
if let Some(status_value) = expected {
|
||||
assert_eq!(
|
||||
fixture
|
||||
.observations
|
||||
@@ -2059,7 +2082,7 @@ async fn dashboard_relative_time_preserves_server_anchor_boundaries_and_deployme
|
||||
("Asia/Kathmandu", "2026-06-15 05:45:01"),
|
||||
("America/New_York", "2026-06-14 20:00:01"),
|
||||
] {
|
||||
for (elapsed_ms, expected, legacy) in [
|
||||
for (elapsed_ms, expected, display) in [
|
||||
(None, json!(null), "—"),
|
||||
(
|
||||
Some(-1_000),
|
||||
@@ -2174,7 +2197,7 @@ async fn dashboard_relative_time_preserves_server_anchor_boundaries_and_deployme
|
||||
account["lastUsedRelative"], expected,
|
||||
"{zone}: {elapsed_ms:?}"
|
||||
);
|
||||
assert_eq!(account["lastUsed"], legacy, "{zone}: {elapsed_ms:?}");
|
||||
assert_eq!(account["lastUsed"], display, "{zone}: {elapsed_ms:?}");
|
||||
assert_eq!(account["lastUsedAt"], json!(last_used_at));
|
||||
}
|
||||
}
|
||||
|
||||
@@ -431,7 +431,7 @@ fn settings_request_accepts_unlimited_default_account_concurrency() {
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn settings_request_validates_cron_and_allows_disabled_empty_schedule() {
|
||||
fn warmup_cron_is_required_and_may_be_empty_only_when_disabled() {
|
||||
for (enabled, cron, valid) in [
|
||||
(false, "", true),
|
||||
(true, "", false),
|
||||
@@ -461,10 +461,9 @@ fn settings_request_validates_cron_and_allows_disabled_empty_schedule() {
|
||||
let request: UpdateRuntimeSettingsRequest = serde_json::from_value(oversized).unwrap();
|
||||
assert_eq!(request.validate().unwrap_err().field(), "accountWarmupCron");
|
||||
|
||||
let mut legacy = update_body();
|
||||
legacy.as_object_mut().unwrap().remove("accountWarmupCron");
|
||||
legacy["accountWarmupScheduleTime"] = json!("08:00");
|
||||
assert!(serde_json::from_value::<UpdateRuntimeSettingsRequest>(legacy).is_err());
|
||||
let mut missing = update_body();
|
||||
missing.as_object_mut().unwrap().remove("accountWarmupCron");
|
||||
assert!(serde_json::from_value::<UpdateRuntimeSettingsRequest>(missing).is_err());
|
||||
}
|
||||
|
||||
#[test]
|
||||
@@ -705,8 +704,6 @@ async fn admin_auth_should_accept_a_configured_request_id_header_name() {
|
||||
|
||||
let fixture = AdminTestFixture::new().await;
|
||||
fixture.auth.insert_session("valid-session");
|
||||
// 部署把 api.request_id_header 改名后,注入的 header 不再叫 x-request-id;
|
||||
// 管理请求仍须拿到请求上下文,而不是退化为 500
|
||||
let custom = HeaderName::from_static("x-trace-id");
|
||||
let app = app(fixture.state()).layer(SetRequestIdLayer::new(custom, MakeRequestUuid));
|
||||
let unlabelled = Request::builder()
|
||||
@@ -919,7 +916,7 @@ fn global_profile_can_be_omitted_but_cannot_be_cleared() {
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn generic_global_profiles_decode_native_providers_and_reject_legacy_conflicts() {
|
||||
async fn global_profiles_decode_native_providers_and_reject_conflicting_openai_settings() {
|
||||
let mut body = update_body();
|
||||
body["providerRequestProfiles"] = json!({
|
||||
"openai":{"preset":"desktop"},
|
||||
|
||||
@@ -198,7 +198,7 @@ mod response {
|
||||
response_json(generic).await,
|
||||
json!({
|
||||
"code": 42902,
|
||||
"message": "请求过于频繁,请稍后重试",
|
||||
"message": "请求过于频繁",
|
||||
"data": null
|
||||
})
|
||||
);
|
||||
@@ -212,7 +212,7 @@ mod response {
|
||||
response_json(login).await,
|
||||
json!({
|
||||
"code": 42901,
|
||||
"message": "登录尝试过多,请稍后重试",
|
||||
"message": "登录尝试过多",
|
||||
"data": null
|
||||
})
|
||||
);
|
||||
|
||||
@@ -345,7 +345,7 @@ async fn records_keep_pagination_and_hide_admin_and_upstream_data() {
|
||||
assert_eq!(data.records.len(), 3);
|
||||
for (query, status) in data.records.iter().zip([
|
||||
UsageRecordStatus::Success,
|
||||
UsageRecordStatus::Error,
|
||||
UsageRecordStatus::Error(None),
|
||||
UsageRecordStatus::All,
|
||||
]) {
|
||||
assert_eq!(query.status, status);
|
||||
|
||||
@@ -228,6 +228,46 @@ fn desktop_headers_should_take_precedence_over_embedded_cli_marker() {
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn desktop_hosted_tui_should_use_core_unless_a_desktop_version_is_supplied() {
|
||||
for (core, version_header, kind, version) in [
|
||||
("0.170.0", None, CodexClientKind::Cli, Some("0.170.0")),
|
||||
(
|
||||
"0.170.0",
|
||||
Some("0.170.0"),
|
||||
CodexClientKind::Cli,
|
||||
Some("0.170.0"),
|
||||
),
|
||||
("invalid", None, CodexClientKind::Cli, None),
|
||||
(
|
||||
"0.170.0",
|
||||
Some("26.1023.51421"),
|
||||
CodexClientKind::Desktop,
|
||||
Some("26.1023.51421"),
|
||||
),
|
||||
("0.170.0", Some("invalid"), CodexClientKind::Desktop, None),
|
||||
] {
|
||||
let mut headers = HeaderMap::new();
|
||||
headers.insert("originator", HeaderValue::from_static("Codex Desktop"));
|
||||
headers.insert(
|
||||
"user-agent",
|
||||
HeaderValue::from_str(&format!(
|
||||
"Codex Desktop/{core} (Ubuntu 26.4.0; aarch64) xterm-256color (codex-tui; 0.169.0)"
|
||||
))
|
||||
.unwrap(),
|
||||
);
|
||||
if let Some(value) = version_header {
|
||||
headers.insert("version", HeaderValue::from_static(value));
|
||||
}
|
||||
let client = identify_codex_client(&headers).unwrap();
|
||||
assert_eq!(client.kind(), kind);
|
||||
assert_eq!(
|
||||
client.version().map(ToString::to_string).as_deref(),
|
||||
version
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn official_core_clients_should_use_the_core_version_instead_of_the_app_suffix() {
|
||||
for product in [
|
||||
@@ -322,7 +362,7 @@ fn chatgpt_remote_desktop_without_app_version_should_not_use_a_version_gate() {
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn chatgpt_remote_marker_should_require_a_complete_exact_client_suffix() {
|
||||
fn desktop_should_require_a_complete_exact_client_suffix() {
|
||||
for suffix in [
|
||||
"(codex_chatgpt_android_remote_extra; dev)",
|
||||
"(unofficial_codex_chatgpt_ios_remote; dev)",
|
||||
@@ -340,6 +380,9 @@ fn chatgpt_remote_marker_should_require_a_complete_exact_client_suffix() {
|
||||
"(Codex Desktop; ) (codex_chatgpt_android_remote; dev)",
|
||||
"(Codex Desktop; invalid) (codex_chatgpt_ios_remote; dev)",
|
||||
"(Codex Desktop)",
|
||||
"(codex-tui-custom; 0.169.0)",
|
||||
"(codex-tui; 0.169.0) trailing",
|
||||
"(codex-tui; )",
|
||||
] {
|
||||
let mut headers = HeaderMap::new();
|
||||
headers.insert(
|
||||
@@ -395,19 +438,23 @@ fn chatgpt_remote_marker_should_not_override_an_existing_desktop_version_suffix(
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn chatgpt_remote_suffix_created_by_header_truncation_should_not_skip_the_gate() {
|
||||
let suffix = " (codex_chatgpt_android_remote; dev)";
|
||||
let mut user_agent = "Codex Desktop/0.154.0-alpha.6.2 ".to_owned();
|
||||
user_agent.push_str(&"x".repeat(4096 - user_agent.len() - suffix.len()));
|
||||
user_agent.push_str(suffix);
|
||||
user_agent.push_str(" (another_client; dev)");
|
||||
let mut headers = HeaderMap::new();
|
||||
headers.insert("user-agent", HeaderValue::from_str(&user_agent).unwrap());
|
||||
fn truncated_client_suffix_should_not_change_the_desktop_gate() {
|
||||
for suffix in [
|
||||
" (codex_chatgpt_android_remote; dev)",
|
||||
" (codex-tui; 0.169.0)",
|
||||
] {
|
||||
let mut user_agent = "Codex Desktop/0.154.0-alpha.6.2 ".to_owned();
|
||||
user_agent.push_str(&"x".repeat(4096 - user_agent.len() - suffix.len()));
|
||||
user_agent.push_str(suffix);
|
||||
user_agent.push_str(" (another_client; dev)");
|
||||
let mut headers = HeaderMap::new();
|
||||
headers.insert("user-agent", HeaderValue::from_str(&user_agent).unwrap());
|
||||
|
||||
let client =
|
||||
identify_codex_client(&headers).expect("incomplete headers still require a version");
|
||||
assert_eq!(client.kind(), CodexClientKind::Desktop);
|
||||
assert!(client.version().is_none());
|
||||
let client =
|
||||
identify_codex_client(&headers).expect("incomplete headers still require a version");
|
||||
assert_eq!(client.kind(), CodexClientKind::Desktop);
|
||||
assert!(client.version().is_none());
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
|
||||
@@ -743,7 +743,7 @@ async fn request_context_should_resolve_forwarded_precedence_and_peer_fallback()
|
||||
operation_kind: OperationKind::Generate,
|
||||
input: Some(json!("hello")),
|
||||
client_metadata: None,
|
||||
// 客户端 User-Agent 仅用于本地展示,不再透传给上游指纹上下文
|
||||
// 客户端 User-Agent 仅用于本地展示
|
||||
protocol_context: Some(json!({"opaque_request_headers": [
|
||||
["cf-connecting-ip", STANDARD.encode(b"198.51.100.1")],
|
||||
["x-real-ip", STANDARD.encode(b"198.51.100.2")],
|
||||
@@ -1378,27 +1378,40 @@ async fn streaming_error_after_initial_keepalive_should_be_a_terminal_sse_failur
|
||||
}
|
||||
|
||||
#[tokio::test(start_paused = true)]
|
||||
async fn streaming_late_upstream_error_should_preserve_extended_error_fields() {
|
||||
async fn streaming_bad_request_preserves_extended_error_fields_before_and_after_keepalive() {
|
||||
let mut error = json!({
|
||||
"type": "invalid_request_error", "code": "misalignment_policy_violation",
|
||||
"message": "synthetic policy error", "misalignment": {"category": "synthetic"},
|
||||
"extension": {"opaque": true}
|
||||
});
|
||||
let failure = ProviderError::new(ProviderErrorKind::InvalidRequest, UpstreamSendState::Sent)
|
||||
.with_client_visible_upstream_response(
|
||||
ClientVisibleUpstreamResponse::new(
|
||||
400,
|
||||
Some(b"application/json".to_vec()),
|
||||
Bytes::from(json!({"error": error}).to_string()),
|
||||
let failure = || {
|
||||
ProviderError::new(ProviderErrorKind::InvalidRequest, UpstreamSendState::Sent)
|
||||
.with_client_visible_upstream_response(
|
||||
ClientVisibleUpstreamResponse::new(
|
||||
400,
|
||||
Some(b"application/json".to_vec()),
|
||||
Bytes::from(json!({"error": error}).to_string()),
|
||||
)
|
||||
.with_headers(headers(&[("retry-after", "7")])),
|
||||
)
|
||||
.with_headers(headers(&[("retry-after", "7")])),
|
||||
);
|
||||
error["headers"] = json!({"retry-after": "7"});
|
||||
};
|
||||
let immediate = FakeSession::streaming(
|
||||
Arc::new(Trace::default()),
|
||||
vec![NextStep::Error(EngineError::Provider(failure()))],
|
||||
);
|
||||
let response = stream_execution_response(Box::new(immediate), None).await;
|
||||
assert_eq!(response.status(), StatusCode::BAD_REQUEST);
|
||||
assert_eq!(response.headers()[CONTENT_TYPE], "application/json");
|
||||
let bytes = to_bytes(response.into_body(), usize::MAX).await.unwrap();
|
||||
assert_eq!(
|
||||
serde_json::from_slice::<Value>(&bytes).unwrap(),
|
||||
json!({"error": error})
|
||||
);
|
||||
let session = FakeSession::streaming(
|
||||
Arc::new(Trace::default()),
|
||||
vec![NextStep::DelayedError(
|
||||
Duration::from_secs(30),
|
||||
EngineError::Provider(failure),
|
||||
EngineError::Provider(failure()),
|
||||
)],
|
||||
);
|
||||
let response = stream_execution_response(Box::new(session), None).await;
|
||||
@@ -1410,6 +1423,7 @@ async fn streaming_late_upstream_error_should_preserve_extended_error_fields() {
|
||||
.find(|event| event.event.as_deref() == Some("response.failed"))
|
||||
.unwrap();
|
||||
let payload: Value = serde_json::from_str(&failed.data).unwrap();
|
||||
error["headers"] = json!({"retry-after": "7"});
|
||||
assert_eq!(payload["response"]["error"], error);
|
||||
assert!(bytes.ends_with(b"data: [DONE]\n\n"));
|
||||
}
|
||||
@@ -2954,20 +2968,21 @@ struct SessionExecution {
|
||||
#[tokio::test]
|
||||
async fn official_core_clients_should_be_version_checked_before_starting_responses() {
|
||||
let admin = crate::admin::AdminTestFixture::new().await.services;
|
||||
for product in [
|
||||
"codex-tui",
|
||||
"codex_exec",
|
||||
"codex_vscode",
|
||||
"codex_sdk_ts",
|
||||
"codex_python_sdk",
|
||||
for (product, client) in [
|
||||
("codex-tui", "codex-tui"),
|
||||
("codex_exec", "codex_exec"),
|
||||
("codex_vscode", "codex_vscode"),
|
||||
("codex_sdk_ts", "codex_sdk_ts"),
|
||||
("codex_python_sdk", "codex_python_sdk"),
|
||||
("Codex Desktop", "codex-tui"),
|
||||
] {
|
||||
for (version, allowed) in [("0.158.0", false), ("0.162.0", true)] {
|
||||
for (version, allowed) in [("0.168.0", false), ("0.170.0", true)] {
|
||||
let trace = Arc::new(Trace::default());
|
||||
let execution = Arc::new(SessionExecution {
|
||||
client: authenticated_client_with_min_versions(
|
||||
"sk_version_test",
|
||||
None,
|
||||
Some("0.162.0"),
|
||||
Some("26.1023.51421"),
|
||||
Some("0.170.0"),
|
||||
),
|
||||
session: Mutex::new(Some(Box::new(FakeSession::streaming(
|
||||
Arc::clone(&trace),
|
||||
@@ -2985,7 +3000,7 @@ async fn official_core_clients_should_be_version_checked_before_starting_respons
|
||||
let request = Request::post("/v1/responses")
|
||||
.header(AUTHORIZATION, "Bearer sk_version_test")
|
||||
.header("user-agent", format!(
|
||||
"{product}/{version} (Mac OS 26.6.2; arm64) Apple_Terminal ({product}; 0.165.0)"
|
||||
"{product}/{version} (Ubuntu 26.4.0; aarch64) xterm-256color ({client}; 0.169.0)"
|
||||
))
|
||||
.body(Body::from(json!({"model": "model-a", "input": "synthetic", "stream": true}).to_string()))
|
||||
.unwrap();
|
||||
@@ -3006,8 +3021,9 @@ async fn official_core_clients_should_be_version_checked_before_starting_respons
|
||||
assert_eq!(status, StatusCode::BAD_REQUEST, "{product}/{version}");
|
||||
let value: Value = serde_json::from_slice(&body).unwrap();
|
||||
assert_eq!(value["error"]["code"], "client_version_too_old");
|
||||
assert_eq!(value["error"]["client"], "codex_cli");
|
||||
assert_eq!(value["error"]["current_version"], version);
|
||||
assert_eq!(value["error"]["min_version"], "0.162.0");
|
||||
assert_eq!(value["error"]["min_version"], "0.170.0");
|
||||
assert!(execution.session.lock().unwrap().is_some());
|
||||
}
|
||||
}
|
||||
|
||||
@@ -492,7 +492,7 @@ fn decoder_should_strip_http_transport_but_leave_source_headers_for_provider() {
|
||||
HeaderValue::from_static(r#"{"scheme":"https"}"#),
|
||||
);
|
||||
headers.insert("accept-encoding", HeaderValue::from_static("br, gzip"));
|
||||
// 正文未压缩;入口现在消费 Content-Encoding,但仍不得向上游透传
|
||||
// identity 与未压缩的正文匹配,Content-Encoding 由入口消费
|
||||
headers.insert("content-encoding", HeaderValue::from_static("identity"));
|
||||
headers.insert("x-openai-future-mode", HeaderValue::from_static("keep"));
|
||||
|
||||
|
||||
+1
-1
@@ -358,7 +358,7 @@ async fn rewrite_upgrade_and_control_active_response_keep_http_context_until_con
|
||||
);
|
||||
let (trace, mut socket, server) =
|
||||
start_active_response_with(Some(frozen), "/custom/websocket", "codex-tui/0.166.0").await;
|
||||
// 升级后的默认会话仍持有入口上下文;101 正文结束不再提前取消它
|
||||
// 101 响应完成后,WebSocket 会话继续持有入口上下文
|
||||
assert!(
|
||||
!plan
|
||||
.http_cancellation
|
||||
|
||||
@@ -255,7 +255,7 @@ impl Stream for TestSocket {
|
||||
|
||||
fn poll_next(mut self: Pin<&mut Self>, context: &mut Context<'_>) -> Poll<Option<Self::Item>> {
|
||||
let event = self.incoming.poll_recv(context);
|
||||
// 模拟 Axum transport 的自动 Pong;pump 不再重复实现协议层应答
|
||||
// 模拟 Axum 传输层收到 Ping 时自动回复 Pong
|
||||
if let Poll::Ready(Some(Ok(Message::Ping(payload)))) = &event {
|
||||
self.written
|
||||
.send(Message::Pong(payload.clone()))
|
||||
|
||||
@@ -1227,12 +1227,16 @@ fn upgrade_request(authorization: &str) -> Request<Body> {
|
||||
|
||||
#[tokio::test]
|
||||
async fn official_core_version_gate_should_run_before_websocket_upgrade() {
|
||||
let app = api_router(ModelsExecution::with_cli_min("0.162.0")).await;
|
||||
let app = api_router(ModelsExecution::with_cli_min("0.170.0")).await;
|
||||
let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
|
||||
let address = listener.local_addr().unwrap();
|
||||
let server = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
|
||||
|
||||
for version in ["0.158.0", "0.162.0"] {
|
||||
for (product, version) in [
|
||||
("codex-tui", "0.158.0"),
|
||||
("Codex Desktop", "0.168.0"),
|
||||
("Codex Desktop", "0.170.0"),
|
||||
] {
|
||||
let mut request = format!("ws://{address}/v1/responses")
|
||||
.into_client_request()
|
||||
.unwrap();
|
||||
@@ -1243,12 +1247,12 @@ async fn official_core_version_gate_should_run_before_websocket_upgrade() {
|
||||
request.headers_mut().insert(
|
||||
"user-agent",
|
||||
HeaderValue::from_str(&format!(
|
||||
"codex-tui/{version} (Mac OS 26.6.2; arm64) Apple_Terminal (codex-tui; 0.165.0)"
|
||||
"{product}/{version} (Ubuntu 26.4.0; aarch64) xterm-256color (codex-tui; 0.169.0)"
|
||||
))
|
||||
.unwrap(),
|
||||
);
|
||||
let result = connect_async(request).await;
|
||||
if version == "0.162.0" {
|
||||
if version == "0.170.0" {
|
||||
let (mut socket, response) = result.expect("current Core upgrades successfully");
|
||||
assert_eq!(response.status(), StatusCode::SWITCHING_PROTOCOLS);
|
||||
socket.close(None).await.unwrap();
|
||||
@@ -1261,8 +1265,9 @@ async fn official_core_version_gate_should_run_before_websocket_upgrade() {
|
||||
assert_eq!(response.status(), StatusCode::BAD_REQUEST);
|
||||
let value: Value = serde_json::from_slice(response.body().as_deref().unwrap()).unwrap();
|
||||
assert_eq!(value["error"]["code"], "client_version_too_old");
|
||||
assert_eq!(value["error"]["current_version"], "0.158.0");
|
||||
assert_eq!(value["error"]["min_version"], "0.162.0");
|
||||
assert_eq!(value["error"]["client"], "codex_cli");
|
||||
assert_eq!(value["error"]["current_version"], version);
|
||||
assert_eq!(value["error"]["min_version"], "0.170.0");
|
||||
}
|
||||
}
|
||||
server.abort();
|
||||
|
||||
@@ -37,7 +37,7 @@ use crate::event::{
|
||||
use crate::lifecycle::{CancellationToken, Deadline, LeaseGuard};
|
||||
use crate::metering::Decimal;
|
||||
use crate::operation::{Operation, ProviderSessionState};
|
||||
use crate::routing::RoutingPlan;
|
||||
use crate::routing::{ProviderCandidate, RoutingPlan};
|
||||
use futures::future::{BoxFuture, Fuse};
|
||||
use futures::{FutureExt, StreamExt, pin_mut, select_biased};
|
||||
use futures_timer::Delay;
|
||||
@@ -1239,142 +1239,11 @@ where
|
||||
}
|
||||
ProviderBoundary::Result(result) => match *result {
|
||||
Ok(stream) => stream,
|
||||
Err(mut error) => {
|
||||
attempt_trace.record_provider_failure(&error);
|
||||
if self.continuation_attempt == ContinuationAttempt::RotateForClientReplay
|
||||
&& error.continuation_recovery_disposition()
|
||||
== Some(ContinuationRecoveryDisposition::ClientReplayRequired)
|
||||
&& let Some(original) = self.last_retryable_failure.take()
|
||||
{
|
||||
// 迁移只改变客户端恢复指令;失败分类、发送事实与运维正文仍属于原请求
|
||||
error = original.with_client_recovery_from(error);
|
||||
self.last_retryable_failure_events.clear();
|
||||
}
|
||||
let connection_fallback = self.connection_rotation.is_some()
|
||||
&& self
|
||||
.last_retryable_failure
|
||||
.as_ref()
|
||||
.and_then(ProviderError::unreachable_proxy)
|
||||
.is_none()
|
||||
&& !self.connection_budget.exhausted()
|
||||
&& !error.retry_is_prohibited()
|
||||
&& error.send_state() == UpstreamSendState::NotSent
|
||||
&& matches!(
|
||||
error.kind(),
|
||||
ProviderErrorKind::NoEligibleAccount
|
||||
| ProviderErrorKind::AccountCapacityUnavailable
|
||||
| ProviderErrorKind::QuotaExhausted
|
||||
| ProviderErrorKind::ConcurrencyQueueFull
|
||||
| ProviderErrorKind::ConcurrencyQueueTimeout
|
||||
);
|
||||
let continuation_retry = !error.retry_is_prohibited()
|
||||
&& self.prepare_unavailable_native_continuation_replay(&error);
|
||||
let candidate_retry = !error.retry_is_prohibited() && !connection_fallback && !continuation_retry
|
||||
&& matches!(
|
||||
error.kind(),
|
||||
ProviderErrorKind::AccountCapacityUnavailable
|
||||
| ProviderErrorKind::NoEligibleAccount
|
||||
| ProviderErrorKind::QuotaExhausted
|
||||
| ProviderErrorKind::ProviderInfrastructureUnavailable
|
||||
| ProviderErrorKind::ConcurrencyQueueFull
|
||||
| ProviderErrorKind::ConcurrencyQueueTimeout
|
||||
)
|
||||
&& error.send_state() == UpstreamSendState::NotSent
|
||||
&& self.current_send_state() == UpstreamSendState::NotSent
|
||||
&& matches!(
|
||||
self.continuation_attempt,
|
||||
ContinuationAttempt::None | ContinuationAttempt::ReplayAny
|
||||
)
|
||||
// 跨 Provider 候选推进必然换号(账号行按 Provider 隔离),
|
||||
// 预算耗尽后不再推进,交回容量类失败的原有终态语义。
|
||||
&& self.has_account_rotation_budget()
|
||||
&& self.advance_provider_candidate();
|
||||
let retryable = self
|
||||
.apply_retry_policy(super::policy::RetryFacts {
|
||||
attempt_index: next_attempt,
|
||||
provider: candidate.provider().clone(),
|
||||
model: candidate
|
||||
.upstream_model()
|
||||
.map(|model| model.as_str().to_owned()),
|
||||
error_kind: error.kind(),
|
||||
upstream_status: error.upstream_status(),
|
||||
send_state: error.send_state(),
|
||||
remaining_routing_attempts: self
|
||||
.plan
|
||||
.max_attempts()
|
||||
.get()
|
||||
.saturating_sub(self.routing_attempts),
|
||||
remaining_deadline: Duration::ZERO,
|
||||
retry_allowed: connection_fallback
|
||||
|| continuation_retry
|
||||
|| candidate_retry,
|
||||
})
|
||||
.await?;
|
||||
attempt_trace.record("retry.decided", json!({
|
||||
"phase": "prepare", "retryable": retryable,
|
||||
"continuationRetry": continuation_retry, "candidateRetry": candidate_retry,
|
||||
"connectionFallback": connection_fallback,
|
||||
"retryProhibited": error.retry_is_prohibited(),
|
||||
"sendState": error.send_state().as_str(),
|
||||
"requestSendState": self.current_send_state().as_str(),
|
||||
"continuation": format!("{:?}", self.continuation_attempt),
|
||||
"accountRotations": self.account_rotations,
|
||||
"maxAccountRotations": self.plan.account_selection_policy().max_account_rotations(),
|
||||
"remainingRoutingAttempts": self.plan.max_attempts().get().saturating_sub(self.routing_attempts),
|
||||
}));
|
||||
if retryable {
|
||||
if connection_fallback {
|
||||
let recovery = self
|
||||
.connection_rotation
|
||||
.take()
|
||||
.expect("pending connection rotation");
|
||||
self.excluded_accounts.remove(&recovery.account);
|
||||
self.pending_retry = Some(recovery);
|
||||
} else if candidate_retry {
|
||||
// 原账号只属于原 Provider,跨候选后不能拿旧钉选作恢复兜底
|
||||
self.connection_rotation = None;
|
||||
}
|
||||
return Ok(Some(PullOutcome::AttemptDiscarded));
|
||||
}
|
||||
if matches!(
|
||||
error.kind(),
|
||||
ProviderErrorKind::AccountCapacityUnavailable
|
||||
| ProviderErrorKind::NoEligibleAccount
|
||||
| ProviderErrorKind::SessionPolicyRestricted
|
||||
| ProviderErrorKind::QuotaExhausted
|
||||
| ProviderErrorKind::ConcurrencyQueueFull
|
||||
| ProviderErrorKind::ConcurrencyQueueTimeout
|
||||
) && let Some(last_failure) = self.last_retryable_failure.take()
|
||||
{
|
||||
let send_state = self.current_send_state();
|
||||
let mut events = std::mem::take(&mut self.last_retryable_failure_events);
|
||||
if !events.is_empty() {
|
||||
self.observe_atomic_terminal_events(&mut events);
|
||||
self.budget_attempt_already_counted = true;
|
||||
return Ok(Some(PullOutcome::TerminalFailure {
|
||||
events,
|
||||
error: last_failure,
|
||||
send_state,
|
||||
}));
|
||||
}
|
||||
self.finish_provider_error(&last_failure).await?;
|
||||
return Err(provider_engine_error(last_failure));
|
||||
}
|
||||
if !(matches!(
|
||||
error.kind(),
|
||||
ProviderErrorKind::AccountCapacityUnavailable
|
||||
| ProviderErrorKind::NoEligibleAccount
|
||||
| ProviderErrorKind::SessionPolicyRestricted
|
||||
| ProviderErrorKind::QuotaExhausted
|
||||
| ProviderErrorKind::ProviderInfrastructureUnavailable
|
||||
| ProviderErrorKind::ConcurrencyQueueFull
|
||||
| ProviderErrorKind::ConcurrencyQueueTimeout
|
||||
) && error.send_state() == UpstreamSendState::NotSent)
|
||||
{
|
||||
self.record_provider_failure(candidate.provider().clone());
|
||||
}
|
||||
self.finish_provider_error(&error).await?;
|
||||
return Err(provider_engine_error(error));
|
||||
Err(error) => {
|
||||
return self
|
||||
.handle_prepare_failure(error, &candidate, next_attempt, &attempt_trace)
|
||||
.await
|
||||
.map(Some);
|
||||
}
|
||||
},
|
||||
};
|
||||
@@ -1560,6 +1429,131 @@ where
|
||||
Ok(None)
|
||||
}
|
||||
|
||||
async fn handle_prepare_failure(
|
||||
&mut self,
|
||||
mut error: ProviderError,
|
||||
candidate: &ProviderCandidate,
|
||||
next_attempt: NonZeroU32,
|
||||
attempt_trace: &TraceContext,
|
||||
) -> Result<PullOutcome, EngineError> {
|
||||
attempt_trace.record_provider_failure(&error);
|
||||
if self.continuation_attempt == ContinuationAttempt::RotateForClientReplay
|
||||
&& error.continuation_recovery_disposition()
|
||||
== Some(ContinuationRecoveryDisposition::ClientReplayRequired)
|
||||
&& let Some(original) = self.last_retryable_failure.take()
|
||||
{
|
||||
// 迁移只改变客户端恢复指令;失败分类、发送事实与运维正文仍属于原请求
|
||||
error = original.with_client_recovery_from(error);
|
||||
self.last_retryable_failure_events.clear();
|
||||
}
|
||||
let kind = error.kind();
|
||||
let account_unavailable = matches!(
|
||||
kind,
|
||||
ProviderErrorKind::NoEligibleAccount
|
||||
| ProviderErrorKind::AccountCapacityUnavailable
|
||||
| ProviderErrorKind::QuotaExhausted
|
||||
| ProviderErrorKind::ConcurrencyQueueFull
|
||||
| ProviderErrorKind::ConcurrencyQueueTimeout
|
||||
);
|
||||
let infrastructure_unavailable =
|
||||
kind == ProviderErrorKind::ProviderInfrastructureUnavailable;
|
||||
let selection_failed =
|
||||
account_unavailable || kind == ProviderErrorKind::SessionPolicyRestricted;
|
||||
let not_sent = error.send_state() == UpstreamSendState::NotSent;
|
||||
let retry_allowed = !error.retry_is_prohibited();
|
||||
let connection_fallback = self.connection_rotation.is_some()
|
||||
&& self
|
||||
.last_retryable_failure
|
||||
.as_ref()
|
||||
.and_then(ProviderError::unreachable_proxy)
|
||||
.is_none()
|
||||
&& !self.connection_budget.exhausted()
|
||||
&& retry_allowed
|
||||
&& not_sent
|
||||
&& account_unavailable;
|
||||
let continuation_retry =
|
||||
retry_allowed && self.prepare_unavailable_native_continuation_replay(&error);
|
||||
let candidate_retry = retry_allowed
|
||||
&& !connection_fallback
|
||||
&& !continuation_retry
|
||||
&& (account_unavailable || infrastructure_unavailable)
|
||||
&& not_sent
|
||||
&& self.current_send_state() == UpstreamSendState::NotSent
|
||||
&& matches!(
|
||||
self.continuation_attempt,
|
||||
ContinuationAttempt::None | ContinuationAttempt::ReplayAny
|
||||
)
|
||||
// 跨 Provider 候选推进必然换号(账号行按 Provider 隔离),
|
||||
// 预算耗尽后不再推进,交回容量类失败的原有终态语义
|
||||
&& self.has_account_rotation_budget()
|
||||
&& self.advance_provider_candidate();
|
||||
let retryable = self
|
||||
.apply_retry_policy(super::policy::RetryFacts {
|
||||
attempt_index: next_attempt,
|
||||
provider: candidate.provider().clone(),
|
||||
model: candidate
|
||||
.upstream_model()
|
||||
.map(|model| model.as_str().to_owned()),
|
||||
error_kind: kind,
|
||||
upstream_status: error.upstream_status(),
|
||||
send_state: error.send_state(),
|
||||
remaining_routing_attempts: self
|
||||
.plan
|
||||
.max_attempts()
|
||||
.get()
|
||||
.saturating_sub(self.routing_attempts),
|
||||
remaining_deadline: Duration::ZERO,
|
||||
retry_allowed: connection_fallback || continuation_retry || candidate_retry,
|
||||
})
|
||||
.await?;
|
||||
attempt_trace.record("retry.decided", json!({
|
||||
"phase": "prepare", "retryable": retryable,
|
||||
"continuationRetry": continuation_retry, "candidateRetry": candidate_retry,
|
||||
"connectionFallback": connection_fallback,
|
||||
"retryProhibited": error.retry_is_prohibited(),
|
||||
"sendState": error.send_state().as_str(),
|
||||
"requestSendState": self.current_send_state().as_str(),
|
||||
"continuation": format!("{:?}", self.continuation_attempt),
|
||||
"accountRotations": self.account_rotations,
|
||||
"maxAccountRotations": self.plan.account_selection_policy().max_account_rotations(),
|
||||
"remainingRoutingAttempts": self.plan.max_attempts().get().saturating_sub(self.routing_attempts),
|
||||
}));
|
||||
if retryable {
|
||||
if connection_fallback {
|
||||
let recovery = self
|
||||
.connection_rotation
|
||||
.take()
|
||||
.expect("pending connection rotation");
|
||||
self.excluded_accounts.remove(&recovery.account);
|
||||
self.pending_retry = Some(recovery);
|
||||
} else if candidate_retry {
|
||||
// 原账号只属于原 Provider,跨候选后不能拿旧钉选作恢复兜底
|
||||
self.connection_rotation = None;
|
||||
}
|
||||
return Ok(PullOutcome::AttemptDiscarded);
|
||||
}
|
||||
if selection_failed && let Some(last_failure) = self.last_retryable_failure.take() {
|
||||
let send_state = self.current_send_state();
|
||||
let mut events = std::mem::take(&mut self.last_retryable_failure_events);
|
||||
if !events.is_empty() {
|
||||
self.observe_atomic_terminal_events(&mut events);
|
||||
self.budget_attempt_already_counted = true;
|
||||
return Ok(PullOutcome::TerminalFailure {
|
||||
events,
|
||||
error: last_failure,
|
||||
send_state,
|
||||
});
|
||||
}
|
||||
self.finish_provider_error(&last_failure).await?;
|
||||
return Err(provider_engine_error(last_failure));
|
||||
}
|
||||
if !(not_sent && (selection_failed || infrastructure_unavailable)) {
|
||||
self.record_provider_failure(candidate.provider().clone());
|
||||
}
|
||||
self.finish_provider_error(&error).await?;
|
||||
Err(provider_engine_error(error))
|
||||
}
|
||||
|
||||
fn advance_provider_candidate(&mut self) -> bool {
|
||||
let Some(next) = self.candidate_index.checked_add(1) else {
|
||||
return false;
|
||||
@@ -2063,7 +2057,11 @@ where
|
||||
.pending_terminal_failure
|
||||
.as_ref()
|
||||
.ok_or(EngineError::NoActiveAttempt)?;
|
||||
if pending.events.is_empty() {
|
||||
// 在保活提交前冻结 HTTP 错误,否则必须交付原流内事件
|
||||
if pending.events.is_empty()
|
||||
|| (pending.error.client_visible_upstream_response().is_some()
|
||||
&& self.response_commit.finish())
|
||||
{
|
||||
return Err(provider_engine_error(
|
||||
self.finalize_pending_terminal_failure().await?,
|
||||
));
|
||||
|
||||
@@ -42,9 +42,12 @@ impl ResponseCommit {
|
||||
self.committed_at().is_some()
|
||||
}
|
||||
|
||||
pub(crate) fn finish(&self) {
|
||||
// 执行已结束且未提交时保留原 HTTP 错误,不能因外层插件迟迟返回再改成 200
|
||||
let _ = self.first.set(TransportState::Finished);
|
||||
/// 冻结交付状态,返回是否仍可发送独立的 HTTP 错误响应
|
||||
pub(crate) fn finish(&self) -> bool {
|
||||
matches!(
|
||||
self.first.get_or_init(|| TransportState::Finished),
|
||||
TransportState::Finished
|
||||
)
|
||||
}
|
||||
|
||||
#[must_use]
|
||||
|
||||
@@ -643,6 +643,11 @@ impl AttemptContext {
|
||||
self.request.client_transport
|
||||
}
|
||||
|
||||
#[must_use]
|
||||
pub fn endpoint(&self) -> &str {
|
||||
self.request.endpoint()
|
||||
}
|
||||
|
||||
/// 原生响应可交付可替换前导事件;中间件可能改变其输出语义
|
||||
#[must_use]
|
||||
pub fn allows_replayable_prelude(&self) -> bool {
|
||||
|
||||
@@ -425,7 +425,7 @@ impl ProviderConnectionObservation {
|
||||
|
||||
/// 只供当前客户端请求使用的 HTTP 失败响应
|
||||
///
|
||||
/// 通常保留原始上游响应;Provider 也可为明确的恢复流程准备客户端投影
|
||||
/// Provider 可透传上游 HTTP 响应,也可按客户端协议构造错误正文
|
||||
/// 投影不能覆盖 [`ProviderError`] 中用于诊断和记账的真实上游事实
|
||||
///
|
||||
/// 该值不属于稳定诊断事实,不能进入日志或持久化
|
||||
@@ -833,7 +833,7 @@ impl ProviderError {
|
||||
self
|
||||
}
|
||||
|
||||
/// 附加仅可返回给当前请求方的原始上游 HTTP 失败响应
|
||||
/// 附加仅可返回给当前请求方的 HTTP 失败响应
|
||||
#[must_use]
|
||||
pub fn with_client_visible_upstream_response(
|
||||
mut self,
|
||||
@@ -1018,7 +1018,7 @@ impl ProviderError {
|
||||
self.client_visible_upstream_error.as_deref()
|
||||
}
|
||||
|
||||
/// 返回只供当前协议响应使用的原始上游 HTTP 失败响应
|
||||
/// 返回仅供当前请求方使用的 HTTP 失败响应
|
||||
#[must_use]
|
||||
pub fn client_visible_upstream_response(&self) -> Option<&ClientVisibleUpstreamResponse> {
|
||||
self.client_visible_upstream_response.as_deref()
|
||||
|
||||
@@ -143,10 +143,10 @@ fn zero_or_absent_window_weights_disable_reset_scores_and_tolerance() {
|
||||
}]
|
||||
.into(),
|
||||
);
|
||||
let legacy = json!({"loadWeight":0,"quotaWeight":0,"healthWeight":0,"latencyWeight":0,"resetWeight":10,"queueWeight":0});
|
||||
let mut disabled = legacy.clone();
|
||||
let omitted = json!({"loadWeight":0,"quotaWeight":0,"healthWeight":0,"latencyWeight":0,"resetWeight":10,"queueWeight":0});
|
||||
let mut disabled = omitted.clone();
|
||||
disabled["resetWindowWeights"] = json!({"fiveHour":0,"weekly":0,"monthly":0});
|
||||
for wire in [legacy, disabled] {
|
||||
for wire in [omitted, disabled] {
|
||||
let config: SmartSchedulingConfig = serde_json::from_value(wire).unwrap();
|
||||
context.policy = context.policy.with_smart_scheduling(config);
|
||||
let trace = gateway_core::diagnostics::TraceContext::new("req_zero_windows");
|
||||
|
||||
@@ -7436,6 +7436,80 @@ fn transport_keepalive_preserves_pre_output_recovery_and_first_business_commit()
|
||||
assert!(state.finalizations[0].committed);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn atomic_http_failure_uses_wire_only_after_downstream_data_or_keepalive() {
|
||||
for (prelude, keepalive) in [(false, false), (true, false), (false, true)] {
|
||||
let operation = generate_operation();
|
||||
let route_plan = plan(&operation);
|
||||
let detail = json!({"code":"invalid_value", "message":"Invalid input."});
|
||||
let wire = json!({"type":"error","status":400,"error":detail});
|
||||
let mut items = Vec::new();
|
||||
if prelude {
|
||||
items.push(Ok(ProviderEvent::canonical(GatewayEvent::Started(
|
||||
ResponseMeta::new("response-1", "gpt-5"),
|
||||
))
|
||||
.with_replayable_prelude()));
|
||||
}
|
||||
items.push(Err(ProviderError::new(
|
||||
ProviderErrorKind::InvalidRequest,
|
||||
UpstreamSendState::Sent,
|
||||
)
|
||||
.with_status(400)
|
||||
.with_client_visible_upstream_response(ClientVisibleUpstreamResponse::new(
|
||||
400,
|
||||
Some(b"application/json".to_vec()),
|
||||
Bytes::from(json!({"error":detail}).to_string()),
|
||||
))
|
||||
.with_atomic_client_events(vec![ProviderEvent::wire(
|
||||
ProtocolWireEvent::json("openai", Some("error".into()), wire.clone()).unwrap(),
|
||||
)])));
|
||||
let (coordinator, store, _) = coordinator(vec![Script::ObservedStream {
|
||||
account_id: "acct_first",
|
||||
items,
|
||||
}]);
|
||||
let mut session = block_on(coordinator.start(
|
||||
model_request(&operation, SystemTime::now() + Duration::from_secs(30)),
|
||||
operation,
|
||||
route_plan,
|
||||
None,
|
||||
None,
|
||||
CancellationToken::new(),
|
||||
))
|
||||
.unwrap();
|
||||
let transport = session.response_commit();
|
||||
if prelude {
|
||||
block_on(session.next_event()).unwrap().unwrap();
|
||||
block_on(session.commit_downstream(Some(200))).unwrap();
|
||||
}
|
||||
if keepalive {
|
||||
assert!(transport.record(Some(200)));
|
||||
}
|
||||
if prelude || keepalive {
|
||||
let batch = block_on(session.next_event()).unwrap().unwrap();
|
||||
let events = batch.into_provider_events();
|
||||
assert_eq!(events.len(), 1);
|
||||
assert_eq!(events[0].wire_event().unwrap().data(), &wire);
|
||||
if keepalive {
|
||||
block_on(session.commit_downstream(Some(200))).unwrap();
|
||||
}
|
||||
}
|
||||
let EngineError::Provider(error) = block_on(session.next_event()).unwrap_err() else {
|
||||
panic!("expected the upstream bad request");
|
||||
};
|
||||
assert_eq!(
|
||||
error.client_visible_upstream_response().unwrap().status(),
|
||||
400
|
||||
);
|
||||
assert!(session.is_finalized());
|
||||
assert_eq!(transport.record(Some(200)), prelude || keepalive);
|
||||
let state = store.state.lock().unwrap();
|
||||
assert_eq!(state.attempts.len(), 1);
|
||||
assert_eq!(state.finalizations.len(), 1);
|
||||
assert_eq!(state.finalizations[0].committed, prelude || keepalive);
|
||||
assert_eq!(state.finalizations[0].upstream_status_code, Some(400));
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn transport_keepalive_records_late_failure_as_incomplete_http_200() {
|
||||
let operation = generate_operation();
|
||||
|
||||
@@ -69,7 +69,7 @@ fn privacy_rule_requires_steps_and_rejects_unknown_fields() {
|
||||
missing_steps.as_object_mut().unwrap().remove("steps");
|
||||
assert!(serde_json::from_value::<PrivacyRule>(missing_steps).is_err());
|
||||
let mut unknown_rule_field = value.clone();
|
||||
unknown_rule_field["scope"] = serde_json::json!("request_body");
|
||||
unknown_rule_field["unexpected"] = serde_json::json!(true);
|
||||
assert!(serde_json::from_value::<PrivacyRule>(unknown_rule_field).is_err());
|
||||
let mut unknown_step_field = value;
|
||||
unknown_step_field["steps"][0]["unexpected"] = serde_json::json!(true);
|
||||
|
||||
@@ -139,7 +139,7 @@ fn blocked_file_output_keeps_http_and_streaming_responsive_and_reserves_errors()
|
||||
);
|
||||
let (release, released) = std::sync::mpsc::channel();
|
||||
let reader = std::thread::spawn(move || {
|
||||
// 超时只用于让旧的同步实现能退出测试,接口必须在解除阻塞之前完成
|
||||
// 请求必须在读端放行前完成,超时让写入阻塞时的测试也能退出
|
||||
let _ = released.recv_timeout(Duration::from_secs(3));
|
||||
let mut body = String::new();
|
||||
fs::File::open(fifo)
|
||||
|
||||
@@ -327,7 +327,6 @@ async fn managed_http_enforces_the_callers_body_limit_before_sending() {
|
||||
.mount(&server)
|
||||
.await;
|
||||
let client = HttpClient::new().unwrap();
|
||||
// 覆盖旧固定上限之外的正文,并验证同一个客户端逐次使用调用方的预算
|
||||
let maximum = 17 * 1024 * 1024;
|
||||
for (size, limit, accepted) in [
|
||||
(maximum, maximum, true),
|
||||
|
||||
@@ -24,9 +24,9 @@ async fn invalid_update_state_should_keep_raw_details_out_of_public_error() {
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn update_status_should_reconcile_manual_deployment_without_reusing_legacy_success() {
|
||||
async fn manual_deployment_reports_the_running_version_and_preserves_the_last_operation() {
|
||||
let fixture = Fixture::new();
|
||||
fs::write(fixture.state(), r#"{"previousVersion":"3.14.0","currentVersion":"3.14.1","operation":{"operationId":"legacy","kind":"update","status":"succeeded","targetVersion":"3.14.1"}}"#).expect("legacy state");
|
||||
fs::write(fixture.state(), r#"{"previousVersion":"3.14.0","currentVersion":"3.14.1","operation":{"operationId":"completed-update","kind":"update","status":"succeeded","targetVersion":"3.14.1"}}"#).expect("completed update state");
|
||||
let mut config = fixture.config("https://api.github.com/repos");
|
||||
config.version = "3.15.0".to_owned();
|
||||
config.deployment_mode = "docker".to_owned();
|
||||
|
||||
@@ -645,7 +645,7 @@ async fn concurrent_calls_keep_their_wire_ids_monotonic() {
|
||||
}
|
||||
ready.wait().await;
|
||||
entered.await;
|
||||
// 旧实现会在 begin 前分配后续 ID;等其他线程进入该窗口后再释放首调用
|
||||
// 暂停首个 begin,给其他并发调用留出竞争发送顺序的时间
|
||||
tokio::time::sleep(Duration::from_millis(20)).await;
|
||||
callbacks.release();
|
||||
for call in calls {
|
||||
|
||||
@@ -542,8 +542,6 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
|
||||
);
|
||||
if let Some(expected) = configuration.get("expected_fast_source") {
|
||||
let sources = &call.request.head.settings_sources["execution"];
|
||||
assert!(sources.get("disable_fast").is_none());
|
||||
assert!(sources["input"].get("disable_fast").is_none());
|
||||
assert_eq!(sources["input"]["fast_mode"], "default");
|
||||
assert_eq!(&sources["fast_mode"], expected);
|
||||
}
|
||||
|
||||
@@ -1,15 +1,9 @@
|
||||
# Gateway Plugin SDK
|
||||
|
||||
用于编写 Codex Proxy 插件的 Rust 合同与可选会话辅助。插件只依赖本包,不依赖宿主 Core、Admin、Store 或 Host。
|
||||
SDK 包版本为 `0.1.0`,独立于网关版本,处于实验阶段。能力是否可用取决于宿主支持、清单声明与实际注册
|
||||
Rust 插件只需依赖 `gateway-plugin-sdk`。SDK `0.1.0` 处于实验阶段,独立于网关发版。清单、进程协议和能力分别版本化,插件可用能力取决于宿主支持、清单声明与实际注册
|
||||
|
||||
清单、进程协议和各项能力分别版本化,当前版本与声明规则统一见[插件清单](docs/manifest.md)
|
||||
|
||||
开发顺序:编写[清单](docs/manifest.md) → 实现[能力处理器](docs/capabilities.md) → 用 [CLI](../../../apps/plugin-cli/README.md)
|
||||
打包 → [安装、配置与启用](../../../../docs/plugins.md)。完整可运行示例位于独立仓库
|
||||
`codex-proxy-plugins` 的 `examples/workbench`
|
||||
|
||||
使用 AI 协作开发时,可调用仓库技能 [`$cpr-plugin-dev`](../../../../.agents/skills/cpr-plugin-dev/SKILL.md),按任务定位合同、示例和验证入口
|
||||
编写[清单](docs/manifest.md) → 实现[处理器](docs/capabilities.md) → 用 [CLI 打包](../../../apps/plugin-cli/README.md) → [安装并启用](../../../../docs/plugins.md)。
|
||||
完整示例见 `codex-proxy-plugins/examples/workbench`,AI 协作入口见 [cpr-plugin-dev](../../../../.agents/skills/cpr-plugin-dev/SKILL.md)
|
||||
|
||||
## 模块与依赖
|
||||
|
||||
@@ -29,11 +23,7 @@ SDK 包版本为 `0.1.0`,独立于网关版本,处于实验阶段。能力
|
||||
| `call::management` | 管理 API、页面与资源声明、公开回调,以及 CLI 命令与待保存账号 |
|
||||
| `client` | 通过 `io` feature 开启的 `PluginBuilder`、会话、中间件与异步帧收发 |
|
||||
|
||||
`call/` 按业务能力组织数据,`message.rs` 定义消息与帧。已有请求链的请求/响应改写、协议转换和思考参数映射使用
|
||||
`call::middleware`;需要指定业务上游并解析结果时使用 `call::upstream_adapter`,作为洋葱链终端复用宿主账号与结算。
|
||||
下游 WebSocket 改写使用 `websocket` 中间件;上游发送前的请求准备使用 `outbound` 中间件,响应观察接口保留只读合同
|
||||
|
||||
插件使用的导入路径例如:
|
||||
`message.rs` 定义消息与帧。改写现有请求、响应或推理参数使用 `call::middleware`,其中 `websocket` 处理下游消息,`outbound` 处理上游发送前的请求。响应观察只读。需要自行选择业务上游并解析响应时使用 `call::upstream_adapter`
|
||||
|
||||
```rust
|
||||
use gateway_plugin_sdk::{Frame, Message, PluginFault};
|
||||
@@ -42,10 +32,8 @@ use gateway_plugin_sdk::call::{host::ModelEventBatch, model::ExecutionEvent};
|
||||
use gateway_plugin_sdk::client::{read_frame, write_frame};
|
||||
```
|
||||
|
||||
默认 feature 不引入异步运行时。`io` 除帧编解码外,还提供 `PluginBuilder`、
|
||||
`PluginSession::accept/run` 和 `PluginHandler`。组合插件从作者清单建立类型化方法,SDK 自动生成
|
||||
`plugin.register`;作者不需要复制贡献项或手写方法名、阶段和敏感载荷编解码。
|
||||
会话管理握手、有界并发、父调用关联、回调、流信用、取消、排空与关闭,容量与计时见[并发与期限](#并发与期限)
|
||||
默认 feature 不引入异步运行时。`io` 提供帧编解码、`PluginBuilder`、`PluginSession::accept/run` 和 `PluginHandler`。
|
||||
[类型化构建器](docs/capabilities.md#类型化作者入口)按清单注册处理器。会话管理握手、并发、父调用关联、回调、流信用、取消、排空与关闭,容量与计时见[并发与期限](#并发与期限)
|
||||
|
||||
`HostClient::scan_usage_records` 与 `query_usage_statistics` 提供用量明细扫描和完整分组统计,按批读取与关闭见[用量查询](docs/usage-data.md#完整扫描与分组统计)
|
||||
|
||||
@@ -149,9 +137,8 @@ session.run(handler).await?;
|
||||
|
||||
### 帧与会话
|
||||
|
||||
`CallContext.timeout_ms` 限定初始处理期限。宿主对由流或连接 owner 管理的调用设置 `resource_stream`:
|
||||
首个流式结果成功返回后,正文、会话及关联回调由资源取消与终态回收,不再沿用初始期限。
|
||||
普通调用继续使用原期限;资源模式仍保留并发容量、Credit、父调用关联及取消约束
|
||||
普通调用受 `CallContext.timeout_ms` 限制。对标记为 `resource_stream` 的调用,初始期限只到首个流式结果成功返回。
|
||||
其后的正文、会话及回调由资源终态或取消回收,仍受并发容量、Credit 和父调用约束
|
||||
|
||||
协议 v7 的帧头由大端 `u32` 元数据长度和大端 `u64` 载荷长度组成,随后依次传输 JSON 元数据和二进制载荷。
|
||||
元数据保留 64 KiB 上限;正文总量不由插件传输层额外限制。传输内部以 256 KiB 为单次 I/O 块,
|
||||
@@ -210,6 +197,4 @@ RUST_MIN_STACK=16777216 cargo +1.99.1 test --manifest-path backend/Cargo.toml -p
|
||||
RUST_MIN_STACK=16777216 RUSTDOCFLAGS='-D warnings' cargo +1.99.1 doc --manifest-path backend/Cargo.toml -p gateway-plugin-sdk --all-features --no-deps --locked
|
||||
```
|
||||
|
||||
源码中的类型和字段是当前合同;宿主接入、目录边界、内置 Provider 与 Runtime 集成验证见
|
||||
[系统架构](../../../../docs/architecture.md#31-插件扩展)。
|
||||
单元测试与文档构建不代替目标平台上的安装、配置及实际能力验证
|
||||
宿主集成见[系统架构](../../../../docs/architecture.md#31-插件扩展)。插件还须在目标平台验证安装、配置和实际功能
|
||||
|
||||
@@ -27,22 +27,15 @@ let plugin = PluginBuilder::from_json(include_bytes!("../plugin.json"))?
|
||||
session.run(plugin).await?;
|
||||
```
|
||||
|
||||
`PluginBuilder::from_json` 与 `cpr-plugin package` 使用同一个作者清单规范化入口。构建器负责:
|
||||
|
||||
- 自动响应 `plugin.register`,注册内容直接来自规范化后的清单
|
||||
- 按方法合同解码控制参数和二进制载荷,并在进入业务处理器前检查调用阶段
|
||||
- 保留 `TypedCall` 中的调用上下文、宿主客户端和取消信号
|
||||
- 按方法合同编码 `TypedReply`,流式结果继续复用有界 `ResponseStream`
|
||||
- 在 `build()` 时核对能力与必需处理器,避免清单与分派表漂移
|
||||
`PluginBuilder::from_json` 与打包 CLI 共用[作者清单入口](manifest.md),按清单响应 `plugin.register`,并在 `build()` 时核对必需处理器。
|
||||
构建器在分派前检查阶段、解码控制参数与载荷。`TypedCall` 携带上下文、宿主客户端及取消信号,结果编码为 `TypedReply`,流式结果使用有界 `ResponseStream`
|
||||
|
||||
`management`、`command_line` 和 `middleware` 是常用组合入口;其余能力使用
|
||||
`on(methods::..., handler)`。方法常量固定请求、响应、阶段与载荷位置,作者不手写 RPC 方法名。
|
||||
状态迁移不是 capability:清单任一 `state[]` 声明了 `migratesFrom` 时,注册
|
||||
`methods::STATE_MIGRATE`,构建器也会要求该处理器存在
|
||||
|
||||
类型化合同故意区分三种数据:普通控制元数据、可能敏感的 JSON 二进制载荷、原始字节。
|
||||
例如 CLI 参数、账号凭据和状态迁移批次使用二进制 JSON,管理 HTTP 正文保持原始字节。
|
||||
错误地把敏感载荷放进控制参数会在业务处理器运行前被拒绝
|
||||
控制参数只放普通元数据。CLI 参数、账号凭据和状态迁移批次使用二进制 JSON,管理 HTTP 正文使用原始字节。敏感载荷放进控制参数会在分派前被拒绝
|
||||
|
||||
## 请求上下文
|
||||
|
||||
@@ -252,9 +245,7 @@ SDK 不自动重试。超时或断连不能证明写入未提交;重试上限
|
||||
|
||||
### Key、模型与模型调用
|
||||
|
||||
模型调用方法:
|
||||
|
||||
- `host.keys.list`:只返回 `{id, name, enabled}`,不返回 Key 明文、前缀或隐藏 scope
|
||||
- `host.keys.list`:分页返回 `{id, name, enabled}`
|
||||
- `host.models.list`:以显式 `client_key_id` 查询该 Key 当前可见的模型目录
|
||||
- `host.model.execute[_stream]`:交给 Core 的路由、准入、租约、重试、账本和计费链路执行
|
||||
- `host.model.stream_read/close`:读取或关闭当前父调用创建的有界流
|
||||
@@ -266,9 +257,8 @@ SDK 不自动重试。超时或断连不能证明写入未提交;重试上限
|
||||
`invalid_input`,不启动模型执行。上游适配器的请求 `GPAQ` 也使用请求预算,响应事件仍受
|
||||
原有 8 MiB 编码上限、Runtime 缓冲预算及流控窗口限制
|
||||
|
||||
HTTP 和 request 中间件中的模型回调沿用有效请求设置;attempt、outbound、路由、调度、重试和上游适配器
|
||||
沿用该次模型请求冻结的正文预算。显式 Key 模型调用的预检与执行使用同一身份快照,
|
||||
同一父调用内复用 Key 时不受后续配置发布影响;父调用结束后重新解析身份才读取新配置,无需重新启用插件
|
||||
HTTP 和 request 中间件使用有效请求设置。attempt、outbound、路由、调度、重试及上游适配器沿用冻结的模型请求预算。
|
||||
显式 Key 的预检与执行共用父调用内的身份快照,后续发布的配置在新的父调用解析身份时生效
|
||||
|
||||
`ModelExecuteRequest.client_key_id` 可显式选择执行 Key,不与触发插件的父请求 Key 求交。省略时继承现有模型父请求身份;没有模型父请求的调用必须提供 Key。所选 Key 的启用状态、模型规则、账号组、并发和预算继续由 Core 执行
|
||||
嵌套调用与显式 Key 调用继承入口快照中的客户端 IP 和 User-Agent;没有 HTTP 入口的后台调用保持来源未知
|
||||
@@ -276,7 +266,7 @@ HTTP 和 request 中间件中的模型回调沿用有效请求设置;attempt
|
||||
模型事件使用 `call::model::ExecutionEvent` 的 `GPE2` 封套,将 canonical 事实、宿主事实和原始 wire 分段编码。`host` 包含费用及定价明细、完整上游观测、会话状态和改写来源;当前 wire 与原始 wire 都保留二进制字节;`WirePayload::WebSocket` 独立保留完整文本消息和可选 JSON 视图,不把未知文本改造成 SSE。读取或回传快照不触发第二次计费、续接提交或发送状态更新。
|
||||
非流式模型结果通过 `ModelEventBatch` 的 `HME1` 有界二进制批次返回;流式句柄只在创建它的父调用内有效。
|
||||
发起回调的插件实例在子调用中跳过,Core 在单次执行的子调用图内限制递归深度、总数和并发,避免插件调用自身形成环。
|
||||
显式 Key 的身份快照随父调用保留,每个模型执行独立计时并建立调用图;父调用结束会取消尚未完成的执行,连接空闲不消耗后续执行的期限
|
||||
每次模型执行独立计时并建立调用图。父调用结束会取消未完成的执行,连接空闲不消耗后续执行的期限
|
||||
|
||||
`host.affinity.lookup` 查询 Provider 已持久化的真实亲和键。命中只是账号偏好,
|
||||
后续执行仍重新检查当前 Key 规则、账号资格和租约
|
||||
@@ -288,16 +278,11 @@ HTTP 和 request 中间件中的模型回调沿用有效请求设置;attempt
|
||||
父调用取消或结束时宿主回收未关闭的流,SDK 不后台预读。取消一次 `read()` 等待后,再次读取会继续同一次操作,不丢弃已经返回的分块。
|
||||
账号上游使用同一正文对象,使用方式见[受管上游](upstream-adapters.md)
|
||||
|
||||
`HostClient::account_http(AccountHttpRequest { account_id, credential_revision, request }, body)` 使用指定账号的当前代理配置,
|
||||
经 `host.http.account` 返回同一 `HostHttpBody`。每次发送核对账号存在、启用和凭据版本,版本变化须由插件重新读取后决定下一步。
|
||||
请求 headers 与正文完全由插件提供;宿主不注入账号认证、不申请推理租约。无显式代理时使用部署默认出口,代理不可用时直接失败,不回退直连。
|
||||
这项能力与上游适配器的账号推理 HTTP 分开,适用于插件自行构造的账号网络请求
|
||||
`HostClient::account_http(AccountHttpRequest { account_id, credential_revision, request }, body)` 经 `host.http.account` 使用账号代理并返回 `HostHttpBody`。每次发送要求账号存在、已启用且凭据版本匹配。版本变化时须重新读取凭据。
|
||||
插件提供请求头与正文,宿主不注入账号认证或申请推理租约。无显式代理时使用部署默认出口,代理不可用时直接失败
|
||||
|
||||
`HostClient::proxy_http(ProxyHttpRequest { proxy_id, request }, body)` 经 `host.http.proxy` 使用指定代理的当前配置,
|
||||
返回同一响应头与 `HostHttpBody`,不要求账号存在或绑定代理,也不校验账号凭据版本。
|
||||
代理不存在、禁用或连接失败时返回错误,不回退直连;未测试或历史测试失败不阻止实际请求。
|
||||
每次发送重新读取代理,已发出的请求沿该次解析的出口完成,不锁定整个插件业务流程的代理配置。
|
||||
目标请求的 headers 与正文由插件提供,宿主不注入账号认证;代理连接所需认证由宿主处理
|
||||
`HostClient::proxy_http(ProxyHttpRequest { proxy_id, request }, body)` 经 `host.http.proxy` 使用指定代理,无需绑定账号,返回响应头与 `HostHttpBody`。
|
||||
宿主每次发送读取代理配置,已发出的请求沿该出口完成。代理不存在、禁用或连接失败时直接报错,历史测试结果不限制发送。插件提供目标请求头与正文,宿主仅处理代理认证
|
||||
|
||||
`HostClient::list_proxies(ProxyListRequest { page, page_size, search })` 经 `host.proxies.list` 查询代理目录。
|
||||
`page` 从 1 开始,`page_size` 为 1–200,`search` 可省略,默认空字符串,最多 256 字节且不能包含控制字符。
|
||||
@@ -387,7 +372,7 @@ let status = host.service::<SetResetCreditAutomation>((account_id, true)).await?
|
||||
|
||||
`HttpCall.request` 提供 method、URI(含 query)、HTTP version、完整多值 headers、`settings`、`timeout_ms` 和 `HttpBody`。
|
||||
调用发生在路由匹配之前,管理接口、模型接口和未知路径都可参与。`settings` 是同一请求快照中的宿主运行设置,
|
||||
插件改写后用于后续认证、版本检查、正文解压及执行;不新增设置业务的中间件入口。`timeout_ms` 使用宿主 HTTP 超时基线,
|
||||
插件改写后的设置用于认证、版本检查、正文解压及执行。`timeout_ms` 默认取宿主 HTTP 超时,
|
||||
插件可改写或用 `None` 清除;终端按有效值执行,不恢复宿主默认值。宿主快照不可用时 `settings` 为 `null`
|
||||
|
||||
`POST /v1/chat/completions` 在 HTTP 挂载中保留 Chat 请求与 Chat JSON/SSE 响应视图,
|
||||
@@ -756,7 +741,7 @@ keep、replace 或 delete;全部完成后宿主才原子提交新配置与状
|
||||
需要跳转到外部页面时,在插件页面的用户点击处理器中调用 `openExternal(url): Promise<void>`。
|
||||
地址必须是绝对 HTTPS URL,不能包含用户名或密码。宿主展示目标主机名和非默认端口,管理员可打开新标签页、复制链接或取消。
|
||||
Promise 成功只表示宿主已接受确认请求,不代表链接已打开;无用户操作、地址无效或已有链接待确认时,请求会被拒绝。
|
||||
切换页面会关闭确认框。兼容较早的 v2 宿主时,先检查 `typeof window.codexProxyPlugin.openExternal === 'function'`
|
||||
切换页面会关闭确认框。插件需要适配缺少此方法的宿主时,先检查 `typeof window.codexProxyPlugin.openExternal === 'function'`
|
||||
|
||||
普通模型请求使用标准 `Response` 接口:
|
||||
|
||||
|
||||
@@ -2,8 +2,7 @@
|
||||
|
||||
[返回 SDK](../README.md) · [能力与回调](capabilities.md)
|
||||
|
||||
`Manifest` 对应包内 `plugin.json`。作者源清单由 `Manifest::from_author_slice` 读取,CLI 打包也调用同一入口;
|
||||
因此本地构建器、生成的安装清单和运行注册共享一份规范化结果
|
||||
`Manifest` 对应包内的 `plugin.json`。本地构建器与打包 CLI 都通过 `Manifest::from_author_slice` 校验并规范化作者清单
|
||||
|
||||
| 字段 | 规则 |
|
||||
| --- | --- |
|
||||
@@ -14,11 +13,10 @@
|
||||
| `configurationSchema` / `secretFields` | 普通设置的 schema / 单独保存的敏感字段 |
|
||||
| `main` / `resources` | 包内可执行文件 / 资源路径与 MIME 类型 |
|
||||
| `state` | [私有状态](capabilities.md#状态日志与迁移)的命名空间、schema 与配额 |
|
||||
| `package` | CLI 生成的协议版本、单一目标平台与文件摘要,不需作者手写 |
|
||||
| `package` | 作者清单须省略。CLI 填入协议版本、目标平台与文件摘要 |
|
||||
|
||||
作者清单不能包含 `package`。使用 `Manifest::from_author_slice()` 校验并规范化;直接反序列化的 `Manifest`
|
||||
不会执行作者清单的 ID 与固定阶段推导,声明的可选字段仍使用其默认值。打包后,`main` 和所有资源都必须进入 `package.files`,
|
||||
宿主校验包结构、目标平台与文件完整性,宿主范围和能力版本另行进行兼容检查。运行模式为 `trustedProcess`,信任边界见[完整信任](#完整信任)
|
||||
直接反序列化 `Manifest` 只应用可选字段默认值。需要推导 ID 和固定阶段时使用作者清单入口。
|
||||
打包后,`package.files` 须包含 `main` 与所有资源
|
||||
|
||||
宿主实际开放的合同由 [plugin-host-compatibility.json](../../runtime/plugin-host-compatibility.json)
|
||||
声明,SDK 的 `Capability::contract_versions()` 只表示 SDK 能描述的行为版本,不能代替宿主支持检查
|
||||
@@ -32,13 +30,9 @@
|
||||
|
||||
`capabilities` 使用扩展能力标识;Provider、模型和账号 ID 不属于这个集合
|
||||
|
||||
清单不接受 `permissions` 字段;插件按[完整信任](#完整信任)运行
|
||||
CLI 按 SDK 合同校验声明。安装包清单拒绝未知字段,并校验必需字段、类型与版本。进程通信见 [RPC 合同](../README.md#通信边界),已安装元数据的读取见[制品与发布](../../../../../docs/architecture.md#制品配置与发布)
|
||||
|
||||
RPC v7 的帧布局、编码与会话生命周期见[通信边界](../README.md#通信边界)。插件使用 SDK 构建,并由 CLI 生成包含协议版本的安装包
|
||||
|
||||
安装包清单校验与已安装元数据读取是两个边界:清单拒绝未知字段,并检查必需字段、类型和版本;
|
||||
数据库元数据的读取规则见[制品与发布](../../../../../docs/architecture.md#制品配置与发布),不改变清单或 RPC 合同。
|
||||
`engines.codex-proxy-rs` 声明插件所需的宿主范围。范围或已声明能力版本不匹配时不自动启动,管理员确认风险后可尝试本次启动;确认不跨宿主重启保留。包结构、清单格式、平台与 RPC 封装校验失败阻止加载,不能通过风险确认绕过。CLI 严格校验作者声明是否符合 SDK 支持的合同
|
||||
宿主版本超出 `engines.codex-proxy-rs` 范围或能力版本不匹配时,管理员可确认风险并尝试启动,确认仅对本次启动有效。包结构、文件完整性、清单格式、平台或 RPC 校验失败时无法加载
|
||||
|
||||
## 接口弃用
|
||||
|
||||
@@ -98,15 +92,11 @@ capability 固定并由工具生成:
|
||||
|
||||
安装并启用插件意味着信任其全部代码和行为。插件与宿主使用相同的系统身份,可以访问数据、凭据和网络;安全由安装者承担,宿主不提供插件安全沙箱
|
||||
|
||||
清单只声明处理器、配置和资源。宿主回调不需要权限声明,也不按调用阶段授予访问域;类型校验、期限、取消、实例 revision、事务及流资源生命周期仍然生效
|
||||
运行模式为 `trustedProcess`。清单不接受 `permissions`,宿主回调无需声明权限。类型、期限、取消、实例 revision、事务与流资源约束均生效
|
||||
|
||||
## 插件图标
|
||||
|
||||
`icon` 指定管理端展示的插件图标。值可以是一个包内文件路径,也可以是包含 `light`、`dark` 两个路径的对象。
|
||||
使用单个路径时,浅色和深色主题共用同一张图;使用主题对象时,管理端按当前主题选择,两项都必须填写。
|
||||
不填写 `icon` 时显示通用图标。图标路径不是远程 URL,也不接受内置图标名称
|
||||
|
||||
在 `plugin.json` 中同时设置 `icon` 和对应的 `resources` 项。以下是单图标配置片段:
|
||||
`icon` 可填包内路径(两种主题共用),或同时含 `light`、`dark` 路径的对象。每个文件均须在 `resources` 登记。省略 `icon` 时显示通用图标
|
||||
|
||||
```json
|
||||
{
|
||||
@@ -151,6 +141,4 @@ capability 固定并由工具生成:
|
||||
- SVG 使用 UTF-8 编码,根元素为 SVG 命名空间中的 `<svg>`,XML 节点不超过 16384 个;不使用 DTD 实体或 XML 处理指令
|
||||
- SVG 保留矢量、渐变、内联样式和 data URL 内嵌图片;图标不能依赖脚本、外部图片、外部样式或外部字体
|
||||
|
||||
将图标文件与清单一同交给 [插件 CLI](../../../../apps/plugin-cli/README.md) 打包。工具收集 `resources` 声明的文件,
|
||||
生成 `package.files` 摘要;宿主在安装时验证图标内容。管理端通过 [图标读取接口](../../../../../docs/api.md#12-插件管理)
|
||||
以图片方式展示,不将 SVG 源码插入页面 HTML
|
||||
[插件 CLI](../../../../apps/plugin-cli/README.md) 打包图标,宿主在安装时校验内容。管理端通过[图标接口](../../../../../docs/api.md#图标读取)以图片展示 SVG
|
||||
|
||||
@@ -2,9 +2,8 @@
|
||||
|
||||
[返回 SDK](../README.md) · [清单声明](manifest.md#扩展项简写) · [能力与回调](capabilities.md)
|
||||
|
||||
`upstream_adapter` v5 是现有生成请求洋葱链的终端,只挂到内置 `openai` / `xai`,不替换独立图像或压缩端点。
|
||||
插件定义 Base URL、业务路径、请求编码和响应解析;宿主继续持有身份、ACL、选号、租约、凭据、代理、重试和账本。
|
||||
普通请求或响应加工使用 [middleware](capabilities.md#洋葱中间件)
|
||||
`upstream_adapter` v5 处理内置 `openai` / `xai` 的生成请求,独立图像和压缩端点使用原生实现。
|
||||
插件负责 Base URL、路径、请求编码和响应解析。宿主负责身份、ACL、选号、租约、凭据、代理、重试和账本。仅需加工请求或响应时使用[中间件](capabilities.md#洋葱中间件)
|
||||
|
||||
## 声明与绑定
|
||||
|
||||
@@ -26,18 +25,13 @@
|
||||
| `models` | 公开请求模型的精确匹配,空集合沿用绑定范围 |
|
||||
| `account_ids` | 上游账号 ID 范围,必填;空数组匹配所有账号 |
|
||||
|
||||
实例绑定沿用 Key、账号组、Provider、模型范围,只允许一次 `upstream` 绑定和 `reject` 故障策略。
|
||||
多个声明命中时按发布顺序选择首个适配器,插件负责声明的业务含义。适配器未命中时仍使用原生上游,
|
||||
已命中但不可用时拒绝请求。安装、配置、启停和升级使用已有插件管理
|
||||
实例只允许一个 `upstream` 绑定,故障策略为 `reject`。Key、账号组、Provider 和模型限定请求范围,插件注册的 `account_ids` 只能进一步收窄账号范围
|
||||
|
||||
账号范围只收窄绑定,不能扩大 Key、分组或模型权限。宿主先排除适配器不可用或认证类型不兼容的账号,
|
||||
再沿用原调度、亲和和租约;取得账号后从同一发布代次解析适配器。不同账号可以为同一公开模型选择不同适配器,
|
||||
未匹配账号保持原生执行,重叠声明仍按发布顺序取首个匹配。
|
||||
前置账号范围已匹配的可用适配器不受后置兜底声明故障影响。
|
||||
xAI 原生编码不支持的请求仍可选择匹配的适配器账号;原生账号会在取得租约前被排除
|
||||
同一模型可按账号使用不同适配器。每个账号按发布顺序取首个匹配声明,后续声明的故障不影响已匹配的适配器。未匹配时使用原生上游,命中但不可用时拒绝执行
|
||||
|
||||
账号范围由插件注册结果提供,不改变管理端 binding 中 `accountGroupIds` 的请求作用域语义。
|
||||
停用或卸载实例会移除其绑定;维护时须先停用依赖该适配器的账号并排空请求,账号范围不提供永久依赖约束。
|
||||
取得租约前,宿主排除适配器不可用或认证不兼容的账号。xAI 原生编码不支持请求时,仅排除原生账号,匹配的适配器账号仍可使用。宿主按亲和与调度策略取得租约后,从同一发布代次解析适配器
|
||||
|
||||
停用或卸载实例会移除绑定。维护前先停用依赖该适配器的账号并排空请求
|
||||
|
||||
能力、清单、进程 RPC 和宿主兼容声明分别校验各自版本,见[清单](manifest.md)。
|
||||
Provider、业务协议和传输名称不能写入宿主兼容清单的 capability / RPC 版本位置
|
||||
@@ -65,9 +59,8 @@ while let Some(bytes) = body.read().await? {
|
||||
}
|
||||
```
|
||||
|
||||
正文与普通 `HostClient::http` 共用 `read`、`collect(maximum_bytes)` 和 `close`;每次读取至多 64 KiB,
|
||||
不后台预读,不向作者暴露流 ID。提前关闭及收集超限会释放正文,父调用结束或取消时宿主兜底回收。
|
||||
JSON 可有界收集,SSE 应增量解析,不能把读取块当成完整事件。HTTP 版本、字节头及 trailers 的读取见[网络](capabilities.md#网络)
|
||||
正文每次 `read` 至多 64 KiB,SDK 按需读取并管理流 ID。JSON 可用 `collect(maximum_bytes)`,SSE 须跨读取块增量解析。
|
||||
显式 `close`、收集超限或父调用结束、取消时释放正文。HTTP 版本、字节头及 trailers 见[网络](capabilities.md#网络)
|
||||
|
||||
WebSocket 使用 `call.host.upstream_websocket(request).await?`,返回
|
||||
`UpstreamWebSocketUpgrade::Connected { http_version, headers, connection }` 或 `Rejected { status, http_version, headers, body, trailers }`。
|
||||
@@ -102,9 +95,7 @@ let (message, ()) = tokio::try_join!(
|
||||
观测事件和该次 HTTP 的读流、关流不单独阻断;HTTP200 流内报错、WebSocket 拒绝及其他状态码不适用。
|
||||
Core 仍复核续接归属、外部副作用、交付与重试预算;这不保证一定换号,也不证明完整信任插件绕过宿主执行的操作可重放
|
||||
|
||||
初始 RPC 回复受插件处理预算约束,默认上限为 120 秒;持续接收与解析应放在返回的流中。
|
||||
初始流式回复后,流的寿命遵循模型请求期限与取消,受管 HTTP 正文每次读取单独计时。
|
||||
持续有数据的流不会因初始 RPC 预算耗尽而结束,单次读取超时、客户端取消和流结束仍会回收资源
|
||||
初始 RPC 回复默认限时 120 秒。持续接收与解析应放在返回的流中,遵循模型请求期限。受管 HTTP 正文每次读取单独计时,读取超时、客户端取消或流结束时回收资源
|
||||
|
||||
用量提交标准 `Usage`,费用由内置 Provider 按已冻结的上游模型与价格计算,响应回显模型不切换计价。
|
||||
`observation.service_tier` 记录上游回显的最新档位,允许上游在完成时确定实际值;OpenAI 计价沿用请求策略,回显档位仅作观测。
|
||||
|
||||
@@ -15,7 +15,7 @@
|
||||
| `WriteAggregates` | `usage.aggregates.write` | 按聚合键批量覆盖或删除统计贡献 |
|
||||
| `EvaluatePricing` | `pricing.evaluate` | 根据当前价目或指定价格试算,逐项返回 `estimated` 或 `not_estimable` |
|
||||
|
||||
明细列表只列请求记录,聚合贡献参与统计但不生成请求明细。完整分组与全局总量使用下方统计读取,趋势使用既有统计查询
|
||||
请求列表只含明细。全局与分组统计包含聚合贡献,趋势由统计查询提供
|
||||
|
||||
## 完整扫描与分组统计
|
||||
|
||||
@@ -93,21 +93,21 @@ async fn read_statistics(
|
||||
|
||||
## 聚合维护
|
||||
|
||||
`UsageAggregateKey` 由 `bucket_start_ms`、`dimensions` 和调用方的 `key` 共同构成。相同完整键的 `put` 覆盖旧值,重复提交相同内容不会累计;改变时间、维度或 `key` 会形成另一个目标,需要移动时由调用方删除旧键
|
||||
`UsageAggregateKey` 由 `bucket_start_ms`、`dimensions` 和调用方的 `key` 组成。`put` 按完整键覆盖,重复提交不会累加。移动记录须写入新键并删除旧键
|
||||
|
||||
`dimensions` 支持 Provider、模型、账号、Key、操作和传输类型。`counts` 的键由 `UsageMetric` 定义,包括请求次数、各终态次数、已完成次数和各项 Token;`costs` 按币种保存十进制金额。计数与费用允许负值,供调用方表达统计修正
|
||||
|
||||
聚合按 `bucket_start_ms` 这个归属时间纳入 `[start_ms, end_ms)` 查询及趋势时间桶,宿主不自动摊分。导入日汇总时,调用方选择该日的归属时间;需要小时分布时,调用方自行提供小时数据
|
||||
贡献按 `bucket_start_ms` 计入查询区间与趋势时间桶。日汇总不会自动摊到各小时,需要小时分布时须写入小时数据
|
||||
|
||||
查询只按实际提供的维度匹配,缺少的维度不会自动补全。未提供某个维度的贡献参与总量,完整分组读取使用独立未归属分组表达,其他维度查询只计入实际提供该维度的贡献。请求 ID、响应 ID、状态码、请求结果及文字搜索等明细筛选不包含聚合贡献,聚合也不生成延迟样本、尝试次数或请求列表页数。原生统计的无符号计数与非负金额若因贡献合计超出表示范围,查询返回错误,由调用方修正输入
|
||||
贡献计入原生总量、趋势、维度统计和账号用量,维度匹配与越界处理见[分组与覆盖](#分组与覆盖)。按请求或响应 ID、状态码、请求结果或文字筛选时排除贡献。贡献不产生延迟样本、尝试次数或请求列表页数
|
||||
|
||||
聚合贡献参与原生总量、趋势、维度统计和账号用量,统计重建保留这些数据。贡献由调用方删除,不随请求历史保留任务清理;明细沿用请求历史保留策略
|
||||
统计重建保留贡献,须由写入方删除。请求历史保留策略只清理明细
|
||||
|
||||
## 费用试算与写回
|
||||
|
||||
`EvaluatePricing` 使用 Provider 的原生单请求 Token 计价公式,支持当前价目和调用方指定的价格覆盖。OpenAI 与 xAI 提供此能力;不支持的 Provider、缺少必要 Token、图像用量或无法确定的价目返回 `not_estimable`
|
||||
`EvaluatePricing` 按 OpenAI 或 xAI 的单请求公式,用当前价目或指定价格试算 Token 费用。须提供输入、输出、缓存读取、缓存写入和图像 Token,纯文本的图像 Token 填零。Provider 不支持、用量不全或价格未知时返回 `not_estimable`
|
||||
|
||||
试算输入需要明确输入、输出、缓存读取、缓存写入以及图像 Token;纯文本用量的图像 Token 填零。结果只包含 Token 费用,不自动处理图像、工具或其他附加费用,也不写入历史
|
||||
试算不含图像、工具等附加费用,也不写入请求记录
|
||||
|
||||
调用方可查询明细、选择目标、逐条试算,再通过 `WriteRecords::Update` 写回费用。补全缺失时只处理 `unavailable`;全部覆盖时自行选择整个范围。日汇总若缺少逐请求分布,长上下文档位和逐请求舍入可能无法复现,计算方法由调用方决定
|
||||
|
||||
@@ -121,4 +121,4 @@ async fn read_statistics(
|
||||
- 存储操作共享宿主观测连接与执行预算,超时、锁等待或取消会结束该次执行并释放资源
|
||||
- 错误类型包括 `invalid_input`、`not_found`、`conflict`、`capacity_exceeded`、`unavailable`,分批读取还区分 `cancelled` 与 `timeout`
|
||||
|
||||
响应丢失时,调用方按稳定 ID 或聚合键查询、重试覆盖。宿主不保存任务、来源登记、幂等回执、调整历史或撤销计划;调用方负责来源映射、业务去重、重试策略、并发写入协调和恢复。服务输入不能指定审计主体,宿主从当前调用身份生成普通变更审计
|
||||
响应丢失时,按稳定 ID 或聚合键查询后重试覆盖。调用方负责来源映射、去重、并发写入、进度、调整记录和恢复。宿主按当前调用身份记录变更审计,不提供幂等回执
|
||||
|
||||
@@ -3,6 +3,9 @@
|
||||
/// OpenAI 线协议载荷与事件的协议标识
|
||||
pub const OPENAI_PROTOCOL: &str = "openai";
|
||||
|
||||
/// 原生 Responses 客户端入口
|
||||
pub const RESPONSES_PATH: &str = "/v1/responses";
|
||||
|
||||
/// Codex Responses Lite 的 HTTP 请求头
|
||||
pub const X_OPENAI_INTERNAL_CODEX_RESPONSES_LITE_HEADER: &str =
|
||||
"x-openai-internal-codex-responses-lite";
|
||||
|
||||
@@ -454,7 +454,10 @@ impl AccountGroupStore for PgAccountGroupRepository {
|
||||
.await
|
||||
.map_err(|source| unavailable("check account group delete conflict", source))?;
|
||||
if exists {
|
||||
Err(conflict(command.id.as_str()))
|
||||
Err(conflict(
|
||||
command.id.as_str(),
|
||||
ConflictKind::InvalidTransition,
|
||||
))
|
||||
} else {
|
||||
Err(not_found_store(command.id.as_str()))
|
||||
}
|
||||
@@ -681,11 +684,15 @@ fn require_one(rows: u64, id: &str) -> StoreResult<()> {
|
||||
}
|
||||
|
||||
fn map_group_write_error(error: sqlx::Error, id: &str) -> StoreError {
|
||||
if error
|
||||
.as_database_error()
|
||||
.is_some_and(|database| database.is_unique_violation())
|
||||
if let Some(database) = error.as_database_error()
|
||||
&& database.is_unique_violation()
|
||||
{
|
||||
conflict(id)
|
||||
let kind = if database.constraint() == Some("account_groups_name_uq") {
|
||||
ConflictKind::DuplicateName
|
||||
} else {
|
||||
ConflictKind::InvalidTransition
|
||||
};
|
||||
conflict(id, kind)
|
||||
} else {
|
||||
unavailable("write account group", error)
|
||||
}
|
||||
@@ -703,12 +710,12 @@ fn not_found_store(id: &str) -> StoreError {
|
||||
}
|
||||
}
|
||||
|
||||
fn conflict(id: &str) -> StoreError {
|
||||
fn conflict(id: &str, kind: ConflictKind) -> StoreError {
|
||||
StoreError::Conflict {
|
||||
source: None,
|
||||
entity: ENTITY,
|
||||
id: id.to_owned(),
|
||||
kind: ConflictKind::InvalidTransition,
|
||||
kind,
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -130,18 +130,7 @@ pub(crate) fn push_usage_filter(
|
||||
pub(crate) const USAGE_LIST_RECORD_SELECT: &str =
|
||||
"select mr.id, mr.outcome, mr.provider_error_code as error_code, mr.error_message, mr.client_status_code, mr.client_api_key_name_snapshot as client_api_key_name, mr.endpoint, mr.client_transport, mr.requested_model_id,
|
||||
mr.error_kind, mr.upstream_status_code,
|
||||
exists (
|
||||
select 1 from (values
|
||||
(saved_error.body -> 'code'),
|
||||
(saved_error.body -> 'type'),
|
||||
(saved_error.body -> 'message')
|
||||
) as field(value)
|
||||
where jsonb_typeof(field.value) = 'string' and field.value <> '\"\"'::jsonb
|
||||
) as has_upstream_error,
|
||||
case when saved_upstream.body ->> 'type' = 'websocket.close'
|
||||
and jsonb_typeof(saved_upstream.body -> 'code') = 'number'
|
||||
then saved_upstream.body ->> 'code'
|
||||
end as websocket_close_code,
|
||||
facts.has_upstream_error, facts.websocket_close_code,
|
||||
mr.continuation_unavailable_reason, mr.upstream_connection_exit_reason,
|
||||
(mr.recovery_request_id is not null and mr.recovered_at is not null) as recovered,
|
||||
mr.provider_kind, mr.provider_account_ref,
|
||||
@@ -164,17 +153,36 @@ pub(crate) const USAGE_LIST_RECORD_SELECT: &str =
|
||||
mr.reasoning_effort, mr.reasoning_preset, mr.subagent_kind, mr.compact,
|
||||
mr.started_at
|
||||
from model_request_observations mr
|
||||
cross join lateral (
|
||||
cross join lateral ";
|
||||
|
||||
// 列表与筛选共用已保存上游事实的解码,兼容早期的空值和非 JSON 错误详情
|
||||
const SAVED_ERROR_FACTS: &str = "(select exists (
|
||||
select 1 from (values
|
||||
(saved_error.body -> 'code'),
|
||||
(saved_error.body -> 'type'),
|
||||
(saved_error.body -> 'message')
|
||||
) as field(value)
|
||||
where jsonb_typeof(field.value) = 'string' and field.value <> '\"\"'::jsonb
|
||||
) as has_upstream_error,
|
||||
case when saved_upstream.body ->> 'type' = 'websocket.close'
|
||||
and jsonb_typeof(saved_upstream.body -> 'code') = 'number'
|
||||
and (saved_upstream.body ->> 'code') ~ '^[0-9]{1,5}$'
|
||||
and (saved_upstream.body -> 'code') <= '65535'::jsonb
|
||||
then saved_upstream.body ->> 'code'
|
||||
end as websocket_close_code
|
||||
from lateral (
|
||||
select case when pg_input_is_valid(mr.error_details, 'jsonb') then
|
||||
case when jsonb_typeof(mr.error_details::jsonb -> 'upstream') = 'string'
|
||||
and pg_input_is_valid(mr.error_details::jsonb ->> 'upstream', 'jsonb')
|
||||
then (mr.error_details::jsonb ->> 'upstream')::jsonb
|
||||
end
|
||||
end as body
|
||||
-- 保留子查询边界,让错误字段和关闭码复用同一行已解码的上游正文
|
||||
offset 0
|
||||
) saved_upstream
|
||||
cross join lateral (
|
||||
select coalesce(saved_upstream.body -> 'error', saved_upstream.body #> '{response,error}') as body
|
||||
) saved_error";
|
||||
) saved_error) facts";
|
||||
|
||||
pub(crate) const USAGE_RECORD_DETAIL_SELECT: &str =
|
||||
"select mr.id, mr.client_api_key_ref, mr.config_revision,
|
||||
@@ -261,7 +269,7 @@ async fn projected_usage_counts(
|
||||
query: &UsageRecordQuery,
|
||||
) -> StoreResult<Option<BTreeMap<DateTime<Utc>, u64>>> {
|
||||
use admin_observability::UsageRecordStatus;
|
||||
if query.status == UsageRecordStatus::Error {
|
||||
if matches!(query.status, UsageRecordStatus::Error(_)) {
|
||||
return Ok(None);
|
||||
}
|
||||
let Some(mut counts) = snapshot
|
||||
@@ -351,7 +359,9 @@ async fn list_usage_record_items_at<'e, E: sqlx::Executor<'e, Database = Postgre
|
||||
statement.push(" offset ");
|
||||
statement.push_bind(offset);
|
||||
statement.push(") ");
|
||||
statement.push(USAGE_LIST_RECORD_SELECT);
|
||||
statement
|
||||
.push(USAGE_LIST_RECORD_SELECT)
|
||||
.push(SAVED_ERROR_FACTS);
|
||||
statement.push(
|
||||
" join candidate_page page on page.id = mr.id order by page.started_at desc, page.id desc",
|
||||
);
|
||||
@@ -504,7 +514,7 @@ fn usage_counts_query(
|
||||
},
|
||||
);
|
||||
}
|
||||
if branch > 0 || status == UsageRecordStatus::Error {
|
||||
if branch > 0 || matches!(status, UsageRecordStatus::Error(_)) {
|
||||
push_non_success_count_filter(&mut statement, filter);
|
||||
} else {
|
||||
push_usage_filter(&mut statement, filter, "mr");
|
||||
@@ -744,8 +754,11 @@ fn push_usage_record_status(
|
||||
use admin_observability::UsageRecordStatus;
|
||||
match status {
|
||||
UsageRecordStatus::Success => push_completed_usage_fact_filter(statement, "mr"),
|
||||
UsageRecordStatus::Error => {
|
||||
UsageRecordStatus::Error(origin) => {
|
||||
statement.push(" and mr.outcome in ('failed', 'incomplete')");
|
||||
if let Some(origin) = origin {
|
||||
push_usage_error_origin(statement, origin);
|
||||
}
|
||||
}
|
||||
UsageRecordStatus::All => {
|
||||
// 成功沿用用量边界,未成功记录保留真实生命周期,不把取消与执行中标为错误
|
||||
@@ -756,3 +769,52 @@ fn push_usage_record_status(
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn push_usage_error_origin(
|
||||
statement: &mut QueryBuilder<Postgres>,
|
||||
origin: admin_observability::UsageErrorOrigin,
|
||||
) {
|
||||
use admin_observability::{UsageErrorEvidence::*, UsageErrorOrigin};
|
||||
statement.push(" and case");
|
||||
for &(evidence, result) in UsageErrorOrigin::RULES {
|
||||
statement.push(" when ");
|
||||
match evidence {
|
||||
ProviderErrorCode => {
|
||||
statement.push("mr.provider_error_code <> ''");
|
||||
}
|
||||
UpstreamStatusAtLeast(min) => {
|
||||
statement
|
||||
.push("mr.upstream_status_code >= ")
|
||||
.push_bind(i32::from(min));
|
||||
}
|
||||
SavedUpstreamErrorOrClose => {
|
||||
statement.push("mr.error_details is not null and (select facts.has_upstream_error or facts.websocket_close_code is not null from lateral ")
|
||||
.push(SAVED_ERROR_FACTS).push(")");
|
||||
}
|
||||
ErrorKind(values) => {
|
||||
statement
|
||||
.push("mr.error_kind = any(")
|
||||
.push_bind(values)
|
||||
.push(")");
|
||||
}
|
||||
Continuation(values) => {
|
||||
statement
|
||||
.push("mr.continuation_unavailable_reason = any(")
|
||||
.push_bind(values)
|
||||
.push(")");
|
||||
}
|
||||
ConnectionExit(values) => {
|
||||
statement
|
||||
.push("mr.upstream_connection_exit_reason = any(")
|
||||
.push_bind(values)
|
||||
.push(")");
|
||||
}
|
||||
}
|
||||
statement.push(" then ").push_bind(result.as_str());
|
||||
}
|
||||
statement
|
||||
.push(" else ")
|
||||
.push_bind(UsageErrorOrigin::Unknown.as_str())
|
||||
.push(" end = ")
|
||||
.push_bind(origin.as_str());
|
||||
}
|
||||
|
||||
@@ -406,7 +406,7 @@ async fn health_counters_match_for_rollups_and_facts_without_counting_recovery_o
|
||||
sqlx::query("update model_requests set recovered_at=completed_at,recovery_request_id='health_success',recovery_attempt_count=1,request_observation_json=request_observation_json||jsonb_build_object('recovery',jsonb_build_object('retryDelayMs',0,'totalLatencyMs',1)) where id='health_recovered'")
|
||||
.execute(&database.pool).await.unwrap();
|
||||
drain_analytics(&database.pool).await;
|
||||
// 模拟旧桶曾把取消的 499 计入调用方错误,无需重建也应得到相同结果
|
||||
// 即使已存储的桶把 499 计入调用方错误,查询也应将其归为取消
|
||||
sqlx::raw_sql("update request_analytics_15m set counts=jsonb_set(counts,'{caller_error_count}','1') where outcome='cancelled'; update request_analytics_1h set counts=jsonb_set(counts,'{caller_error_count}','1') where outcome='cancelled'")
|
||||
.execute(&database.pool).await.unwrap();
|
||||
let repo = observability_repository(&database.pool);
|
||||
@@ -930,7 +930,7 @@ async fn interrupted_quarters_restart_changed_versions_and_publish_one_consisten
|
||||
.execute(&database.pool)
|
||||
.await
|
||||
.unwrap();
|
||||
// 独立重建请求改变版本,验证旧前缀废弃后仍可恢复,普通源变更不再重启整桶
|
||||
// 显式重建会更换版本,Worker 需要丢弃已处理的前缀并恢复构建
|
||||
sqlx::query("update request_analytics_pending_buckets set change_version=nextval('request_analytics_change_version')")
|
||||
.execute(&database.pool).await.unwrap();
|
||||
drop(worker);
|
||||
@@ -1034,7 +1034,7 @@ async fn backfill_coverage_uses_contiguous_cursor_instead_of_old_corrected_facts
|
||||
] {
|
||||
seed(&database.pool, id, now - TimeDelta::hours(age), &[]).await;
|
||||
}
|
||||
// 模拟迁移后历史队列为空,随后最旧请求发生单点修正
|
||||
// 清空待处理队列后只修正最早的请求,验证中间的时间段仍需回填
|
||||
sqlx::query("delete from request_analytics_pending_requests")
|
||||
.execute(&database.pool)
|
||||
.await
|
||||
|
||||
@@ -175,7 +175,7 @@ async fn usage_error_origins_agree_for_saved_errors_without_failure_status() {
|
||||
.list_usage_records(UsageRecordQuery {
|
||||
range,
|
||||
filter: UsageRecordFilter::default(),
|
||||
status: admin_observability::UsageRecordStatus::All,
|
||||
status: admin_observability::UsageRecordStatus::Error(Some(origin)),
|
||||
current_page: 1,
|
||||
page_size: ObservabilityPageSize::new(10).unwrap(),
|
||||
})
|
||||
@@ -282,7 +282,7 @@ async fn usage_error_origins_preserve_saved_failure_and_connection_boundaries()
|
||||
.list_usage_records(UsageRecordQuery {
|
||||
range,
|
||||
filter: UsageRecordFilter::default(),
|
||||
status: admin_observability::UsageRecordStatus::All,
|
||||
status: admin_observability::UsageRecordStatus::Error(Some(origin)),
|
||||
current_page: 1,
|
||||
page_size: ObservabilityPageSize::new(10).unwrap(),
|
||||
})
|
||||
@@ -993,10 +993,10 @@ async fn usage_account_filter_matches_only_historical_names_and_emails() {
|
||||
let repo = observability_repository(&database.pool);
|
||||
for (status, search, page, total, expected_id) in [
|
||||
(Success, r"_%\", 1, 1, Some("req_observe_success")),
|
||||
(Error, "team", 1, 1, Some("req_observe_failed")),
|
||||
(Error(None), "team", 1, 1, Some("req_observe_failed")),
|
||||
(All, "alice", 1, 2, Some("req_observe_failed")),
|
||||
(All, "alice", 2, 2, Some("req_observe_success")),
|
||||
(Error, "@example", 1, 0, None),
|
||||
(Error(None), "@example", 1, 0, None),
|
||||
(All, "ALICE", 1, 0, None),
|
||||
(All, "alice%ops", 1, 0, None),
|
||||
(All, "public-model", 1, 0, None),
|
||||
|
||||
@@ -460,7 +460,7 @@ async fn all_status_counts_keep_filters_delivery_rules_and_time_boundaries() {
|
||||
vec![],
|
||||
),
|
||||
] {
|
||||
for status in [UsageRecordStatus::All, UsageRecordStatus::Error] {
|
||||
for status in [UsageRecordStatus::All, UsageRecordStatus::Error(None)] {
|
||||
let expected = expected
|
||||
.iter()
|
||||
.copied()
|
||||
@@ -584,7 +584,7 @@ async fn request_status_pages_share_one_request_timeline() {
|
||||
.unwrap();
|
||||
for (status, expected) in [
|
||||
(UsageRecordStatus::Success, vec!["status_f", "status_a"]),
|
||||
(UsageRecordStatus::Error, vec!["status_c", "status_b"]),
|
||||
(UsageRecordStatus::Error(None), vec!["status_c", "status_b"]),
|
||||
(
|
||||
UsageRecordStatus::All,
|
||||
vec![
|
||||
@@ -619,7 +619,7 @@ async fn request_status_pages_share_one_request_timeline() {
|
||||
}
|
||||
let page = repo
|
||||
.list_usage_records(UsageRecordQuery {
|
||||
status: UsageRecordStatus::Error,
|
||||
status: UsageRecordStatus::Error(None),
|
||||
range,
|
||||
filter: UsageRecordFilter {
|
||||
search: Some("model_status_b".into()),
|
||||
@@ -647,3 +647,123 @@ async fn request_status_pages_share_one_request_timeline() {
|
||||
assert_eq!(errors.len(), 2);
|
||||
database.close().await;
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn error_origin_filters_matching_requests_before_counting_and_paging() {
|
||||
use gateway_admin::model::observability::{UsageErrorOrigin::*, UsageRecordStatus};
|
||||
|
||||
let Some(database) = TestDatabase::create("usage_error_origin_pages").await else {
|
||||
return;
|
||||
};
|
||||
let start = Utc::now();
|
||||
let repository = observability_repository(&database.pool);
|
||||
let range = ObservabilityRange::new(start, start + TimeDelta::hours(1)).unwrap();
|
||||
let saved =
|
||||
|body: serde_json::Value| serde_json::json!({"upstream": body.to_string()}).to_string();
|
||||
for (minute, (id, outcome, kind, status, details, model)) in [
|
||||
("edge_0", "failed", "internal_error", None, None, "main"),
|
||||
(
|
||||
"edge_1",
|
||||
"failed",
|
||||
"internal_error",
|
||||
Some(503_i32),
|
||||
None,
|
||||
"main",
|
||||
),
|
||||
("edge_2", "incomplete", "transport", Some(200), None, "main"),
|
||||
(
|
||||
"edge_3",
|
||||
"incomplete",
|
||||
"invalid_request",
|
||||
None,
|
||||
Some("old plain text".into()),
|
||||
"main",
|
||||
),
|
||||
(
|
||||
"edge_4",
|
||||
"failed",
|
||||
"internal_error",
|
||||
None,
|
||||
Some(saved(
|
||||
serde_json::json!({"response":{"error":{"message":"sample"}}}),
|
||||
)),
|
||||
"main",
|
||||
),
|
||||
(
|
||||
"edge_5",
|
||||
"failed",
|
||||
"internal_error",
|
||||
None,
|
||||
Some(saved(
|
||||
serde_json::json!({"type":"websocket.close","code":1012}),
|
||||
)),
|
||||
"other",
|
||||
),
|
||||
(
|
||||
"edge_6",
|
||||
"failed",
|
||||
"internal_error",
|
||||
None,
|
||||
Some(saved(
|
||||
serde_json::json!({"type":"websocket.close","code":65536}),
|
||||
)),
|
||||
"main",
|
||||
),
|
||||
("edge_7", "cancelled", "internal_error", None, None, "main"),
|
||||
("edge_8", "succeeded", "internal_error", None, None, "main"),
|
||||
]
|
||||
.into_iter()
|
||||
.enumerate()
|
||||
{
|
||||
seed(
|
||||
&database.pool,
|
||||
id,
|
||||
start + TimeDelta::minutes(minute as i64),
|
||||
&[],
|
||||
)
|
||||
.await;
|
||||
sqlx::query("update model_requests set outcome=$2, error_kind=$3, upstream_status_code=$4, error_details=$5, requested_model_id=$6 where id=$1")
|
||||
.bind(id).bind(outcome).bind(kind).bind(status).bind(details).bind(model)
|
||||
.execute(&database.pool).await.unwrap();
|
||||
}
|
||||
for (origin, model, ids) in [
|
||||
(Proxy, None, vec!["edge_6", "edge_0"]),
|
||||
(Upstream, None, vec!["edge_5", "edge_4", "edge_1"]),
|
||||
(Connection, None, vec!["edge_2"]),
|
||||
(Unknown, None, vec!["edge_3"]),
|
||||
(Upstream, Some("main"), vec!["edge_4", "edge_1"]),
|
||||
(Proxy, Some("other"), vec![]),
|
||||
] {
|
||||
for current_page in 1..=ids.len() + 1 {
|
||||
let page = repository
|
||||
.list_usage_records(UsageRecordQuery {
|
||||
range,
|
||||
status: UsageRecordStatus::Error(Some(origin)),
|
||||
filter: UsageRecordFilter {
|
||||
model_contains: model.map(str::to_owned),
|
||||
..Default::default()
|
||||
},
|
||||
current_page: current_page as u32,
|
||||
page_size: ObservabilityPageSize::new(1).unwrap(),
|
||||
})
|
||||
.await
|
||||
.unwrap();
|
||||
assert_eq!(page.total, ids.len() as u64, "{origin:?} / {model:?}");
|
||||
let items: Vec<_> = page
|
||||
.items
|
||||
.iter()
|
||||
.map(|item| (item.id.as_str(), item.error_origin()))
|
||||
.collect();
|
||||
let expected: Vec<_> = ids
|
||||
.get(current_page - 1)
|
||||
.map(|id| (*id, origin))
|
||||
.into_iter()
|
||||
.collect();
|
||||
assert_eq!(
|
||||
items, expected,
|
||||
"{origin:?} / {model:?} / page {current_page}"
|
||||
);
|
||||
}
|
||||
}
|
||||
database.close().await;
|
||||
}
|
||||
|
||||
@@ -59,10 +59,10 @@ tokio-rustls = { version = "=0.26.4", default-features = false }
|
||||
tokio-util = { version = "0.7.18", features = ["rt"] }
|
||||
tower-service = "0.3.3"
|
||||
tower-layer = "0.3.3"
|
||||
# 官方 Codex WebSocket 需要上游尚未发布的 proxy 与 permessage-deflate 实现,固定到已审计提交。
|
||||
tokio-tungstenite = { git = "https://github.com/openai-oss-forks/tokio-tungstenite", rev = "0e5b2d73aa18dd9f0a50ee9ff199d5aef7594186", features = ["proxy", "rustls-tls-native-roots"] }
|
||||
# 官方 fork 支持代理连接和分帧消息的 permessage-deflate,两个提交须配套
|
||||
tokio-tungstenite = { git = "https://github.com/openai-oss-forks/tokio-tungstenite", rev = "7447c427513cfe685f236e1ac0513c4ea3dd9c0b", features = ["proxy", "rustls-tls-native-roots"] }
|
||||
tracing = "0.1.44"
|
||||
tungstenite = { git = "https://github.com/openai-oss-forks/tungstenite-rs", rev = "4fffad30fe373adbdcffab9545e9e9bf4f2fc19f", features = ["deflate", "proxy"] }
|
||||
tungstenite = { git = "https://github.com/openai-oss-forks/tungstenite-rs", rev = "bc589d684755a8c02da0fc7e58d0861cbfc306f1", features = ["deflate", "proxy"] }
|
||||
url = "2.5.8"
|
||||
uuid = { version = "1.23.3", features = ["v4", "v7"] }
|
||||
# 静态链接 XZ 解码器,不要求部署环境安装 liblzma。
|
||||
@@ -73,8 +73,8 @@ zstd = "=0.14.3"
|
||||
zip = { version = "9.0.4", default-features = false, features = ["deflate-flate2"] }
|
||||
|
||||
[target.'cfg(target_os = "linux")'.dependencies]
|
||||
openssl = "=0.10.80"
|
||||
openssl-sys = { version = "=0.9.116", features = ["vendored"] }
|
||||
openssl = "=0.10.82"
|
||||
openssl-sys = { version = "=0.9.118", features = ["vendored"] }
|
||||
|
||||
[dev-dependencies]
|
||||
gateway-host = { path = "../../gateway-host" }
|
||||
|
||||
@@ -8,7 +8,9 @@ use url::Url;
|
||||
|
||||
use crate::credential::CodexQuotaRefreshPolicy;
|
||||
use crate::transport::session::{CodexSessionIdentity, CodexSessionIdentityError};
|
||||
use crate::transport::websocket::CodexWebSocketPoolConfig;
|
||||
use crate::transport::websocket::{
|
||||
CodexWebSocketPoolConfig, DEFAULT_FAST_PATH_BUDGET_MS, WEBSOCKET_CONNECT_TIMEOUT,
|
||||
};
|
||||
use crate::{
|
||||
OFFICIAL_CODEX_BASE_URL,
|
||||
credential::token_client::{
|
||||
@@ -165,26 +167,24 @@ impl CodexApiConfig {
|
||||
|
||||
/// Codex Responses WebSocket pool 的 Provider-owned 启动设置
|
||||
#[derive(Debug, Clone, Deserialize, PartialEq, Eq)]
|
||||
#[serde(default)]
|
||||
pub struct CodexWebSocketPoolSettings {
|
||||
pub enabled: bool,
|
||||
pub max_age_ms: u64,
|
||||
pub max_connecting: usize,
|
||||
#[serde(default = "default_websocket_pool_idle_timeout_ms")]
|
||||
pub fast_path_budget_ms: u64,
|
||||
pub idle_timeout_ms: u64,
|
||||
pub stream_idle_timeout_ms: u64,
|
||||
}
|
||||
|
||||
const fn default_websocket_pool_idle_timeout_ms() -> u64 {
|
||||
300_000
|
||||
}
|
||||
|
||||
impl Default for CodexWebSocketPoolSettings {
|
||||
fn default() -> Self {
|
||||
Self {
|
||||
enabled: true,
|
||||
max_age_ms: 55 * 60 * 1000,
|
||||
max_connecting: 8,
|
||||
idle_timeout_ms: default_websocket_pool_idle_timeout_ms(),
|
||||
fast_path_budget_ms: DEFAULT_FAST_PATH_BUDGET_MS,
|
||||
idle_timeout_ms: 300_000,
|
||||
stream_idle_timeout_ms: 300_000,
|
||||
}
|
||||
}
|
||||
@@ -192,6 +192,13 @@ impl Default for CodexWebSocketPoolSettings {
|
||||
|
||||
impl CodexWebSocketPoolSettings {
|
||||
fn validate(&self) -> Result<(), OpenAiConfigError> {
|
||||
if self.fast_path_budget_ms == 0
|
||||
|| Duration::from_millis(self.fast_path_budget_ms) > WEBSOCKET_CONNECT_TIMEOUT
|
||||
{
|
||||
return Err(OpenAiConfigError::InvalidField(
|
||||
"openai.ws_pool.fast_path_budget_ms",
|
||||
));
|
||||
}
|
||||
if self.max_age_ms == 0 || self.max_connecting == 0 || self.idle_timeout_ms == 0 {
|
||||
return Err(OpenAiConfigError::InvalidField("openai.ws_pool"));
|
||||
}
|
||||
@@ -203,6 +210,7 @@ impl CodexWebSocketPoolSettings {
|
||||
enabled: self.enabled,
|
||||
max_age: Duration::from_millis(self.max_age_ms),
|
||||
max_connecting: self.max_connecting,
|
||||
fast_path_budget: Duration::from_millis(self.fast_path_budget_ms),
|
||||
idle_timeout: Duration::from_millis(self.idle_timeout_ms),
|
||||
stream_idle_timeout: (self.stream_idle_timeout_ms != 0)
|
||||
.then(|| Duration::from_millis(self.stream_idle_timeout_ms)),
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
//! AttemptContext 驱动的 Codex 账号选择与 Redis lease port
|
||||
|
||||
use std::collections::HashMap;
|
||||
use std::collections::{BTreeSet, HashMap};
|
||||
use std::fmt;
|
||||
use std::sync::{Arc, Mutex};
|
||||
use std::time::{Duration, SystemTime};
|
||||
@@ -10,11 +10,11 @@ use gateway_core::account::CredentialRevision;
|
||||
use gateway_core::error::ErrorSource;
|
||||
|
||||
use gateway_core::account::{
|
||||
AccountAffinity, AccountCandidate, AccountCapacitySnapshot, AccountErrorReason,
|
||||
AccountFeedbackStats, AccountModelAccessMode, AccountQuotaSignals, AccountRuntimeSignals,
|
||||
AccountSchedulingBlocker, AccountSelectionContext, AccountSelectionPolicy, AccountSelector,
|
||||
AccountStatus, CredentialState, PreferredAccountSelection, ProviderAccount, ProviderAccountId,
|
||||
QuotaEvidence, RotationStrategy,
|
||||
AccountAffinity, AccountCandidate, AccountCapacitySnapshot, AccountCooldown,
|
||||
AccountCooldownKind, AccountErrorReason, AccountFeedbackStats, AccountModelAccessMode,
|
||||
AccountQuotaSignals, AccountRuntimeSignals, AccountSchedulingBlocker, AccountSelectionContext,
|
||||
AccountSelectionPolicy, AccountSelector, AccountStatus, CredentialState,
|
||||
PreferredAccountSelection, ProviderAccount, ProviderAccountId, QuotaEvidence, RotationStrategy,
|
||||
};
|
||||
use gateway_core::concurrency::{
|
||||
CapacityWait, ConcurrencyQueuePolicy, ConcurrencyWaitQueue, QueueRejection, WaitPriority,
|
||||
@@ -30,7 +30,7 @@ use gateway_core::provider_ports::{
|
||||
ProviderSessionAffinityPort, ProviderSessionBinding, ProviderSessionClaim,
|
||||
ProviderSessionExclusionPort, ProviderSessionExclusions, ProviderStoreError,
|
||||
};
|
||||
use gateway_core::routing::ProviderKind;
|
||||
use gateway_core::routing::{ProviderKind, UpstreamModelId};
|
||||
use secrecy::ExposeSecret;
|
||||
use thiserror::Error;
|
||||
use url::Url;
|
||||
@@ -185,48 +185,63 @@ impl AffinityEscapeReason {
|
||||
}
|
||||
|
||||
#[derive(Debug, Default)]
|
||||
struct AffinitySelection {
|
||||
bound_account: Option<ProviderAccountId>,
|
||||
preferred_account: Option<ProviderAccountId>,
|
||||
escape_reason: Option<AffinityEscapeReason>,
|
||||
enum AffinitySelection<'a> {
|
||||
#[default]
|
||||
Unbound,
|
||||
Preferred(&'a ProviderAccountId),
|
||||
Escaped(&'a ProviderAccountId, AffinityEscapeReason),
|
||||
}
|
||||
|
||||
impl AffinitySelection {
|
||||
fn preferred(account_id: ProviderAccountId) -> Self {
|
||||
Self {
|
||||
bound_account: Some(account_id.clone()),
|
||||
preferred_account: Some(account_id),
|
||||
escape_reason: None,
|
||||
impl<'a> AffinitySelection<'a> {
|
||||
fn for_binding(
|
||||
account: &'a ProviderAccountId,
|
||||
candidates: &[AccountCandidate],
|
||||
now: SystemTime,
|
||||
) -> Self {
|
||||
let status = candidates
|
||||
.iter()
|
||||
.find(|candidate| candidate.account.id() == account)
|
||||
.map(|candidate| {
|
||||
candidate
|
||||
.account
|
||||
.status_projection(now, candidate.signals.cooldown)
|
||||
.status
|
||||
});
|
||||
match status {
|
||||
Some(AccountStatus::Normal) => Self::Preferred(account),
|
||||
Some(AccountStatus::QuotaExhausted) => {
|
||||
Self::Escaped(account, AffinityEscapeReason::QuotaExhausted)
|
||||
}
|
||||
Some(AccountStatus::RateLimited | AccountStatus::QuotaPaused) => {
|
||||
Self::Escaped(account, AffinityEscapeReason::Cooldown)
|
||||
}
|
||||
Some(AccountStatus::Disabled | AccountStatus::Error) | None => {
|
||||
Self::Escaped(account, AffinityEscapeReason::HardUnavailable)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn escaped(account_id: ProviderAccountId, reason: AffinityEscapeReason) -> Self {
|
||||
Self {
|
||||
bound_account: Some(account_id),
|
||||
preferred_account: None,
|
||||
escape_reason: Some(reason),
|
||||
fn bound_account(&self) -> Option<&'a ProviderAccountId> {
|
||||
match self {
|
||||
Self::Preferred(account) | Self::Escaped(account, _) => Some(account),
|
||||
Self::Unbound => None,
|
||||
}
|
||||
}
|
||||
|
||||
fn bound_account(&self) -> Option<&ProviderAccountId> {
|
||||
self.bound_account.as_ref()
|
||||
}
|
||||
|
||||
fn preferred_account(&self) -> Option<&ProviderAccountId> {
|
||||
self.preferred_account.as_ref()
|
||||
fn preferred_account(&self) -> Option<&'a ProviderAccountId> {
|
||||
match self {
|
||||
Self::Preferred(account) => Some(account),
|
||||
_ => None,
|
||||
}
|
||||
}
|
||||
|
||||
fn escape(&mut self, reason: AffinityEscapeReason) {
|
||||
if self.bound_account.is_some() && self.escape_reason.is_none() {
|
||||
self.escape_reason = Some(reason);
|
||||
self.preferred_account = None;
|
||||
if let Self::Preferred(account) = self {
|
||||
*self = Self::Escaped(account, reason);
|
||||
}
|
||||
}
|
||||
|
||||
fn observe_preferred_selection(&mut self, selection: PreferredAccountSelection) {
|
||||
if self.bound_account.is_none() || self.escape_reason.is_some() {
|
||||
return;
|
||||
}
|
||||
match selection {
|
||||
PreferredAccountSelection::Hit => {}
|
||||
PreferredAccountSelection::OverriddenByPolicy => {
|
||||
@@ -253,7 +268,7 @@ impl AffinitySelection {
|
||||
}
|
||||
|
||||
fn observe_lease_busy(&mut self, account_id: &ProviderAccountId) {
|
||||
if self.bound_account.as_ref() == Some(account_id) {
|
||||
if self.preferred_account() == Some(account_id) {
|
||||
self.escape(AffinityEscapeReason::LeaseSaturated);
|
||||
}
|
||||
}
|
||||
@@ -264,14 +279,15 @@ impl AffinitySelection {
|
||||
cache_preference: bool,
|
||||
) -> AffinityTelemetry {
|
||||
AffinityTelemetry {
|
||||
affinity_hit: self.bound_account.as_ref() == Some(selected_account)
|
||||
&& self.escape_reason.is_none(),
|
||||
escape_reason: self.escape_reason,
|
||||
// 仅因缓存偏好而分流时,客户端的轮次状态仍没有已知归属。
|
||||
affinity_hit: self.preferred_account() == Some(selected_account),
|
||||
escape_reason: match self {
|
||||
Self::Escaped(_, reason) => Some(*reason),
|
||||
_ => None,
|
||||
},
|
||||
// 仅因缓存偏好而分流时,客户端的轮次状态仍没有已知归属
|
||||
account_switch: !cache_preference
|
||||
&& self
|
||||
.bound_account
|
||||
.as_ref()
|
||||
.bound_account()
|
||||
.is_some_and(|bound| bound != selected_account),
|
||||
}
|
||||
}
|
||||
@@ -556,6 +572,123 @@ impl CodexCredentialSelector {
|
||||
})
|
||||
}
|
||||
|
||||
async fn load_candidate_accounts(
|
||||
&self,
|
||||
attempt: &AttemptContext,
|
||||
model: CodexSelectionModel<'_>,
|
||||
adapter_model: Option<&UpstreamModelId>,
|
||||
only_account: Option<&ProviderAccountId>,
|
||||
) -> Result<Vec<ProviderAccount>, CredentialSelectionError> {
|
||||
let diagnostic = attempt.account_eligibility().bypasses_local_eligibility();
|
||||
// 固定归属或已有完整投影时只重查目标账号,诊断允许读取停用账号
|
||||
if let Some(id) = only_account {
|
||||
let account = self
|
||||
.repository
|
||||
.store()
|
||||
.get_account(id)
|
||||
.await
|
||||
.map_err(|source| CredentialSelectionError::Store(ErrorSource::new(source)))?;
|
||||
return Ok(account
|
||||
.filter(|account| diagnostic || account.enabled())
|
||||
.into_iter()
|
||||
.collect());
|
||||
}
|
||||
if diagnostic {
|
||||
return Ok(self.repository.list_for_provider().await?);
|
||||
}
|
||||
let account_ids: Vec<_> = attempt
|
||||
.account_scope()
|
||||
.into_iter()
|
||||
.flat_map(|scope| scope.allowed_account_ids().cloned())
|
||||
.collect();
|
||||
let omissions = match (model, attempt.account_scope()) {
|
||||
(CodexSelectionModel::Requested(model), Some(scope)) => {
|
||||
self.catalog.omissions(model, &account_ids, |id| {
|
||||
scope.directory().account(id).is_some_and(|account| {
|
||||
account.model_access().mode() == AccountModelAccessMode::Allowlist
|
||||
}) || adapter_model.is_some_and(|model| {
|
||||
!matches!(
|
||||
attempt.upstream_adapter_for_account(&self.provider_kind, model, id),
|
||||
Ok(None)
|
||||
)
|
||||
})
|
||||
})
|
||||
}
|
||||
_ => None,
|
||||
};
|
||||
let Some(filter) = omissions else {
|
||||
return Ok(self.repository.list_for_accounts(&account_ids).await?);
|
||||
};
|
||||
let candidates = self
|
||||
.repository
|
||||
.store()
|
||||
.list_catalog_candidates(&self.provider_kind, &account_ids, &filter)
|
||||
.await
|
||||
.map_err(CredentialRepositoryError::from)?;
|
||||
if attempt.trace().is_enabled() {
|
||||
attempt.trace().record(
|
||||
"account.catalog_candidates",
|
||||
serde_json::json!({
|
||||
"scopedCount": account_ids.len(),
|
||||
"candidateCount": candidates.len(),
|
||||
}),
|
||||
);
|
||||
}
|
||||
Ok(candidates)
|
||||
}
|
||||
|
||||
async fn load_candidate_cooldowns(
|
||||
&self,
|
||||
accounts: &[ProviderAccount],
|
||||
account_ids: &[ProviderAccountId],
|
||||
native_accounts: &BTreeSet<ProviderAccountId>,
|
||||
model: CodexSelectionModel<'_>,
|
||||
) -> HashMap<ProviderAccountId, AccountCooldown> {
|
||||
let native = accounts
|
||||
.iter()
|
||||
.filter(|account| native_accounts.contains(account.id()));
|
||||
let model_cooldowns = async {
|
||||
let CodexSelectionModel::Requested(model) = model else {
|
||||
return Vec::new();
|
||||
};
|
||||
let Ok(model) = UpstreamModelId::new(model) else {
|
||||
return Vec::new();
|
||||
};
|
||||
let ids: Vec<_> = native.clone().map(|account| account.id().clone()).collect();
|
||||
self.cooldowns
|
||||
.read_scoped_many(&ids, &ProviderCooldownScope::upstream_model(model))
|
||||
.await
|
||||
};
|
||||
let (account_cooldowns, model_cooldowns) =
|
||||
futures::join!(self.cooldowns.read_many(account_ids), model_cooldowns);
|
||||
let mut active: HashMap<_, _> = account_ids
|
||||
.iter()
|
||||
.zip(account_cooldowns)
|
||||
.filter_map(|(id, cooldown)| {
|
||||
let state = cooldown.ok().flatten()?.scheduling_state();
|
||||
state
|
||||
.is_active(SystemTime::now())
|
||||
.then(|| (id.clone(), state))
|
||||
})
|
||||
.collect();
|
||||
for (account, cooldown) in native.zip(model_cooldowns) {
|
||||
if let Some(cooldown) = cooldown.ok().flatten().filter(|cooldown| {
|
||||
cooldown.credential_revision() == account.revision()
|
||||
&& cooldown.until() > SystemTime::now()
|
||||
}) {
|
||||
// 两种冷却取较晚期限,保留账号级冷却的恢复探测语义
|
||||
active
|
||||
.entry(account.id().clone())
|
||||
.and_modify(|state| state.until = state.until.max(cooldown.until()))
|
||||
.or_insert(AccountCooldown {
|
||||
until: cooldown.until(),
|
||||
kind: AccountCooldownKind::RateLimit,
|
||||
});
|
||||
}
|
||||
}
|
||||
active
|
||||
}
|
||||
|
||||
async fn select_inner_loop(
|
||||
&self,
|
||||
request: &CredentialSelectionInput<'_>,
|
||||
@@ -567,7 +700,7 @@ impl CodexCredentialSelector {
|
||||
) -> Result<CodexCredentialLease, CredentialSelectionError> {
|
||||
let adapter_model = match model {
|
||||
CodexSelectionModel::Requested(model) if request.managed_upstream => Some(
|
||||
gateway_core::routing::UpstreamModelId::new(model)
|
||||
UpstreamModelId::new(model)
|
||||
.map_err(|_| CredentialSelectionError::NoEligibleCredential)?,
|
||||
),
|
||||
_ => None,
|
||||
@@ -730,64 +863,18 @@ impl CodexCredentialSelector {
|
||||
.as_ref()
|
||||
.and_then(|_| binding.as_ref().map(ProviderSessionBinding::account_id));
|
||||
let projection_started = std::time::Instant::now();
|
||||
// 固定归属或已有完整投影的会话只查询目标账号,随后实时复核其资格和租约
|
||||
// 常规调度排除停用账号,管理端诊断允许验证其真实上游状态
|
||||
let accounts = if let Some(pinned) = pinned_account
|
||||
let only_account = pinned_account
|
||||
.as_ref()
|
||||
.or(queued_account.as_ref())
|
||||
.or(projected_account)
|
||||
{
|
||||
self.repository
|
||||
.store()
|
||||
.get_account(pinned)
|
||||
.await
|
||||
.map_err(|source| CredentialSelectionError::Store(ErrorSource::new(source)))?
|
||||
.filter(|account| diagnostic || account.enabled())
|
||||
.into_iter()
|
||||
.collect()
|
||||
} else if diagnostic {
|
||||
self.repository.list_for_provider().await?
|
||||
} else {
|
||||
let account_ids = request
|
||||
.attempt
|
||||
.account_scope()
|
||||
.into_iter()
|
||||
.flat_map(|scope| scope.allowed_account_ids().cloned())
|
||||
.collect::<Vec<_>>();
|
||||
let omissions = match (model, request.attempt.account_scope()) {
|
||||
(CodexSelectionModel::Requested(model), Some(scope)) => {
|
||||
self.catalog.omissions(model, &account_ids, |id| {
|
||||
scope.directory().account(id).is_some_and(|a| {
|
||||
a.model_access().mode() == AccountModelAccessMode::Allowlist
|
||||
}) || adapter_model.as_ref().is_some_and(|m| {
|
||||
!matches!(
|
||||
request.attempt.upstream_adapter_for_account(
|
||||
&self.provider_kind,
|
||||
m,
|
||||
id
|
||||
),
|
||||
Ok(None)
|
||||
)
|
||||
})
|
||||
})
|
||||
}
|
||||
_ => None,
|
||||
};
|
||||
if let Some(filter) = omissions {
|
||||
let candidates = self
|
||||
.repository
|
||||
.store()
|
||||
.list_catalog_candidates(&self.provider_kind, &account_ids, &filter)
|
||||
.await
|
||||
.map_err(CredentialRepositoryError::from)?;
|
||||
if request.attempt.trace().is_enabled() {
|
||||
request.attempt.trace().record("account.catalog_candidates",serde_json::json!({"scopedCount":account_ids.len(),"candidateCount":candidates.len()}));
|
||||
}
|
||||
candidates
|
||||
} else {
|
||||
self.repository.list_for_accounts(&account_ids).await?
|
||||
}
|
||||
};
|
||||
.or(projected_account);
|
||||
let accounts = self
|
||||
.load_candidate_accounts(
|
||||
request.attempt,
|
||||
model,
|
||||
adapter_model.as_ref(),
|
||||
only_account,
|
||||
)
|
||||
.await?;
|
||||
let mut model_access_rejected = 0_usize;
|
||||
let accounts = accounts
|
||||
.into_iter()
|
||||
@@ -822,7 +909,7 @@ impl CodexCredentialSelector {
|
||||
_ => None,
|
||||
};
|
||||
let mut catalog_rejected = 0_usize;
|
||||
let mut native_accounts = std::collections::BTreeSet::new();
|
||||
let mut native_accounts = BTreeSet::new();
|
||||
for account in accounts {
|
||||
let adapter = if let Some(model) = adapter_model.as_ref() {
|
||||
match request.attempt.upstream_adapter_for_account(
|
||||
@@ -943,65 +1030,12 @@ impl CodexCredentialSelector {
|
||||
.iter()
|
||||
.map(|account| account.id().clone())
|
||||
.collect::<Vec<_>>();
|
||||
let mut rate_limits = HashMap::with_capacity(accounts.len());
|
||||
let model_scope = match model {
|
||||
CodexSelectionModel::Requested(model) => {
|
||||
gateway_core::routing::UpstreamModelId::new(model)
|
||||
.ok()
|
||||
.map(ProviderCooldownScope::upstream_model)
|
||||
}
|
||||
_ => None,
|
||||
let rate_limits = if diagnostic {
|
||||
HashMap::new()
|
||||
} else {
|
||||
self.load_candidate_cooldowns(&accounts, &account_ids, &native_accounts, model)
|
||||
.await
|
||||
};
|
||||
if !diagnostic {
|
||||
let model_account_ids = account_ids
|
||||
.iter()
|
||||
.filter(|id| native_accounts.contains(*id))
|
||||
.cloned()
|
||||
.collect::<Vec<_>>();
|
||||
let model_cooldowns = async {
|
||||
match model_scope.as_ref() {
|
||||
Some(scope) => {
|
||||
self.cooldowns
|
||||
.read_scoped_many(&model_account_ids, scope)
|
||||
.await
|
||||
}
|
||||
None => Vec::new(),
|
||||
}
|
||||
};
|
||||
let (account_cooldowns, model_cooldowns) =
|
||||
futures::join!(self.cooldowns.read_many(&account_ids), model_cooldowns,);
|
||||
// 存储端有界批量读取,单项失败沿用未知冷却;待探测冻结由端口事实判断
|
||||
for (id, cooldown) in account_ids.iter().zip(account_cooldowns) {
|
||||
let state = cooldown
|
||||
.ok()
|
||||
.flatten()
|
||||
.map(|value| value.scheduling_state());
|
||||
rate_limits.insert(
|
||||
id.clone(),
|
||||
state.filter(|state| state.is_active(SystemTime::now())),
|
||||
);
|
||||
}
|
||||
for (account, cooldown) in accounts
|
||||
.iter()
|
||||
.filter(|account| native_accounts.contains(account.id()))
|
||||
.zip(model_cooldowns)
|
||||
{
|
||||
if let Some(cooldown) = cooldown.ok().flatten().filter(|cooldown| {
|
||||
cooldown.credential_revision() == account.revision()
|
||||
&& cooldown.until() > SystemTime::now()
|
||||
}) {
|
||||
// 两种冷却取较晚期限,账号保护保留其恢复探测语义
|
||||
let until = rate_limits
|
||||
.entry(account.id().clone())
|
||||
.or_default()
|
||||
.get_or_insert(gateway_core::account::AccountCooldown {
|
||||
until: cooldown.until(),
|
||||
kind: gateway_core::account::AccountCooldownKind::RateLimit,
|
||||
});
|
||||
until.until = until.until.max(cooldown.until());
|
||||
}
|
||||
}
|
||||
}
|
||||
let policy = request.attempt.account_selection_policy();
|
||||
let client_key = request.attempt.client_api_key_ref();
|
||||
let use_assignment_cursor = policy.strategy() == RotationStrategy::RoundRobin
|
||||
@@ -1068,7 +1102,7 @@ impl CodexCredentialSelector {
|
||||
first_output_latency_ms: None,
|
||||
})
|
||||
.with_provider_quota(quota)
|
||||
.with_rate_limit(rate_limits.get(account.id()).copied().flatten())
|
||||
.with_rate_limit(rate_limits.get(account.id()).copied())
|
||||
.with_runtime_health(health.0, health.1);
|
||||
AccountCandidate {
|
||||
account,
|
||||
@@ -1107,8 +1141,8 @@ impl CodexCredentialSelector {
|
||||
.as_ref()
|
||||
.filter(|_| affinity_mode != AccountAffinity::Relaxed)
|
||||
.map_or_else(AffinitySelection::default, |binding| {
|
||||
affinity_selection_for_bound_account(
|
||||
binding.account_id().clone(),
|
||||
AffinitySelection::for_binding(
|
||||
binding.account_id(),
|
||||
&candidates,
|
||||
SystemTime::now(),
|
||||
)
|
||||
@@ -1410,17 +1444,13 @@ impl CodexCredentialSelector {
|
||||
};
|
||||
affinity.observe_preferred_selection(selection.preferred());
|
||||
let selected = selection.candidate();
|
||||
let account = candidates
|
||||
.iter()
|
||||
.find(|candidate| candidate.account.id() == selected.account.id())
|
||||
.map(|candidate| candidate.account.clone())
|
||||
.ok_or(CredentialSelectionError::InvalidCredential(None))?;
|
||||
let account = &selected.account;
|
||||
// 凭据、状态或额度结论的并发更新会使账号快照失效,必须重新选号并校验资格;
|
||||
// 仅额度观测时刻前进时沿用最新快照
|
||||
// 在占用租约前完成校验,避免重读被自己的异步释放挡住
|
||||
let (account, runtime) = match self
|
||||
.repository
|
||||
.reload_selected_credential(&account)
|
||||
.reload_selected_credential(account)
|
||||
.await
|
||||
{
|
||||
Ok(reloaded) => reloaded,
|
||||
@@ -1429,7 +1459,7 @@ impl CodexCredentialSelector {
|
||||
self.scheduling_projection.invalidate(key);
|
||||
}
|
||||
refresh_candidates = true;
|
||||
retry_account_snapshot(request.attempt, &account, &mut snapshot_retries)?;
|
||||
retry_account_snapshot(request.attempt, account, &mut snapshot_retries)?;
|
||||
continue 'capacity;
|
||||
}
|
||||
Err(error) => return Err(error.into()),
|
||||
@@ -1445,7 +1475,7 @@ impl CodexCredentialSelector {
|
||||
}
|
||||
let allows_account_state_mutation =
|
||||
eligibility.allows_account_state_mutation(account.enabled());
|
||||
match self
|
||||
let guard = match self
|
||||
.leases
|
||||
.try_acquire(ProviderLeaseRequest::Scheduling(
|
||||
ProviderSchedulingLeaseRequest::new(
|
||||
@@ -1474,167 +1504,117 @@ impl CodexCredentialSelector {
|
||||
}
|
||||
shortest_retry = minimum_duration(shortest_retry, retry_after);
|
||||
busy_accounts.insert(account.id().clone());
|
||||
continue;
|
||||
}
|
||||
ProviderLeaseAcquisition::Acquired(guard) => {
|
||||
let mut binding_account = account.id();
|
||||
if affinity_mode == AccountAffinity::Preferred
|
||||
&& let Some(primary) = binding.as_ref()
|
||||
&& (primary.account_id() == account.id()
|
||||
|| pinned_account.is_some()
|
||||
|| !self
|
||||
.preferred_primary_needs_migration(
|
||||
primary,
|
||||
queue_policy.timeout,
|
||||
)
|
||||
.await?)
|
||||
{
|
||||
binding_account = primary.account_id();
|
||||
}
|
||||
let claim = binding_key.map(|key| ProviderSessionClaim {
|
||||
key,
|
||||
expected: binding.as_ref(),
|
||||
account: binding_account,
|
||||
ttl: policy.openai_session_affinity_ttl(),
|
||||
});
|
||||
// 插件委托与普通内置选号共享轮询,显式选择、亲和命中及等待不消耗位置
|
||||
let admission = match assignment_cursor {
|
||||
Some(cursor)
|
||||
if !selection.is_policy_choice()
|
||||
&& selection.preferred() != PreferredAccountSelection::Hit =>
|
||||
{
|
||||
Some(ProviderAccountAdmission::RoundRobin {
|
||||
client_key,
|
||||
cursor,
|
||||
session: claim,
|
||||
})
|
||||
}
|
||||
_ => claim.map(ProviderAccountAdmission::Session),
|
||||
};
|
||||
if let Some(admission) = admission {
|
||||
let admitted = match self.admit_account(admission).await {
|
||||
Ok(false) => false,
|
||||
Err(error)
|
||||
if cache_preference
|
||||
&& affinity_mode == AccountAffinity::Preferred
|
||||
&& admission.session().is_some() =>
|
||||
{
|
||||
tracing::warn!(%error, "OpenAI cache preference update unavailable");
|
||||
// 缓存偏好允许丢失,实际的轮询分配仍须占用该位置
|
||||
match admission {
|
||||
ProviderAccountAdmission::RoundRobin {
|
||||
client_key,
|
||||
cursor,
|
||||
..
|
||||
} => {
|
||||
self.admit_account(
|
||||
ProviderAccountAdmission::RoundRobin {
|
||||
client_key,
|
||||
cursor,
|
||||
session: None,
|
||||
},
|
||||
)
|
||||
.await?
|
||||
}
|
||||
ProviderAccountAdmission::Session(_) => true,
|
||||
}
|
||||
}
|
||||
Err(error) => return Err(error),
|
||||
Ok(true) => {
|
||||
if let Some(reason) = queue_rejection
|
||||
&& let Some(previous) = binding.as_ref().filter(|binding| {
|
||||
binding.account_id() != binding_account
|
||||
})
|
||||
{
|
||||
tracing::info!(
|
||||
request_id = %request.attempt.request_id(),
|
||||
attempt_index = request.attempt.attempt_index().get(),
|
||||
reason = %reason,
|
||||
from_account_id = %previous.account_id(),
|
||||
to_account_id = %binding_account,
|
||||
"OpenAI 账号排队失败后已迁移绑定"
|
||||
);
|
||||
request.attempt.trace().record_evidence(
|
||||
"account.binding.migrated",
|
||||
serde_json::json!({
|
||||
"reason": reason.to_string(),
|
||||
"fromAccountId": previous.account_id().as_str(),
|
||||
"toAccountId": binding_account.as_str(),
|
||||
}),
|
||||
);
|
||||
}
|
||||
true
|
||||
}
|
||||
};
|
||||
if !admitted {
|
||||
guard.release().await?;
|
||||
if request.attempt.deadline().is_elapsed() {
|
||||
return Err(CredentialSelectionError::AccountSnapshotChanged);
|
||||
}
|
||||
continue 'capacity;
|
||||
}
|
||||
}
|
||||
let affinity_telemetry = affinity.telemetry(account.id(), cache_preference);
|
||||
let affinity_observation = request.session_affinity_observation;
|
||||
tracing::info!(
|
||||
request_id = %request.attempt.request_id(),
|
||||
attempt_index = request.attempt.attempt_index().get(),
|
||||
rotation_strategy = policy.strategy().as_str(),
|
||||
account_id = %account.id(),
|
||||
affinity_hit = affinity_telemetry.affinity_hit,
|
||||
escape_reason = affinity_telemetry
|
||||
.escape_reason
|
||||
.map_or("", AffinityEscapeReason::as_str),
|
||||
account_switch = affinity_telemetry.account_switch,
|
||||
affinity_key_hash = affinity_observation
|
||||
.map_or("", CodexSessionAffinity::key_hash),
|
||||
affinity_anchor_source = affinity_observation
|
||||
.map_or("", CodexSessionAffinity::anchor_source),
|
||||
affinity_anchor = affinity_observation
|
||||
.map_or("", CodexSessionAffinity::anchor),
|
||||
session_id = affinity_observation
|
||||
.and_then(CodexSessionAffinity::session_id)
|
||||
.unwrap_or(""),
|
||||
session_id_present = affinity_observation
|
||||
.is_some_and(CodexSessionAffinity::session_id_present),
|
||||
"OpenAI account selected"
|
||||
);
|
||||
let cookies = runtime
|
||||
.cookies
|
||||
.into_iter()
|
||||
.filter(|cookie| {
|
||||
cookie
|
||||
.expires_at
|
||||
.is_none_or(|expires| expires > chrono::Utc::now())
|
||||
&& self.cookie_policy.may_replay(
|
||||
request.request_url,
|
||||
&cookie.domain,
|
||||
&cookie.path,
|
||||
cookie.host_only,
|
||||
cookie.secure,
|
||||
)
|
||||
})
|
||||
.collect();
|
||||
if !waiting.elapsed().is_zero() {
|
||||
request.attempt.trace().record(
|
||||
"account.queue.acquired",
|
||||
serde_json::json!({"waitMs": waiting.elapsed().as_millis() as u64}),
|
||||
);
|
||||
}
|
||||
return Ok(CodexCredentialLease {
|
||||
installation_id: runtime.installation_id,
|
||||
transport: runtime.transport,
|
||||
account,
|
||||
authentication: runtime.authentication,
|
||||
cookies,
|
||||
cyber_policy_scope,
|
||||
allows_account_state_mutation,
|
||||
affinity_telemetry,
|
||||
admitted_session: binding_key.filter(|_| !cache_preference).cloned(),
|
||||
capacity: capacity.map(AccountCapacitySnapshot::with_acquired_request),
|
||||
_guard: guard,
|
||||
});
|
||||
}
|
||||
ProviderLeaseAcquisition::Acquired(guard) => guard,
|
||||
};
|
||||
let mut binding_account = account.id();
|
||||
if affinity_mode == AccountAffinity::Preferred
|
||||
&& let Some(primary) = binding.as_ref()
|
||||
&& (primary.account_id() == account.id()
|
||||
|| pinned_account.is_some()
|
||||
|| !self
|
||||
.preferred_primary_needs_migration(primary, queue_policy.timeout)
|
||||
.await?)
|
||||
{
|
||||
binding_account = primary.account_id();
|
||||
}
|
||||
let claim = binding_key.map(|key| ProviderSessionClaim {
|
||||
key,
|
||||
expected: binding.as_ref(),
|
||||
account: binding_account,
|
||||
ttl: policy.openai_session_affinity_ttl(),
|
||||
});
|
||||
// 插件委托与普通内置选号共享轮询,显式选择、亲和命中及等待不消耗位置
|
||||
let admission = match assignment_cursor {
|
||||
Some(cursor)
|
||||
if !selection.is_policy_choice()
|
||||
&& selection.preferred() != PreferredAccountSelection::Hit =>
|
||||
{
|
||||
Some(ProviderAccountAdmission::RoundRobin {
|
||||
client_key,
|
||||
cursor,
|
||||
session: claim,
|
||||
})
|
||||
}
|
||||
_ => claim.map(ProviderAccountAdmission::Session),
|
||||
};
|
||||
if let Some(admission) = admission
|
||||
&& !self
|
||||
.admit_selected_account(
|
||||
admission,
|
||||
cache_preference && affinity_mode == AccountAffinity::Preferred,
|
||||
request.attempt,
|
||||
queue_rejection,
|
||||
)
|
||||
.await?
|
||||
{
|
||||
guard.release().await?;
|
||||
if request.attempt.deadline().is_elapsed() {
|
||||
return Err(CredentialSelectionError::AccountSnapshotChanged);
|
||||
}
|
||||
continue 'capacity;
|
||||
}
|
||||
let affinity_telemetry = affinity.telemetry(account.id(), cache_preference);
|
||||
let affinity_observation = request.session_affinity_observation;
|
||||
tracing::info!(
|
||||
request_id = %request.attempt.request_id(),
|
||||
attempt_index = request.attempt.attempt_index().get(),
|
||||
rotation_strategy = policy.strategy().as_str(),
|
||||
account_id = %account.id(),
|
||||
affinity_hit = affinity_telemetry.affinity_hit,
|
||||
escape_reason = affinity_telemetry
|
||||
.escape_reason
|
||||
.map_or("", AffinityEscapeReason::as_str),
|
||||
account_switch = affinity_telemetry.account_switch,
|
||||
affinity_key_hash = affinity_observation
|
||||
.map_or("", CodexSessionAffinity::key_hash),
|
||||
affinity_anchor_source = affinity_observation
|
||||
.map_or("", CodexSessionAffinity::anchor_source),
|
||||
affinity_anchor = affinity_observation
|
||||
.map_or("", CodexSessionAffinity::anchor),
|
||||
session_id = affinity_observation
|
||||
.and_then(CodexSessionAffinity::session_id)
|
||||
.unwrap_or(""),
|
||||
session_id_present = affinity_observation
|
||||
.is_some_and(CodexSessionAffinity::session_id_present),
|
||||
"OpenAI account selected"
|
||||
);
|
||||
let cookies = runtime
|
||||
.cookies
|
||||
.into_iter()
|
||||
.filter(|cookie| {
|
||||
cookie
|
||||
.expires_at
|
||||
.is_none_or(|expires| expires > chrono::Utc::now())
|
||||
&& self.cookie_policy.may_replay(
|
||||
request.request_url,
|
||||
&cookie.domain,
|
||||
&cookie.path,
|
||||
cookie.host_only,
|
||||
cookie.secure,
|
||||
)
|
||||
})
|
||||
.collect();
|
||||
if !waiting.elapsed().is_zero() {
|
||||
request.attempt.trace().record(
|
||||
"account.queue.acquired",
|
||||
serde_json::json!({"waitMs": waiting.elapsed().as_millis() as u64}),
|
||||
);
|
||||
}
|
||||
return Ok(CodexCredentialLease {
|
||||
installation_id: runtime.installation_id,
|
||||
transport: runtime.transport,
|
||||
account,
|
||||
authentication: runtime.authentication,
|
||||
cookies,
|
||||
cyber_policy_scope,
|
||||
allows_account_state_mutation,
|
||||
affinity_telemetry,
|
||||
admitted_session: binding_key.filter(|_| !cache_preference).cloned(),
|
||||
capacity: capacity.map(AccountCapacitySnapshot::with_acquired_request),
|
||||
_guard: guard,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1717,6 +1697,60 @@ impl CodexCredentialSelector {
|
||||
.map_err(binding_store_error)
|
||||
}
|
||||
|
||||
async fn admit_selected_account(
|
||||
&self,
|
||||
admission: ProviderAccountAdmission<'_>,
|
||||
optional_cache_binding: bool,
|
||||
attempt: &AttemptContext,
|
||||
queue_rejection: Option<QueueRejection>,
|
||||
) -> Result<bool, CredentialSelectionError> {
|
||||
let claim = admission.session();
|
||||
match self.admit_account(admission).await {
|
||||
Ok(false) => return Ok(false),
|
||||
Err(error) if optional_cache_binding && claim.is_some() => {
|
||||
tracing::warn!(%error, "OpenAI cache preference update unavailable");
|
||||
// 缓存偏好允许丢失,实际的轮询分配仍须占用该位置
|
||||
return match admission {
|
||||
ProviderAccountAdmission::RoundRobin {
|
||||
client_key, cursor, ..
|
||||
} => {
|
||||
self.admit_account(ProviderAccountAdmission::RoundRobin {
|
||||
client_key,
|
||||
cursor,
|
||||
session: None,
|
||||
})
|
||||
.await
|
||||
}
|
||||
ProviderAccountAdmission::Session(_) => Ok(true),
|
||||
};
|
||||
}
|
||||
Err(error) => return Err(error),
|
||||
Ok(true) => {}
|
||||
}
|
||||
if let (Some(reason), Some(claim)) = (queue_rejection, claim)
|
||||
&& let Some(previous) = claim.expected
|
||||
&& previous.account_id() != claim.account
|
||||
{
|
||||
tracing::info!(
|
||||
request_id = %attempt.request_id(),
|
||||
attempt_index = attempt.attempt_index().get(),
|
||||
reason = %reason,
|
||||
from_account_id = %previous.account_id(),
|
||||
to_account_id = %claim.account,
|
||||
"OpenAI 账号排队失败后已迁移绑定"
|
||||
);
|
||||
attempt.trace().record_evidence(
|
||||
"account.binding.migrated",
|
||||
serde_json::json!({
|
||||
"reason": reason.to_string(),
|
||||
"fromAccountId": previous.account_id().as_str(),
|
||||
"toAccountId": claim.account.as_str(),
|
||||
}),
|
||||
);
|
||||
}
|
||||
Ok(true)
|
||||
}
|
||||
|
||||
async fn admit_account(
|
||||
&self,
|
||||
admission: ProviderAccountAdmission<'_>,
|
||||
@@ -2194,49 +2228,6 @@ fn binding_store_error(
|
||||
)))
|
||||
}
|
||||
|
||||
fn affinity_selection_for_bound_account(
|
||||
account_id: ProviderAccountId,
|
||||
candidates: &[AccountCandidate],
|
||||
now: SystemTime,
|
||||
) -> AffinitySelection {
|
||||
let Some(candidate) = candidates
|
||||
.iter()
|
||||
.find(|candidate| candidate.account.id() == &account_id)
|
||||
else {
|
||||
return AffinitySelection::escaped(account_id, AffinityEscapeReason::HardUnavailable);
|
||||
};
|
||||
match candidate
|
||||
.account
|
||||
.status_projection(now, candidate.signals.cooldown)
|
||||
.status
|
||||
{
|
||||
AccountStatus::Normal => AffinitySelection::preferred(account_id),
|
||||
AccountStatus::QuotaPaused
|
||||
| AccountStatus::QuotaExhausted
|
||||
| AccountStatus::RateLimited
|
||||
| AccountStatus::Disabled
|
||||
| AccountStatus::Error => {
|
||||
AffinitySelection::escaped(account_id, affinity_unavailable_reason(candidate, now))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn affinity_unavailable_reason(
|
||||
candidate: &AccountCandidate,
|
||||
now: SystemTime,
|
||||
) -> AffinityEscapeReason {
|
||||
match candidate
|
||||
.account
|
||||
.status_projection(now, candidate.signals.cooldown)
|
||||
.status
|
||||
{
|
||||
AccountStatus::QuotaExhausted => AffinityEscapeReason::QuotaExhausted,
|
||||
AccountStatus::RateLimited | AccountStatus::QuotaPaused => AffinityEscapeReason::Cooldown,
|
||||
AccountStatus::Normal => AffinityEscapeReason::SelectionInvariant,
|
||||
AccountStatus::Disabled | AccountStatus::Error => AffinityEscapeReason::HardUnavailable,
|
||||
}
|
||||
}
|
||||
|
||||
fn active_risk_recovery<'a>(
|
||||
recovery: &'a mut HashMap<String, RiskRecoveryState>,
|
||||
account_id: &str,
|
||||
|
||||
@@ -1250,9 +1250,7 @@ pub(super) fn cold_response_stream(response: ColdResponse) -> EventStream {
|
||||
yield event;
|
||||
}
|
||||
} else if atomic_upstream_failure {
|
||||
failure.error = failure
|
||||
.error
|
||||
.with_atomic_client_events(events);
|
||||
failure.error = with_atomic_failure_events(failure.error, events, &context);
|
||||
}
|
||||
Err(continuation_recovery_error(
|
||||
failure.error,
|
||||
|
||||
@@ -135,6 +135,32 @@ fn is_replaceable_prelude(event: &ProviderEvent) -> bool {
|
||||
})
|
||||
}
|
||||
|
||||
/// WS 拒绝请求时也保留原始 error 对象,供原生 Responses 在 HTTP 首字节前交付
|
||||
pub(super) fn with_atomic_failure_events(
|
||||
mut error: ProviderError,
|
||||
events: Vec<ProviderEvent>,
|
||||
context: &AttemptContext,
|
||||
) -> ProviderError {
|
||||
if error.kind() == ProviderErrorKind::InvalidRequest
|
||||
&& error.upstream_status() == Some(400)
|
||||
&& error.retry_is_prohibited()
|
||||
&& context.client_transport() == gateway_core::engine::execution::ClientTransport::HttpSse
|
||||
&& context.endpoint() == gateway_protocol::openai::RESPONSES_PATH
|
||||
&& let [event] = events.as_slice()
|
||||
&& let Some(wire) = event.wire_event()
|
||||
&& wire.raw_websocket_message().is_some()
|
||||
&& wire.event_type() == Some("error")
|
||||
&& let Some(detail) = wire.data().get("error").and_then(Value::as_object)
|
||||
{
|
||||
error = error.with_client_visible_upstream_response(ClientVisibleUpstreamResponse::new(
|
||||
400,
|
||||
Some(b"application/json".to_vec()),
|
||||
Bytes::from(json!({ "error": detail }).to_string()),
|
||||
));
|
||||
}
|
||||
error.with_atomic_client_events(events)
|
||||
}
|
||||
|
||||
#[derive(Clone, Copy)]
|
||||
pub(super) enum ReplayBoundary {
|
||||
BeforeSemanticOutput,
|
||||
@@ -1500,15 +1526,12 @@ pub(super) fn map_upstream_failure(
|
||||
.status
|
||||
.is_some_and(|status| status.is_client_error())
|
||||
&& is_cyber_policy_code(failure.code.as_deref());
|
||||
let continuation_failure = failure
|
||||
.upstream_code()
|
||||
.filter(|code| is_history_failure_code(code))
|
||||
.map(|_| ContinuationFailure::HistoryUnavailable);
|
||||
let continuation_summary = failure.upstream_code().and_then(history_failure_summary);
|
||||
let send_state = upstream_send_state(failure.send_phase);
|
||||
let error_kind = if continuation_failure.is_some() {
|
||||
ProviderErrorKind::ContinuationRecoveryRequired
|
||||
let (error_kind, summary) = if let Some(summary) = continuation_summary {
|
||||
(ProviderErrorKind::ContinuationRecoveryRequired, summary)
|
||||
} else {
|
||||
provider_error_kind(category)
|
||||
upstream_failure_summary(category, failure.upstream_code())
|
||||
};
|
||||
let mut error = provider_error(error_kind, send_state)
|
||||
.with_upstream_failure_fields(failure.upstream_fields.clone());
|
||||
@@ -1517,7 +1540,7 @@ pub(super) fn map_upstream_failure(
|
||||
let upgrade_required = failure.send_phase == CodexUpstreamSendPhase::BeforePayload
|
||||
&& failure.status == Some(reqwest::StatusCode::UPGRADE_REQUIRED);
|
||||
if category == CodexFailureCategory::FlexUnavailable
|
||||
|| (!replay_safe && continuation_failure.is_none() && !upgrade_required)
|
||||
|| (!replay_safe && continuation_summary.is_none() && !upgrade_required)
|
||||
{
|
||||
error = error.with_retry_prohibited();
|
||||
}
|
||||
@@ -1552,9 +1575,9 @@ pub(super) fn map_upstream_failure(
|
||||
if replay_boundary.permits_provider_proof() && replay_safe {
|
||||
error = error.with_replay_safe();
|
||||
}
|
||||
if let Some(continuation_failure) = continuation_failure {
|
||||
if continuation_summary.is_some() {
|
||||
error = error
|
||||
.with_continuation_failure(continuation_failure)
|
||||
.with_continuation_failure(ContinuationFailure::HistoryUnavailable)
|
||||
.with_continuation_recovery_disposition(
|
||||
ContinuationRecoveryDisposition::ClientReplayRequired,
|
||||
)
|
||||
@@ -1595,16 +1618,13 @@ pub(super) fn map_upstream_failure(
|
||||
if let Some(request_id) = failure.request_id.as_deref() {
|
||||
error = error.with_upstream_request_id(OpaqueUpstreamValue::new(request_id.to_owned()));
|
||||
}
|
||||
let status = error
|
||||
.upstream_status()
|
||||
.map_or_else(|| "none".to_owned(), |status| status.to_string());
|
||||
let kind = error.kind().as_str();
|
||||
let summary = if cyber_policy_failure {
|
||||
"请求被上游安全策略拦截"
|
||||
} else {
|
||||
summary
|
||||
};
|
||||
error = error.with_diagnostic(
|
||||
ProviderDiagnostic::new(format!(
|
||||
"OpenAI upstream failure: kind={}, status={status}",
|
||||
kind
|
||||
))
|
||||
.with_classification("upstream", "upstream_rejected"),
|
||||
ProviderDiagnostic::new(summary).with_classification("upstream", "upstream_rejected"),
|
||||
);
|
||||
MappedProviderFailure {
|
||||
error,
|
||||
@@ -1633,38 +1653,80 @@ pub(super) fn is_cyber_policy_code(code: Option<&str>) -> bool {
|
||||
code.is_some_and(|code| code.trim().eq_ignore_ascii_case("cyber_policy"))
|
||||
}
|
||||
|
||||
pub(super) fn is_history_failure_code(code: &str) -> bool {
|
||||
[
|
||||
"previous_response_not_found",
|
||||
"invalid_encrypted_content",
|
||||
"missing_tool_output",
|
||||
"no_tool_output",
|
||||
]
|
||||
.iter()
|
||||
.any(|known| code.trim().eq_ignore_ascii_case(known))
|
||||
fn history_failure_summary(code: &str) -> Option<&'static str> {
|
||||
let code = code.trim();
|
||||
if code.eq_ignore_ascii_case("previous_response_not_found") {
|
||||
Some("上游找不到先前的响应")
|
||||
} else if code.eq_ignore_ascii_case("invalid_encrypted_content") {
|
||||
Some("上游拒绝了加密的历史内容")
|
||||
} else if code.eq_ignore_ascii_case("missing_tool_output")
|
||||
|| code.eq_ignore_ascii_case("no_tool_output")
|
||||
{
|
||||
Some("对话历史缺少工具调用结果")
|
||||
} else {
|
||||
None
|
||||
}
|
||||
}
|
||||
|
||||
pub(super) const fn provider_error_kind(category: CodexFailureCategory) -> ProviderErrorKind {
|
||||
fn upstream_failure_summary(
|
||||
category: CodexFailureCategory,
|
||||
code: Option<&str>,
|
||||
) -> (ProviderErrorKind, &'static str) {
|
||||
match category {
|
||||
CodexFailureCategory::ModelUnsupported => ProviderErrorKind::Unsupported,
|
||||
CodexFailureCategory::CredentialExpired => ProviderErrorKind::Unauthorized,
|
||||
CodexFailureCategory::IdentityVerificationRequired | CodexFailureCategory::Banned => {
|
||||
ProviderErrorKind::PermissionDenied
|
||||
CodexFailureCategory::ModelUnsupported => {
|
||||
(ProviderErrorKind::Unsupported, "上游账号不支持此模型")
|
||||
}
|
||||
CodexFailureCategory::UsageLimitExhausted => ProviderErrorKind::QuotaExhausted,
|
||||
CodexFailureCategory::RateLimited | CodexFailureCategory::TurnRateLimited => {
|
||||
ProviderErrorKind::RateLimited
|
||||
CodexFailureCategory::CredentialExpired => {
|
||||
(ProviderErrorKind::Unauthorized, "上游账号凭据无效")
|
||||
}
|
||||
CodexFailureCategory::QuotaExhausted => ProviderErrorKind::QuotaExhausted,
|
||||
CodexFailureCategory::CloudflareChallenge
|
||||
| CodexFailureCategory::CloudflarePathBlocked
|
||||
| CodexFailureCategory::FlexUnavailable
|
||||
| CodexFailureCategory::Unavailable => ProviderErrorKind::Unavailable,
|
||||
CodexFailureCategory::CapacityUnavailable => ProviderErrorKind::UpstreamCapacityUnavailable,
|
||||
CodexFailureCategory::InvalidRequest => ProviderErrorKind::InvalidRequest,
|
||||
CodexFailureCategory::PermissionDenied => ProviderErrorKind::PermissionDenied,
|
||||
CodexFailureCategory::Timeout => ProviderErrorKind::Timeout,
|
||||
CodexFailureCategory::Transport => ProviderErrorKind::Transport,
|
||||
CodexFailureCategory::IdentityVerificationRequired => {
|
||||
(ProviderErrorKind::PermissionDenied, "上游账号需要验证身份")
|
||||
}
|
||||
CodexFailureCategory::Banned => (ProviderErrorKind::PermissionDenied, "上游账号已被停用"),
|
||||
CodexFailureCategory::UsageLimitExhausted => (
|
||||
ProviderErrorKind::QuotaExhausted,
|
||||
"当前用量窗口的额度已用完",
|
||||
),
|
||||
CodexFailureCategory::QuotaExhausted => {
|
||||
(ProviderErrorKind::QuotaExhausted, "上游账号额度已用完")
|
||||
}
|
||||
CodexFailureCategory::RateLimited => (ProviderErrorKind::RateLimited, "上游请求频率受限"),
|
||||
CodexFailureCategory::TurnRateLimited => {
|
||||
(ProviderErrorKind::RateLimited, "当前对话轮次受到限流")
|
||||
}
|
||||
CodexFailureCategory::CloudflareChallenge => {
|
||||
(ProviderErrorKind::Unavailable, "Cloudflare 要求验证请求")
|
||||
}
|
||||
CodexFailureCategory::CloudflarePathBlocked => {
|
||||
(ProviderErrorKind::Unavailable, "上游接口返回空的 404 响应")
|
||||
}
|
||||
CodexFailureCategory::FlexUnavailable => {
|
||||
(ProviderErrorKind::Unavailable, "Flex 服务容量不足")
|
||||
}
|
||||
CodexFailureCategory::CapacityUnavailable => (
|
||||
ProviderErrorKind::UpstreamCapacityUnavailable,
|
||||
"上游模型容量不足",
|
||||
),
|
||||
CodexFailureCategory::InvalidRequest => {
|
||||
let summary = match code.map(str::trim) {
|
||||
Some(code) if code.eq_ignore_ascii_case("unsupported_value") => {
|
||||
"上游不支持该参数值"
|
||||
}
|
||||
Some(code) if code.eq_ignore_ascii_case("invalid_prompt") => "上游拒绝了提示词",
|
||||
Some(code) if code.eq_ignore_ascii_case("context_length_exceeded") => {
|
||||
"输入超出模型上下文长度"
|
||||
}
|
||||
_ => "上游拒绝了请求参数",
|
||||
};
|
||||
(ProviderErrorKind::InvalidRequest, summary)
|
||||
}
|
||||
CodexFailureCategory::PermissionDenied => (
|
||||
ProviderErrorKind::PermissionDenied,
|
||||
"上游账号无权执行此请求",
|
||||
),
|
||||
CodexFailureCategory::Timeout => (ProviderErrorKind::Timeout, "上游响应超时"),
|
||||
CodexFailureCategory::Unavailable => (ProviderErrorKind::Unavailable, "上游服务暂不可用"),
|
||||
CodexFailureCategory::Transport => (ProviderErrorKind::Transport, "上游返回了非预期响应"),
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -2,7 +2,10 @@
|
||||
|
||||
use gateway_core::diagnostics::{StreamCapture, StreamFormat, TraceContext, diagnostic_json};
|
||||
|
||||
use std::{sync::Arc, time::Instant};
|
||||
use std::{
|
||||
sync::Arc,
|
||||
time::{Duration, Instant},
|
||||
};
|
||||
|
||||
use futures::{StreamExt, TryStreamExt};
|
||||
use gateway_protocol::openai::{
|
||||
@@ -32,9 +35,10 @@ use crate::transport::{
|
||||
},
|
||||
response_meta,
|
||||
websocket::{
|
||||
CodexWebSocketConnection, CodexWebSocketExchangeError, CodexWebSocketPoolKey,
|
||||
DEFAULT_STREAM_IDLE_TIMEOUT, PreviousResponseUnavailableReason, WEBSOCKET_FAST_PATH_BUDGET,
|
||||
WebSocketFastPath, execute_prepared_response_create_request_stream, post_send_ambiguous,
|
||||
CodexWebSocketConnection, CodexWebSocketExchangeError, CodexWebSocketPool,
|
||||
CodexWebSocketPoolKey, DEFAULT_FAST_PATH_BUDGET_MS, DEFAULT_STREAM_IDLE_TIMEOUT,
|
||||
PreviousResponseUnavailableReason, WebSocketFastPath,
|
||||
execute_prepared_response_create_request_stream, post_send_ambiguous,
|
||||
prepare_response_create_request_with_pool, websocket_audit_dir,
|
||||
write_websocket_audit_artifact_from_env,
|
||||
},
|
||||
@@ -375,7 +379,10 @@ impl CodexBackendClient {
|
||||
.map(|pool| (pool, pool_key, downstream_cancellation));
|
||||
let fast_path_budget = match requirement {
|
||||
TransportRequirement::PersistedContinuation | TransportRequirement::NewChain => {
|
||||
Some(WEBSOCKET_FAST_PATH_BUDGET)
|
||||
Some(self.websocket_pool.as_deref().map_or(
|
||||
Duration::from_millis(DEFAULT_FAST_PATH_BUDGET_MS),
|
||||
CodexWebSocketPool::fast_path_budget,
|
||||
))
|
||||
}
|
||||
TransportRequirement::ExplicitWebSocketWarmup
|
||||
| TransportRequirement::WebSocketNewChain
|
||||
|
||||
@@ -56,10 +56,10 @@ pub(super) struct DesktopArtifact {
|
||||
pub etag: &'static str,
|
||||
}
|
||||
|
||||
// 官方 npm 稳定标签及六个平台依赖;核验于 2026-11-14T02:09:52Z
|
||||
// 官方 npm 稳定版本及六个平台依赖,核验于 2026-11-19T00:51:11Z
|
||||
pub(super) const CLI_RELEASE: CoreRelease = CoreRelease {
|
||||
version: "0.169.0",
|
||||
verified_at_millis: 1_794_622_192_000,
|
||||
version: "0.170.0",
|
||||
verified_at_millis: 1_795_049_471_000,
|
||||
};
|
||||
|
||||
// macOS arm64 ZIP;核验于 2026-11-14T02:09:52Z
|
||||
|
||||
@@ -198,7 +198,7 @@ pub fn websocket_response_create_payload(request: &CodexResponsesRequest) -> Val
|
||||
Value::Object(payload)
|
||||
}
|
||||
|
||||
/// 借用原始 body 序列化 `response.create` 帧,不复制字段
|
||||
/// 借用原始 body 序列化 `response.create` 消息,不复制字段
|
||||
///
|
||||
/// 输出与序列化 [`websocket_response_create_payload`] 的合并 Map 逐字节一致:
|
||||
/// body 自带 `type` 键时以 body 值置于首位,其余字段按插入顺序原样透传
|
||||
@@ -224,7 +224,7 @@ impl serde::Serialize for ResponseCreateFrame<'_> {
|
||||
}
|
||||
}
|
||||
|
||||
/// 生成 Responses WebSocket `response.create` 文本帧内容
|
||||
/// 生成 Responses WebSocket `response.create` 消息的完整文本
|
||||
pub fn websocket_response_create_payload_text(
|
||||
request: &CodexResponsesRequest,
|
||||
) -> Result<String, serde_json::Error> {
|
||||
|
||||
@@ -32,8 +32,6 @@ use super::{
|
||||
pump::{PumpLogContext, PumpedWebSocket, transport_metric_reason},
|
||||
};
|
||||
|
||||
pub(crate) const WEBSOCKET_FAST_PATH_BUDGET: Duration = Duration::from_millis(800);
|
||||
|
||||
/// WebSocket 快路径的控制流结果;预算未命中不代表连接失败
|
||||
pub(crate) enum WebSocketFastPath<T> {
|
||||
/// 在前台预算内获得结果
|
||||
@@ -575,7 +573,7 @@ async fn wait_for_shared_connect(
|
||||
wait_for_fast_path(waiter.started_at(), fast_path_budget, waiter.wait()).await
|
||||
}
|
||||
|
||||
// 同一次 opening 的所有等待者共享截止时间;后来的请求不会重置 800ms 预算
|
||||
// 同一次 opening 的所有等待者共享截止时间
|
||||
async fn wait_for_fast_path<F: Future>(
|
||||
started_at: TokioInstant,
|
||||
budget: Option<Duration>,
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
//! Responses WebSocket endpoint、opening handshake 与首帧发送
|
||||
//! Responses WebSocket endpoint、opening handshake 与请求发送
|
||||
|
||||
use std::{error::Error as _, io, time::Duration};
|
||||
|
||||
@@ -35,7 +35,7 @@ use super::{
|
||||
use super::control::WEBSOCKET_SEND_TIMEOUT;
|
||||
|
||||
const WEBSOCKET_EXTENSIONS: &str = "permessage-deflate; client_max_window_bits";
|
||||
const WEBSOCKET_CONNECT_TIMEOUT: Duration = Duration::from_secs(15);
|
||||
pub(crate) const WEBSOCKET_CONNECT_TIMEOUT: Duration = Duration::from_secs(15);
|
||||
|
||||
impl CodexWebSocketConnection {
|
||||
/// 复用传输库的握手编码检查,不能在拨号后才发现插件输出不可表示
|
||||
@@ -95,7 +95,7 @@ impl CodexWebSocketConnection {
|
||||
}
|
||||
}
|
||||
|
||||
/// 构造 Responses WebSocket opening 与首个 `response.create` 文本帧
|
||||
/// 构造 Responses WebSocket opening 与首条 `response.create` 消息
|
||||
pub fn responses_create_request(
|
||||
base_url: &str,
|
||||
websocket_key: &str,
|
||||
|
||||
@@ -39,11 +39,11 @@ pub use self::{
|
||||
};
|
||||
pub(crate) use self::{
|
||||
coordinator::{
|
||||
PreparedWebSocket, WEBSOCKET_FAST_PATH_BUDGET, WebSocketFastPath,
|
||||
execute_prepared_response_create_request_stream, post_send_ambiguous,
|
||||
prepare_response_create_request_with_pool,
|
||||
PreparedWebSocket, WebSocketFastPath, execute_prepared_response_create_request_stream,
|
||||
post_send_ambiguous, prepare_response_create_request_with_pool,
|
||||
},
|
||||
error::WEBSOCKET_CLOSE_MESSAGE_TOO_BIG,
|
||||
handshake::WEBSOCKET_CONNECT_TIMEOUT,
|
||||
live::{connect_live_sideband, into_live_relay},
|
||||
pool::DEFAULT_STREAM_IDLE_TIMEOUT,
|
||||
pool::{DEFAULT_FAST_PATH_BUDGET_MS, DEFAULT_STREAM_IDLE_TIMEOUT},
|
||||
};
|
||||
|
||||
@@ -147,7 +147,7 @@ impl CodexWebSocketRequest {
|
||||
&self.connection
|
||||
}
|
||||
|
||||
/// 返回将要发送的首个文本帧
|
||||
/// 返回将要发送的完整 `response.create` 文本
|
||||
pub fn payload_text(&self) -> &str {
|
||||
&self.payload_text
|
||||
}
|
||||
|
||||
@@ -37,6 +37,7 @@ pub(crate) use self::{
|
||||
};
|
||||
|
||||
const DEFAULT_MAX_CONNECTING: usize = 16;
|
||||
pub(crate) const DEFAULT_FAST_PATH_BUDGET_MS: u64 = 800;
|
||||
const DEFAULT_MAX_AGE: Duration = Duration::from_mins(55);
|
||||
const DEFAULT_MAINTENANCE_INTERVAL: Duration = Duration::from_secs(5);
|
||||
const DEFAULT_IDLE_TIMEOUT: Duration = Duration::from_secs(300);
|
||||
@@ -70,6 +71,8 @@ pub struct CodexWebSocketPoolConfig {
|
||||
pub max_age: Duration,
|
||||
/// 所有账号合计允许并发执行的 opening 数
|
||||
pub max_connecting: usize,
|
||||
/// 允许回退 HTTP 的请求在前台等待 WebSocket 建连的时长
|
||||
pub fast_path_budget: Duration,
|
||||
/// 后台维护间隔;`None` 表示不启动后台任务
|
||||
pub maintenance_interval: Option<Duration>,
|
||||
/// 未绑定下游 WS 的连接归池后可空闲的时间,不由 Ping/Pong 刷新
|
||||
@@ -84,6 +87,7 @@ impl Default for CodexWebSocketPoolConfig {
|
||||
enabled: true,
|
||||
max_age: DEFAULT_MAX_AGE,
|
||||
max_connecting: DEFAULT_MAX_CONNECTING,
|
||||
fast_path_budget: Duration::from_millis(DEFAULT_FAST_PATH_BUDGET_MS),
|
||||
maintenance_interval: Some(DEFAULT_MAINTENANCE_INTERVAL),
|
||||
idle_timeout: DEFAULT_IDLE_TIMEOUT,
|
||||
stream_idle_timeout: Some(DEFAULT_STREAM_IDLE_TIMEOUT),
|
||||
@@ -117,6 +121,10 @@ impl CodexWebSocketPool {
|
||||
pool
|
||||
}
|
||||
|
||||
pub(crate) fn fast_path_budget(&self) -> Duration {
|
||||
self.config.fast_path_budget
|
||||
}
|
||||
|
||||
/// 等待下一条上游消息的空闲超时;`None` 或零值使用默认 300 秒
|
||||
pub(crate) fn stream_idle_timeout(&self) -> Option<Duration> {
|
||||
self.config.stream_idle_timeout
|
||||
|
||||
@@ -11,9 +11,13 @@ use std::sync::{
|
||||
};
|
||||
use std::time::Duration;
|
||||
|
||||
use bytes::Bytes;
|
||||
use futures::{Sink, SinkExt, Stream, StreamExt};
|
||||
use tokio::{sync::mpsc, task::JoinHandle, time::Instant};
|
||||
use tokio_tungstenite::tungstenite::Message;
|
||||
use tungstenite::{
|
||||
Message,
|
||||
protocol::frame::{Fragment, Frame, coding::Data},
|
||||
};
|
||||
use uuid::Uuid;
|
||||
|
||||
use super::{
|
||||
@@ -311,7 +315,7 @@ impl PumpedWebSocket {
|
||||
}
|
||||
}
|
||||
|
||||
/// 通过 pump 发送一帧,区分未开始发送与底层传输失败
|
||||
/// 通过 pump 发送一条消息,区分未开始发送与底层传输失败
|
||||
pub(crate) async fn send(&self, message: Message) -> Result<(), CodexWebSocketExchangeError> {
|
||||
if self.is_closed() {
|
||||
return Err(CodexWebSocketExchangeError::SendNotStarted);
|
||||
@@ -613,7 +617,7 @@ async fn handle_command(
|
||||
return None;
|
||||
}
|
||||
let is_close = matches!(message, Message::Close(_));
|
||||
let result = inner.send(message).await;
|
||||
let result = write_message(inner, message).await;
|
||||
let transport_error = result
|
||||
.as_ref()
|
||||
.err()
|
||||
@@ -629,6 +633,31 @@ async fn handle_command(
|
||||
}
|
||||
}
|
||||
|
||||
/// 同一命令内逐帧写完大文本,保持一条消息的压缩上下文和发送回执
|
||||
async fn write_message(
|
||||
inner: &mut RawWsStream,
|
||||
message: Message,
|
||||
) -> Result<(), tungstenite::Error> {
|
||||
const FRAGMENT_BYTES: usize = 1024 * 1024;
|
||||
let mut remaining = match message {
|
||||
Message::Text(text) if text.len() > FRAGMENT_BYTES => Bytes::from(text),
|
||||
other => return inner.send(other).await,
|
||||
};
|
||||
let mut opcode = Data::Text;
|
||||
while !remaining.is_empty() {
|
||||
let payload = remaining.split_to(remaining.len().min(FRAGMENT_BYTES));
|
||||
let fragment = if remaining.is_empty() {
|
||||
Fragment::Final
|
||||
} else {
|
||||
Fragment::More
|
||||
};
|
||||
let frame = Frame::message_fragment(payload, opcode, fragment);
|
||||
inner.send(Message::Frame(frame)).await?;
|
||||
opcode = Data::Continue;
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
fn record_activity(lifecycle: &Mutex<PumpLifecycleState>, observed_at: Instant) {
|
||||
lifecycle
|
||||
.lock()
|
||||
|
||||
@@ -811,12 +811,6 @@ async fn openai_admin_provider_persists_the_full_pending_envelope_and_binds_owne
|
||||
.get("mutation")
|
||||
.and_then(Value::as_object)
|
||||
.expect("pending mutation");
|
||||
assert!(
|
||||
payload
|
||||
.expose_to_provider()
|
||||
.get("reauthorization_credential_revision")
|
||||
.is_none()
|
||||
);
|
||||
assert!(
|
||||
payload
|
||||
.expose_to_provider()
|
||||
@@ -829,13 +823,8 @@ async fn openai_admin_provider_persists_the_full_pending_envelope_and_binds_owne
|
||||
mutation.get("schema_version").and_then(Value::as_u64),
|
||||
Some(3)
|
||||
);
|
||||
assert!(mutation.get("expected_config_revision").is_none());
|
||||
assert!(
|
||||
mutation
|
||||
.get("target")
|
||||
.and_then(Value::as_object)
|
||||
.is_some_and(|target| target.get("expected_credential_revision").is_none())
|
||||
);
|
||||
assert_eq!(mutation["target"]["kind"], "create");
|
||||
assert_eq!(mutation["target"]["name"], "OAuth account");
|
||||
assert_eq!(
|
||||
mutation.get("started_request_id").and_then(Value::as_str),
|
||||
Some("request-start")
|
||||
@@ -1037,11 +1026,6 @@ async fn openai_reauthorization_pending_payload_reuses_the_account_installation_
|
||||
document.get("installation_id").and_then(Value::as_str),
|
||||
Some(expected_installation_id.as_str())
|
||||
);
|
||||
assert!(
|
||||
document
|
||||
.get("reauthorization_credential_revision")
|
||||
.is_none()
|
||||
);
|
||||
assert_eq!(
|
||||
target.get("kind").and_then(Value::as_str),
|
||||
Some("reauthorize")
|
||||
@@ -1050,7 +1034,6 @@ async fn openai_reauthorization_pending_payload_reuses_the_account_installation_
|
||||
target.get("account_id").and_then(Value::as_str),
|
||||
Some("acct_pending_reauth")
|
||||
);
|
||||
assert!(target.get("expected_credential_revision").is_none());
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
@@ -2942,7 +2925,6 @@ mod errors {
|
||||
.prepare_refresh(command())
|
||||
.await
|
||||
.unwrap_err();
|
||||
// 既有 transport 策略未认定此错误为安全重试,本次不能因展示更详细而放宽重试边界
|
||||
assert_eq!(error.kind(), Kind::Ambiguous);
|
||||
assert_eq!(
|
||||
error.public_message(),
|
||||
|
||||
@@ -96,26 +96,53 @@ fn openai_stream_retry_budget_uses_the_official_hard_cap() {
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn websocket_pool_idle_timeout_accepts_existing_configs_and_explicit_overrides() {
|
||||
for (idle_timeout_ms, expected) in [(None, 300_000), (Some(600_000), 600_000)] {
|
||||
let mut document = serde_json::json!({
|
||||
"ws_pool": {
|
||||
fn websocket_pool_timeouts_accept_defaults_and_individual_overrides() {
|
||||
for (settings, idle_ms, fast_ms) in [
|
||||
(
|
||||
serde_json::json!({
|
||||
"enabled": true,
|
||||
"max_age_ms": 3_300_000,
|
||||
"max_connecting": 8,
|
||||
"stream_idle_timeout_ms": 300_000
|
||||
}
|
||||
});
|
||||
if let Some(idle_timeout_ms) = idle_timeout_ms {
|
||||
document["ws_pool"]["idle_timeout_ms"] = serde_json::json!(idle_timeout_ms);
|
||||
}
|
||||
let mut config: OpenAiConfig = serde_json::from_value(document).unwrap();
|
||||
}),
|
||||
300_000,
|
||||
800,
|
||||
),
|
||||
(
|
||||
serde_json::json!({"idle_timeout_ms": 600_000}),
|
||||
600_000,
|
||||
800,
|
||||
),
|
||||
(serde_json::json!({"fast_path_budget_ms": 1}), 300_000, 1),
|
||||
(
|
||||
serde_json::json!({"fast_path_budget_ms": 15_000}),
|
||||
300_000,
|
||||
15_000,
|
||||
),
|
||||
] {
|
||||
let mut config: OpenAiConfig =
|
||||
serde_json::from_value(serde_json::json!({"ws_pool": settings})).unwrap();
|
||||
config
|
||||
.resolve_and_validate(Path::new("/srv/gateway"))
|
||||
.unwrap();
|
||||
assert_eq!(
|
||||
config.websocket_pool_config().idle_timeout,
|
||||
Duration::from_millis(expected)
|
||||
let pool = config.websocket_pool_config();
|
||||
assert_eq!(pool.idle_timeout, Duration::from_millis(idle_ms));
|
||||
assert_eq!(pool.fast_path_budget, Duration::from_millis(fast_ms));
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn websocket_fast_path_budget_must_fit_the_opening_timeout() {
|
||||
for budget_ms in [0, 15_001] {
|
||||
let mut config = valid_config();
|
||||
config.ws_pool.fast_path_budget_ms = budget_ms;
|
||||
let error = config
|
||||
.resolve_and_validate(Path::new("/srv/gateway"))
|
||||
.unwrap_err();
|
||||
assert!(
|
||||
error
|
||||
.to_string()
|
||||
.contains("openai.ws_pool.fast_path_budget_ms")
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -232,7 +232,6 @@ async fn warmup_uses_global_profile_and_lowest_reasoning_effort() {
|
||||
zstd::stream::decode_all(requests[0].body.as_slice()).expect("zstd body should decode");
|
||||
let body: serde_json::Value =
|
||||
serde_json::from_slice(&decoded).expect("warmup body should be valid JSON");
|
||||
// 上游按目录拒绝目录外的档位,none 曾让全部定时预热只留下 error 终态
|
||||
assert_eq!(body["reasoning"]["effort"], "low");
|
||||
*policy.0.lock().unwrap() = OpaqueProviderData::new(
|
||||
json!({"mode":"custom","userAgent":"invalid"})
|
||||
|
||||
@@ -128,6 +128,9 @@ async fn upstream_codes_survive_http_and_websocket_opening_without_normalization
|
||||
body,
|
||||
);
|
||||
let diagnostic = error.diagnostic().expect("safe diagnostic");
|
||||
if expected_kind == ProviderErrorKind::ContinuationRecoveryRequired {
|
||||
assert_eq!(diagnostic.as_str(), "上游找不到先前的响应");
|
||||
}
|
||||
assert!(!diagnostic.as_str().contains(original_code));
|
||||
assert!(!diagnostic.as_str().contains("PRIVATE_UPSTREAM_DETAIL"));
|
||||
assert!(!format!("{error:?} {error}").contains(original_code));
|
||||
|
||||
@@ -3559,7 +3559,7 @@ async fn assert_cross_endpoint_affinity(thread_id: Option<&str>) {
|
||||
}
|
||||
drop(same);
|
||||
|
||||
// 仍由旧租约流程报告繁忙并换号,亲和不绕过并发限制
|
||||
// 亲和账号的并发租约已满时,请求应切换账号
|
||||
leases
|
||||
.busy_accounts
|
||||
.lock()
|
||||
@@ -8875,6 +8875,7 @@ async fn capacity_http_and_websocket_opening_rejections_use_bounded_business_ret
|
||||
}
|
||||
};
|
||||
assert_eq!(error.kind(), ProviderErrorKind::UpstreamCapacityUnavailable);
|
||||
assert_eq!(error.diagnostic().unwrap().as_str(), "上游模型容量不足");
|
||||
assert_eq!(error.upstream_status(), Some(status));
|
||||
assert!(error.replay_is_safe());
|
||||
assert_eq!(error.retry_after(), Some(Duration::from_secs(129600)));
|
||||
|
||||
@@ -70,6 +70,78 @@ pub(super) async fn stream_failure(
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn bare_websocket_bad_request_offers_http_error_only_for_native_responses_sse() {
|
||||
use ClientTransport::{HttpJson, HttpSse, WebSocket};
|
||||
use gateway_protocol::openai::RESPONSES_PATH;
|
||||
|
||||
let detail = json!({
|
||||
"type":"invalid_request_error", "code":"invalid_value", "message":"Invalid input.",
|
||||
"param":"input[2].id", "extension":{"reason":"duplicate"}
|
||||
});
|
||||
let bad_request = json!({"type":"error", "status":400, "error":detail, "sequence_number":7});
|
||||
let no_status = json!({"type":"error", "error":detail});
|
||||
let response_failed = json!({"type":"response.failed", "status":400, "response":{"id":"resp_failed","error":detail}});
|
||||
let capacity = json!({"status":400, "type":"error", "error":overload()["error"]});
|
||||
for (endpoint, transport, frame, expects_http) in [
|
||||
(RESPONSES_PATH, HttpSse, &bad_request, true),
|
||||
(RESPONSES_PATH, WebSocket, &bad_request, false),
|
||||
(RESPONSES_PATH, HttpJson, &bad_request, false),
|
||||
("/v1/chat/completions", HttpSse, &bad_request, false),
|
||||
(RESPONSES_PATH, HttpSse, &no_status, false),
|
||||
(RESPONSES_PATH, HttpSse, &response_failed, false),
|
||||
(RESPONSES_PATH, HttpSse, &capacity, false),
|
||||
] {
|
||||
let store = Arc::new(MemoryAccountStore::default());
|
||||
create_account(&store, "acct_provider_contract").await;
|
||||
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
|
||||
let base_url = format!("http://{}", listener.local_addr().unwrap());
|
||||
let raw = frame.to_string();
|
||||
let server = tokio::spawn(async move {
|
||||
let (socket, _) = listener.accept().await.unwrap();
|
||||
let mut ws = accept_codex_test_websocket(socket).await;
|
||||
ws.next().await.unwrap().unwrap();
|
||||
ws.send(Message::Text(raw.into())).await.unwrap();
|
||||
});
|
||||
let request = RequestAttemptContext::new(
|
||||
ModelRequestId::new("req_ws_bad_input").unwrap(),
|
||||
ClientApiKeyId::new("key_openai_contract").unwrap(),
|
||||
)
|
||||
.with_middleware(None, Arc::from([]), endpoint.to_owned(), transport)
|
||||
.with_request_location(Some(global_request_location()));
|
||||
let mut stream = provider_with_base_url(&store, base_url)
|
||||
.execute(
|
||||
planned_request("openai", generate_operation()),
|
||||
context_for_request(request, CancellationToken::new()),
|
||||
)
|
||||
.await
|
||||
.unwrap();
|
||||
let (events, mut error) = stream_failure(&mut stream).await;
|
||||
assert!(events.iter().all(|event| !event.has_client_event()));
|
||||
let response = error.client_visible_upstream_response();
|
||||
assert_eq!(
|
||||
response.is_some(),
|
||||
expects_http,
|
||||
"{endpoint} {transport:?} {frame}"
|
||||
);
|
||||
if let Some(response) = response {
|
||||
assert_eq!(response.status(), 400);
|
||||
assert_eq!(
|
||||
response.content_type(),
|
||||
Some(b"application/json".as_slice())
|
||||
);
|
||||
assert_eq!(
|
||||
serde_json::from_slice::<Value>(response.body()).unwrap(),
|
||||
json!({"error":detail})
|
||||
);
|
||||
}
|
||||
let events = error.take_atomic_client_events();
|
||||
assert_eq!(events.len(), 1);
|
||||
assert_eq!(events[0].wire_event().unwrap().data(), frame);
|
||||
server.await.unwrap();
|
||||
}
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn large_preludes_are_forwarded_before_failure_on_http_and_websocket() {
|
||||
for websocket in [false, true] {
|
||||
|
||||
@@ -341,6 +341,31 @@ async fn downstream_websocket_new_chain_should_preserve_continuation_after_slow_
|
||||
|
||||
#[tokio::test]
|
||||
async fn external_continuation_should_wait_for_a_cold_websocket() {
|
||||
assert_slow_opening_uses_websocket(
|
||||
external_continuation_request("conversation-cross-account"),
|
||||
CodexWebSocketPoolConfig::default(),
|
||||
)
|
||||
.await;
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn configured_fast_path_budget_should_allow_slow_websocket_openings() {
|
||||
let config = CodexWebSocketPoolConfig {
|
||||
fast_path_budget: Duration::from_secs(3),
|
||||
..Default::default()
|
||||
};
|
||||
let mut persisted = new_chain_request("persisted");
|
||||
persisted.set_previous_response_id(Some("resp_persisted".into()));
|
||||
persisted.previous_response_scope = Some(PreviousResponseScope::Persisted);
|
||||
for request in [new_chain_request("new-chain"), persisted] {
|
||||
assert_slow_opening_uses_websocket(request, config).await;
|
||||
}
|
||||
}
|
||||
|
||||
async fn assert_slow_opening_uses_websocket(
|
||||
request: CodexResponsesRequest,
|
||||
config: CodexWebSocketPoolConfig,
|
||||
) {
|
||||
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
|
||||
let addr = listener.local_addr().unwrap();
|
||||
let server = tokio::spawn(async move {
|
||||
@@ -350,12 +375,12 @@ async fn external_continuation_should_wait_for_a_cold_websocket() {
|
||||
let _payload = websocket.next().await.unwrap().unwrap();
|
||||
websocket
|
||||
.send(Message::Text(
|
||||
completed_websocket_response("resp_cross_account", 2, 1).into(),
|
||||
completed_websocket_response("resp_slow_opening", 2, 1).into(),
|
||||
))
|
||||
.await
|
||||
.unwrap();
|
||||
});
|
||||
let pool = Arc::new(CodexWebSocketPool::default());
|
||||
let pool = Arc::new(CodexWebSocketPool::with_config(config));
|
||||
let backend = CodexBackendClient::new(
|
||||
reqwest::Client::builder().no_proxy().build().unwrap(),
|
||||
format!("http://{addr}"),
|
||||
@@ -363,13 +388,16 @@ async fn external_continuation_should_wait_for_a_cold_websocket() {
|
||||
)
|
||||
.with_websocket_pool(Arc::clone(&pool));
|
||||
|
||||
let response = backend
|
||||
.create_response(
|
||||
&external_continuation_request("conversation-cross-account"),
|
||||
request_context("req_cross_account", Some("chatgpt-account-b")),
|
||||
)
|
||||
.await
|
||||
.expect("external continuation should complete over WebSocket");
|
||||
let response = timeout(
|
||||
Duration::from_secs(5),
|
||||
backend.create_response(
|
||||
&request,
|
||||
request_context("req_slow_opening", Some("chatgpt-account-b")),
|
||||
),
|
||||
)
|
||||
.await
|
||||
.expect("slow WebSocket opening should complete")
|
||||
.unwrap();
|
||||
server.await.unwrap();
|
||||
|
||||
assert_eq!(response.transport, CodexBackendTransport::WebSocket);
|
||||
|
||||
@@ -432,8 +432,7 @@ async fn lagged_profiles_track_observed_release_history() {
|
||||
);
|
||||
}
|
||||
|
||||
/// 重启后恢复缓存、首次检查即发现新版:恢复版本必须进入发布历史,
|
||||
/// 滞后一档不能跳回启动种子(PR #339 审查反馈的触发序列)。
|
||||
/// 重启后首次检查发现新版时,滞后一档应选中从缓存恢复的版本
|
||||
#[tokio::test]
|
||||
async fn restored_cache_release_should_stay_in_version_lag_history() {
|
||||
use provider_openai::transport::profile::selection::ClientProfileSelection;
|
||||
|
||||
@@ -1,8 +1,6 @@
|
||||
//! 验证 HTTP 与 WebSocket 的 TLS 握手特征
|
||||
|
||||
use std::collections::BTreeMap;
|
||||
use std::path::Path;
|
||||
use std::process::Stdio;
|
||||
|
||||
use bytes::{Buf as _, Bytes};
|
||||
|
||||
@@ -10,11 +8,8 @@ use super::*;
|
||||
|
||||
const CASE_ENV: &str = "CODEX_PROXY_TEST_HTTP_CLIENT_HELLO";
|
||||
const CASE_COMPLETED: &str = "http-tls-client-hello-case-completed";
|
||||
const REFERENCE_ENV: &str = "CODEX_PROXY_TEST_REFERENCE_BINARY";
|
||||
|
||||
// 基线来自官方 Codex 823ea830c0 的客户端源码,各路径重复采样五次
|
||||
// HTTP 另与本机 Core 0.160.0 的采样核对,源码客户端与本项目还通过真实 models 请求验证
|
||||
// HTTP/native-tls 的扩展顺序固定;WebSocket/rustls 会随机化扩展顺序和临时密钥
|
||||
// 握手基线对应官方 Codex 823ea830c0,rustls 的扩展顺序和临时密钥按连接变化
|
||||
#[derive(Debug, PartialEq, Eq)]
|
||||
struct ClientHello {
|
||||
legacy_version: u16,
|
||||
@@ -57,81 +52,22 @@ fn http_client_hellos_should_match_official_tls_transports() {
|
||||
return;
|
||||
}
|
||||
|
||||
run_isolated_cases(
|
||||
"transport::tls::http_client_hellos_should_match_official_tls_transports",
|
||||
&["native", "custom-ca"],
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
#[ignore = "requires CODEX_PROXY_TEST_REFERENCE_BINARY pointing to the official Codex executable"]
|
||||
fn client_hellos_should_match_the_official_binary_on_this_platform() {
|
||||
let reference = std::env::var_os(REFERENCE_ENV)
|
||||
.map(std::path::PathBuf::from)
|
||||
.expect("set CODEX_PROXY_TEST_REFERENCE_BINARY to the official Codex executable")
|
||||
.canonicalize()
|
||||
.expect("official Codex executable path");
|
||||
if let Ok(case) = std::env::var(CASE_ENV) {
|
||||
let runtime = tokio::runtime::Builder::new_current_thread()
|
||||
.enable_all()
|
||||
.build()
|
||||
.unwrap();
|
||||
runtime.block_on(async {
|
||||
for sample in 0..3 {
|
||||
let mut expected = capture_official_hello(&reference, case == "websocket").await;
|
||||
let mut actual = if case == "websocket" {
|
||||
capture_websocket_hello().await
|
||||
} else {
|
||||
capture_http_hello(provider_openai::transport::build_reqwest_client().unwrap())
|
||||
.await
|
||||
};
|
||||
// rustls 随机排列扩展,其他字段及各自列表的顺序仍逐项核对
|
||||
if case != "native" {
|
||||
expected.extensions.sort_unstable();
|
||||
actual.extensions.sort_unstable();
|
||||
}
|
||||
assert_eq!(actual, expected, "{case} ClientHello sample {sample}");
|
||||
}
|
||||
});
|
||||
println!("\n{CASE_COMPLETED}");
|
||||
return;
|
||||
}
|
||||
|
||||
let version = Command::new(&reference)
|
||||
.arg("--version")
|
||||
.output()
|
||||
.expect("read official Codex version");
|
||||
assert!(version.status.success());
|
||||
println!(
|
||||
"TLS reference: {} on {}-{}",
|
||||
String::from_utf8_lossy(&version.stdout).trim(),
|
||||
std::env::consts::OS,
|
||||
std::env::consts::ARCH,
|
||||
);
|
||||
run_isolated_cases(
|
||||
"transport::tls::client_hellos_should_match_the_official_binary_on_this_platform",
|
||||
&["native", "custom-ca", "websocket"],
|
||||
);
|
||||
}
|
||||
|
||||
fn run_isolated_cases(test_name: &str, cases: &[&str]) {
|
||||
// Cargo 运行测试时可能注入 SSL_CERT_FILE,生产代码会把它视作自定义 CA 并切到 rustls;
|
||||
// 因此在清理相关环境变量的子进程里验证默认路径
|
||||
let current_exe = std::env::current_exe().expect("current test binary path");
|
||||
let directory = tempfile::tempdir().unwrap();
|
||||
let ca_path = directory.path().join("ca.pem");
|
||||
std::fs::write(&ca_path, TEST_CA_PEM).unwrap();
|
||||
for case in cases {
|
||||
for case in ["native", "custom-ca"] {
|
||||
let mut command = Command::new(¤t_exe);
|
||||
command
|
||||
.arg("--exact")
|
||||
.arg(test_name)
|
||||
.arg("--include-ignored")
|
||||
.arg("transport::tls::http_client_hellos_should_match_official_tls_transports")
|
||||
.arg("--nocapture")
|
||||
.env(CASE_ENV, case)
|
||||
.env_remove(provider_openai::transport::tls::CODEX_CA_CERT_ENV)
|
||||
.env_remove(provider_openai::transport::tls::SSL_CERT_FILE_ENV);
|
||||
if *case == "custom-ca" {
|
||||
if case == "custom-ca" {
|
||||
command.env(provider_openai::transport::tls::CODEX_CA_CERT_ENV, &ca_path);
|
||||
}
|
||||
let output = command.output().expect("run isolated TLS ClientHello case");
|
||||
@@ -153,70 +89,6 @@ fn run_isolated_cases(test_name: &str, cases: &[&str]) {
|
||||
}
|
||||
}
|
||||
|
||||
async fn capture_official_hello(reference: &Path, websocket: bool) -> ClientHello {
|
||||
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
|
||||
let endpoint = format!(
|
||||
"https://localhost:{}/v1",
|
||||
listener.local_addr().unwrap().port()
|
||||
);
|
||||
let directory = tempfile::tempdir().unwrap();
|
||||
// 官方进程只访问本机采集端点,握手后即终止,认证使用无效测试值
|
||||
let mut command = tokio::process::Command::new(reference);
|
||||
command
|
||||
.args([
|
||||
"exec",
|
||||
"--ignore-user-config",
|
||||
"--ignore-rules",
|
||||
"--ephemeral",
|
||||
"--skip-git-repo-check",
|
||||
"--sandbox",
|
||||
"read-only",
|
||||
"--json",
|
||||
"--model",
|
||||
"tls-probe",
|
||||
])
|
||||
.current_dir(directory.path())
|
||||
.env("CPR_TLS_PROBE_API_KEY", "test-local-handshake-only")
|
||||
.stdin(Stdio::null())
|
||||
.stdout(Stdio::null())
|
||||
.stderr(Stdio::null())
|
||||
.kill_on_drop(true);
|
||||
for name in [
|
||||
"HTTP_PROXY",
|
||||
"HTTPS_PROXY",
|
||||
"ALL_PROXY",
|
||||
"http_proxy",
|
||||
"https_proxy",
|
||||
"all_proxy",
|
||||
] {
|
||||
command.env_remove(name);
|
||||
}
|
||||
for setting in [
|
||||
"model_provider=\"cpr_tls_probe\"".to_owned(),
|
||||
"model_providers.cpr_tls_probe.name=\"CPR TLS Probe\"".to_owned(),
|
||||
format!("model_providers.cpr_tls_probe.base_url=\"{endpoint}\""),
|
||||
"model_providers.cpr_tls_probe.env_key=\"CPR_TLS_PROBE_API_KEY\"".to_owned(),
|
||||
"model_providers.cpr_tls_probe.wire_api=\"responses\"".to_owned(),
|
||||
format!("model_providers.cpr_tls_probe.supports_websockets={websocket}"),
|
||||
"model_providers.cpr_tls_probe.request_max_retries=0".to_owned(),
|
||||
"model_providers.cpr_tls_probe.stream_max_retries=0".to_owned(),
|
||||
"project_doc_max_bytes=0".to_owned(),
|
||||
] {
|
||||
command.args(["--config", &setting]);
|
||||
}
|
||||
let mut child = command
|
||||
.arg("TLS handshake capture")
|
||||
.spawn()
|
||||
.expect("start official Codex TLS reference");
|
||||
let hello = timeout(Duration::from_secs(30), read_client_hello(listener)).await;
|
||||
let _ = child.kill().await;
|
||||
child
|
||||
.wait()
|
||||
.await
|
||||
.expect("reap official Codex TLS reference");
|
||||
hello.expect("official Codex ClientHello within timeout")
|
||||
}
|
||||
|
||||
async fn capture_http_hello(client: reqwest::Client) -> ClientHello {
|
||||
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
|
||||
let url = format!(
|
||||
@@ -237,19 +109,13 @@ async fn capture_http_hello(client: reqwest::Client) -> ClientHello {
|
||||
|
||||
#[tokio::test]
|
||||
async fn websocket_client_hello_should_match_official_rustls_transport() {
|
||||
let mut hello = capture_websocket_hello().await;
|
||||
hello.extensions.sort_unstable();
|
||||
assert_eq!(hello, official_websocket_hello());
|
||||
}
|
||||
|
||||
async fn capture_websocket_hello() -> ClientHello {
|
||||
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
|
||||
let url = format!("wss://localhost:{}/", listener.local_addr().unwrap().port());
|
||||
let connector =
|
||||
provider_openai::transport::tls::maybe_build_rustls_client_config_with_custom_ca()
|
||||
.unwrap()
|
||||
.map(tokio_tungstenite::Connector::Rustls);
|
||||
let (hello, response) = timeout(Duration::from_secs(10), async {
|
||||
let (mut hello, response) = timeout(Duration::from_secs(10), async {
|
||||
tokio::join!(
|
||||
read_client_hello(listener),
|
||||
tokio_tungstenite::connect_async_tls_with_config(url, None, false, connector)
|
||||
@@ -261,7 +127,8 @@ async fn capture_websocket_hello() -> ClientHello {
|
||||
response.is_err(),
|
||||
"capture endpoint rejects TLS after ClientHello"
|
||||
);
|
||||
hello
|
||||
hello.extensions.sort_unstable();
|
||||
assert_eq!(hello, official_websocket_hello());
|
||||
}
|
||||
|
||||
#[cfg(target_os = "linux")]
|
||||
|
||||
@@ -1,7 +1,9 @@
|
||||
//! 验证 Codex WebSocket 线协议指纹
|
||||
|
||||
use std::io::Read as _;
|
||||
|
||||
use base64::{Engine as _, engine::general_purpose::STANDARD};
|
||||
use flate2::{Decompress, FlushDecompress};
|
||||
use flate2::read::DeflateDecoder;
|
||||
use tokio_tungstenite::tungstenite::handshake::derive_accept_key;
|
||||
|
||||
use super::*;
|
||||
@@ -16,41 +18,6 @@ struct ClientFrame {
|
||||
|
||||
#[tokio::test]
|
||||
async fn official_websocket_wire_fingerprint_should_remain_aligned() {
|
||||
let listener = TcpListener::bind("127.0.0.1:0")
|
||||
.await
|
||||
.expect("bind fingerprint server");
|
||||
let address = listener.local_addr().expect("fingerprint server address");
|
||||
let server = tokio::spawn(async move {
|
||||
let (mut stream, _) = listener.accept().await.expect("accept fingerprint client");
|
||||
let opening = read_http_request(&mut stream).await;
|
||||
let websocket_key = read_header_value(&opening, "sec-websocket-key")
|
||||
.expect("WebSocket key")
|
||||
.to_owned();
|
||||
let response = format!(
|
||||
concat!(
|
||||
"HTTP/1.1 101 Switching Protocols\r\n",
|
||||
"Connection: Upgrade\r\n",
|
||||
"Upgrade: websocket\r\n",
|
||||
"Sec-WebSocket-Accept: {}\r\n",
|
||||
"Sec-WebSocket-Extensions: permessage-deflate\r\n",
|
||||
"\r\n"
|
||||
),
|
||||
derive_accept_key(websocket_key.as_bytes())
|
||||
);
|
||||
stream
|
||||
.write_all(response.as_bytes())
|
||||
.await
|
||||
.expect("write upgrade response");
|
||||
|
||||
let frame = read_client_frame(&mut stream).await;
|
||||
write_server_text_frame(
|
||||
&mut stream,
|
||||
&completed_websocket_response("resp_wire_fingerprint", 1, 1),
|
||||
)
|
||||
.await;
|
||||
(opening, websocket_key, frame)
|
||||
});
|
||||
|
||||
let mut request = encode_request_with_headers(
|
||||
json!({
|
||||
"model": "gpt-5.5",
|
||||
@@ -77,36 +44,21 @@ async fn official_websocket_wire_fingerprint_should_remain_aligned() {
|
||||
request.turn_metadata = Some(r#"{"kind":"fingerprint"}"#.to_owned());
|
||||
request.version = Some("26.908.40834".to_owned());
|
||||
request.codex_window_id = Some("window-fingerprint".to_owned());
|
||||
let client = CodexBackendClient::new(
|
||||
reqwest::Client::builder()
|
||||
.no_proxy()
|
||||
.build()
|
||||
.expect("HTTP client"),
|
||||
format!("http://{address}/backend-api"),
|
||||
test_wire_profile(),
|
||||
)
|
||||
.with_websocket_pool(Arc::new(CodexWebSocketPool::new(Duration::from_mins(1))));
|
||||
|
||||
let result = client
|
||||
.create_response(
|
||||
&request,
|
||||
CodexRequestContext {
|
||||
response_control: None,
|
||||
trace: None,
|
||||
turn_metadata: request.turn_metadata.as_deref(),
|
||||
version: request.version.as_deref(),
|
||||
codex_window_id: request.codex_window_id.as_deref(),
|
||||
session_id: Some("session-fingerprint"),
|
||||
thread_id: Some("thread-fingerprint"),
|
||||
client_request_id: Some("request-fingerprint"),
|
||||
installation_id: Some("3b11bc82-c666-417d-b9ff-2a34fd040385"),
|
||||
..request_context("req_wire_fingerprint", Some("account-fingerprint"))
|
||||
},
|
||||
)
|
||||
.await;
|
||||
|
||||
result.unwrap_or_else(|error| panic!("fingerprint WebSocket response: {error}"));
|
||||
let (opening, websocket_key, frame) = server.await.expect("fingerprint server task");
|
||||
let context = CodexRequestContext {
|
||||
turn_metadata: request.turn_metadata.as_deref(),
|
||||
version: request.version.as_deref(),
|
||||
codex_window_id: request.codex_window_id.as_deref(),
|
||||
session_id: Some("session-fingerprint"),
|
||||
thread_id: Some("thread-fingerprint"),
|
||||
client_request_id: Some("request-fingerprint"),
|
||||
installation_id: Some("3b11bc82-c666-417d-b9ff-2a34fd040385"),
|
||||
..request_context("req_wire_fingerprint", Some("account-fingerprint"))
|
||||
};
|
||||
let (opening, frames) = capture_response_create(&request, context, true).await;
|
||||
let [frame] = frames.as_slice() else {
|
||||
panic!("expected a single text frame")
|
||||
};
|
||||
let websocket_key = read_header_value(&opening, "sec-websocket-key").unwrap();
|
||||
assert_eq!(
|
||||
opening.lines().next(),
|
||||
Some("GET /backend-api/codex/responses HTTP/1.1")
|
||||
@@ -206,6 +158,121 @@ async fn official_websocket_wire_fingerprint_should_remain_aligned() {
|
||||
);
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn large_responses_use_continuation_frames_for_one_text_message() {
|
||||
const MIB: usize = 1024 * 1024;
|
||||
let make_request = |instructions: &str| {
|
||||
let mut request = codex_request("gpt-test", instructions, Vec::new());
|
||||
request.use_websocket = true;
|
||||
request.local_conversation_id = Some("fragment-test".to_owned());
|
||||
request
|
||||
};
|
||||
let context = request_context("fragment-test", Some("account-test"));
|
||||
|
||||
// 用实际序列化的空指令测量 JSON 开销,边界包含元数据
|
||||
let (_, baseline) = capture_response_create(&make_request(""), context, false).await;
|
||||
let empty_payload = std::str::from_utf8(&baseline[0].payload).unwrap();
|
||||
let instructions_key = r#""instructions":""#;
|
||||
let start = empty_payload.find(instructions_key).unwrap() + instructions_key.len();
|
||||
// FIN 只在末帧,文本操作码和压缩标记只在首帧
|
||||
for (size, deflate, headers) in [
|
||||
(MIB, false, &[0x81][..]),
|
||||
(MIB + 1, false, &[0x01, 0x80]),
|
||||
(MIB + 1, true, &[0x41, 0x80]),
|
||||
(2 * MIB + 1, true, &[0x41, 0x00, 0x80]),
|
||||
] {
|
||||
let mut instructions = "a".repeat(size - empty_payload.len());
|
||||
if size > 2 * MIB {
|
||||
// 分帧边界穿过一个 UTF-8 字符
|
||||
instructions.replace_range(MIB - start - 1..MIB - start + 3, "🌱");
|
||||
}
|
||||
let request = make_request(&instructions);
|
||||
let (_, frames) = capture_response_create(&request, context, deflate).await;
|
||||
let actual_headers: Vec<_> = frames.iter().map(|frame| frame.first_byte).collect();
|
||||
assert_eq!(actual_headers, headers);
|
||||
let mut payload = Vec::new();
|
||||
for (index, frame) in frames.iter().enumerate() {
|
||||
assert!(frame.masked);
|
||||
if !deflate {
|
||||
assert_eq!(frame.payload.len(), (size - index * MIB).min(MIB));
|
||||
}
|
||||
payload.extend_from_slice(&frame.payload);
|
||||
}
|
||||
if deflate {
|
||||
payload = decompress_permessage_deflate(&payload);
|
||||
}
|
||||
assert_eq!(payload.len(), size);
|
||||
let decoded: Value = serde_json::from_slice(&payload).unwrap();
|
||||
assert!(decoded["instructions"].as_str() == Some(&instructions));
|
||||
}
|
||||
}
|
||||
|
||||
async fn capture_response_create(
|
||||
request: &CodexResponsesRequest,
|
||||
context: CodexRequestContext<'_>,
|
||||
deflate: bool,
|
||||
) -> (String, Vec<ClientFrame>) {
|
||||
let listener = TcpListener::bind("127.0.0.1:0")
|
||||
.await
|
||||
.expect("bind fingerprint server");
|
||||
let address = listener.local_addr().expect("fingerprint server address");
|
||||
let server = tokio::spawn(async move {
|
||||
let (mut stream, _) = listener.accept().await.expect("accept fingerprint client");
|
||||
let opening = read_http_request(&mut stream).await;
|
||||
let websocket_key =
|
||||
read_header_value(&opening, "sec-websocket-key").expect("WebSocket key");
|
||||
let extension = if deflate {
|
||||
"Sec-WebSocket-Extensions: permessage-deflate\r\n"
|
||||
} else {
|
||||
""
|
||||
};
|
||||
let response = format!(
|
||||
concat!(
|
||||
"HTTP/1.1 101 Switching Protocols\r\n",
|
||||
"Connection: Upgrade\r\n",
|
||||
"Upgrade: websocket\r\n",
|
||||
"Sec-WebSocket-Accept: {}\r\n",
|
||||
"{}",
|
||||
"\r\n"
|
||||
),
|
||||
derive_accept_key(websocket_key.as_bytes()),
|
||||
extension
|
||||
);
|
||||
stream
|
||||
.write_all(response.as_bytes())
|
||||
.await
|
||||
.expect("write upgrade response");
|
||||
|
||||
let mut frames = Vec::new();
|
||||
loop {
|
||||
let frame = read_client_frame(&mut stream).await;
|
||||
let finished = frame.first_byte & 0x80 != 0;
|
||||
frames.push(frame);
|
||||
if finished {
|
||||
break;
|
||||
}
|
||||
}
|
||||
write_server_text_frame(
|
||||
&mut stream,
|
||||
&completed_websocket_response("resp_wire_fingerprint", 1, 1),
|
||||
)
|
||||
.await;
|
||||
(opening, frames)
|
||||
});
|
||||
|
||||
let client = CodexBackendClient::new(
|
||||
reqwest::Client::builder().no_proxy().build().unwrap(),
|
||||
format!("http://{address}/backend-api"),
|
||||
test_wire_profile(),
|
||||
)
|
||||
.with_websocket_pool(Arc::new(CodexWebSocketPool::new(Duration::from_mins(1))));
|
||||
client
|
||||
.create_response(request, context)
|
||||
.await
|
||||
.expect("fingerprint WebSocket response");
|
||||
server.await.expect("fingerprint server task")
|
||||
}
|
||||
|
||||
async fn read_client_frame(stream: &mut TcpStream) -> ClientFrame {
|
||||
let first_byte = stream.read_u8().await.expect("frame first byte");
|
||||
let second_byte = stream.read_u8().await.expect("frame second byte");
|
||||
@@ -239,17 +306,13 @@ async fn read_client_frame(stream: &mut TcpStream) -> ClientFrame {
|
||||
}
|
||||
|
||||
fn decompress_permessage_deflate(payload: &[u8]) -> Vec<u8> {
|
||||
let mut compressed = Vec::with_capacity(payload.len() + 4);
|
||||
compressed.extend_from_slice(payload);
|
||||
compressed.extend_from_slice(&[0x00, 0x00, 0xff, 0xff]);
|
||||
let mut output = vec![0_u8; 64 * 1024];
|
||||
let mut decompressor = Decompress::new(false);
|
||||
decompressor
|
||||
.decompress(&compressed, &mut output, FlushDecompress::Sync)
|
||||
.expect("decompress response.create frame");
|
||||
output.truncate(
|
||||
usize::try_from(decompressor.total_out()).expect("decompressed length fits usize"),
|
||||
);
|
||||
let mut compressed = payload.to_vec();
|
||||
// 补回 permessage-deflate 的同步刷新尾部,再加空终止块供完整流解码器读取
|
||||
compressed.extend_from_slice(&[0, 0, 0xff, 0xff, 1, 0, 0, 0xff, 0xff]);
|
||||
let mut output = Vec::new();
|
||||
DeflateDecoder::new(compressed.as_slice())
|
||||
.read_to_end(&mut output)
|
||||
.unwrap();
|
||||
output
|
||||
}
|
||||
|
||||
|
||||
@@ -875,7 +875,6 @@ async fn websocket_execute_response_create_request_should_forward_typed_events_w
|
||||
let (stream, _) = listener.accept().await.unwrap();
|
||||
let mut websocket = accept_codex_test_websocket(stream).await;
|
||||
let _message = websocket.next().await.unwrap().unwrap();
|
||||
// 透明代理:缺官方必需字段的 delta 事件不再被丢弃,原样转发
|
||||
websocket
|
||||
.send(Message::Text(
|
||||
json!({
|
||||
|
||||
@@ -982,8 +982,7 @@ async fn websocket_pool_should_release_slot_when_client_drops_stream() {
|
||||
.contains("streaming has begun")
|
||||
);
|
||||
|
||||
// 客户端断开:drop stream → rx 被 drop → tx.closed() 完成 →
|
||||
// 代理丢弃上游连接并释放 slot(不再等 idle 超时)
|
||||
// 客户端丢弃响应流会触发上游连接关闭,池槽位在空闲超时前释放
|
||||
drop(stream);
|
||||
tokio::time::sleep(Duration::from_millis(200)).await;
|
||||
|
||||
|
||||
@@ -525,24 +525,7 @@ pub(super) fn map_transport_error_with_state(
|
||||
allow_explicit_replay: bool,
|
||||
) -> ProviderError {
|
||||
let transport_kind = error.kind();
|
||||
let kind = match transport_kind {
|
||||
GrokInferenceTransportErrorKind::InvalidRequest => ProviderErrorKind::InvalidRequest,
|
||||
GrokInferenceTransportErrorKind::Unsupported => ProviderErrorKind::Unsupported,
|
||||
GrokInferenceTransportErrorKind::Unauthorized => ProviderErrorKind::Unauthorized,
|
||||
GrokInferenceTransportErrorKind::PermissionDenied
|
||||
| GrokInferenceTransportErrorKind::ModelAccessDenied
|
||||
| GrokInferenceTransportErrorKind::PaymentRequired
|
||||
| GrokInferenceTransportErrorKind::SafetyRejected => ProviderErrorKind::PermissionDenied,
|
||||
GrokInferenceTransportErrorKind::RateLimited => ProviderErrorKind::RateLimited,
|
||||
GrokInferenceTransportErrorKind::QuotaExhausted
|
||||
| GrokInferenceTransportErrorKind::FreeQuotaExhausted
|
||||
| GrokInferenceTransportErrorKind::ModelQuotaExhausted => ProviderErrorKind::QuotaExhausted,
|
||||
GrokInferenceTransportErrorKind::Timeout => ProviderErrorKind::Timeout,
|
||||
GrokInferenceTransportErrorKind::Transport => ProviderErrorKind::Transport,
|
||||
GrokInferenceTransportErrorKind::Protocol => ProviderErrorKind::Protocol,
|
||||
GrokInferenceTransportErrorKind::Unavailable => ProviderErrorKind::Unavailable,
|
||||
GrokInferenceTransportErrorKind::Cancelled => ProviderErrorKind::Cancelled,
|
||||
};
|
||||
let kind = transport_kind.provider_kind();
|
||||
let mut mapped = provider_error(
|
||||
kind,
|
||||
forced_send_state.unwrap_or_else(|| error.send_state()),
|
||||
@@ -579,14 +562,8 @@ pub(super) fn map_transport_error_with_state(
|
||||
mapped = mapped.with_client_visible_upstream_error(detail);
|
||||
}
|
||||
let diagnostic = error.diagnostic().cloned().unwrap_or_else(|| {
|
||||
let status = error
|
||||
.status()
|
||||
.map_or_else(|| "none".to_owned(), |value| value.to_string());
|
||||
ProviderDiagnostic::new(format!(
|
||||
"xAI upstream failure: kind={}, status={status}",
|
||||
kind.as_str()
|
||||
))
|
||||
.with_classification("upstream", "upstream_failure")
|
||||
ProviderDiagnostic::new(transport_kind.diagnostic_message())
|
||||
.with_classification("upstream", "upstream_failure")
|
||||
});
|
||||
mapped = mapped.with_diagnostic(diagnostic);
|
||||
if error.requires_credential_recovery() {
|
||||
|
||||
@@ -4,7 +4,8 @@ use std::collections::{BTreeMap, BTreeSet};
|
||||
|
||||
use gateway_core::engine::provider::NativeResponseTranslator;
|
||||
use gateway_core::error::{
|
||||
ClientVisibleUpstreamError, OpaqueUpstreamValue, ProviderError, ProviderErrorKind,
|
||||
ClientVisibleUpstreamError, OpaqueUpstreamValue, ProviderDiagnostic, ProviderError,
|
||||
ProviderErrorKind,
|
||||
};
|
||||
use gateway_core::event::{
|
||||
ContentItem, ContentKind, FinishReason, GatewayEvent, ProtocolWireEvent, ProviderEvent,
|
||||
@@ -20,6 +21,7 @@ use gateway_protocol::openai::events::{TokenUsage, billable_usage_is_complete, e
|
||||
use gateway_protocol::openai::sse::{SseEvent, SseEventDecoder};
|
||||
use serde_json::Value;
|
||||
|
||||
use super::GrokInferenceTransportErrorKind;
|
||||
use super::request::{GrokResponseTransform, GrokResponsesRequest};
|
||||
use super::upstream_error::{classify_grok_quota_failure, scrub_account_fingerprints};
|
||||
|
||||
@@ -1207,19 +1209,24 @@ fn upstream_event_error(value: &Value) -> ProviderError {
|
||||
.or_else(|| value.pointer("/response/error/type"))
|
||||
.and_then(Value::as_str);
|
||||
let message = upstream_error_field(value, "message");
|
||||
let kind = if classify_grok_quota_failure(code, error_type, message).is_some() {
|
||||
ProviderErrorKind::QuotaExhausted
|
||||
let kind = if let Some(quota) = classify_grok_quota_failure(code, error_type, message) {
|
||||
GrokInferenceTransportErrorKind::from_quota(quota)
|
||||
} else {
|
||||
match code {
|
||||
Some("invalid_request" | "invalid_prompt") => ProviderErrorKind::InvalidRequest,
|
||||
Some("unsupported" | "unsupported_feature") => ProviderErrorKind::Unsupported,
|
||||
Some("unauthorized" | "invalid_token") => ProviderErrorKind::Unauthorized,
|
||||
Some("permission_denied") => ProviderErrorKind::PermissionDenied,
|
||||
Some("rate_limit_exceeded") => ProviderErrorKind::RateLimited,
|
||||
_ => ProviderErrorKind::Unavailable,
|
||||
Some("invalid_request" | "invalid_prompt") => {
|
||||
GrokInferenceTransportErrorKind::InvalidRequest
|
||||
}
|
||||
Some("unsupported" | "unsupported_feature") => {
|
||||
GrokInferenceTransportErrorKind::Unsupported
|
||||
}
|
||||
Some("unauthorized" | "invalid_token") => GrokInferenceTransportErrorKind::Unauthorized,
|
||||
Some("permission_denied") => GrokInferenceTransportErrorKind::PermissionDenied,
|
||||
Some("rate_limit_exceeded") => GrokInferenceTransportErrorKind::RateLimited,
|
||||
_ => GrokInferenceTransportErrorKind::Unavailable,
|
||||
}
|
||||
};
|
||||
let mut error = ProviderError::new(kind, UpstreamSendState::Sent)
|
||||
let mut error = ProviderError::new(kind.provider_kind(), UpstreamSendState::Sent)
|
||||
.with_diagnostic(ProviderDiagnostic::new(kind.diagnostic_message()))
|
||||
.with_raw_upstream_error(gateway_core::error::RawUpstreamError::new(
|
||||
value.to_string(),
|
||||
))
|
||||
|
||||
@@ -9,13 +9,14 @@ use futures::Stream;
|
||||
use gateway_core::engine::middleware::MiddlewareHeader;
|
||||
use gateway_core::error::{
|
||||
ClientVisibleUpstreamError, ErrorSource, OpaqueUpstreamValue, ProviderDiagnostic,
|
||||
RawUpstreamError,
|
||||
ProviderErrorKind, RawUpstreamError,
|
||||
};
|
||||
use gateway_core::event::UpstreamHttpVersion;
|
||||
use gateway_core::upstream::UpstreamSendState;
|
||||
use url::Url;
|
||||
use zeroize::Zeroizing;
|
||||
|
||||
use super::upstream_error::GrokQuotaFailureKind;
|
||||
use super::{GrokHeader, GrokSessionBinding};
|
||||
|
||||
/// 交给注入的 HTTP SSE transport 的自持有请求
|
||||
@@ -352,6 +353,58 @@ pub enum GrokInferenceTransportErrorKind {
|
||||
Cancelled,
|
||||
}
|
||||
|
||||
impl GrokInferenceTransportErrorKind {
|
||||
pub(crate) const fn from_quota(failure: GrokQuotaFailureKind) -> Self {
|
||||
match failure {
|
||||
GrokQuotaFailureKind::Account => Self::QuotaExhausted,
|
||||
GrokQuotaFailureKind::FreeAccount => Self::FreeQuotaExhausted,
|
||||
GrokQuotaFailureKind::FreeModelUsage => Self::ModelQuotaExhausted,
|
||||
}
|
||||
}
|
||||
|
||||
pub(crate) const fn provider_kind(self) -> ProviderErrorKind {
|
||||
match self {
|
||||
Self::InvalidRequest => ProviderErrorKind::InvalidRequest,
|
||||
Self::Unsupported => ProviderErrorKind::Unsupported,
|
||||
Self::Unauthorized => ProviderErrorKind::Unauthorized,
|
||||
Self::PermissionDenied
|
||||
| Self::ModelAccessDenied
|
||||
| Self::PaymentRequired
|
||||
| Self::SafetyRejected => ProviderErrorKind::PermissionDenied,
|
||||
Self::RateLimited => ProviderErrorKind::RateLimited,
|
||||
Self::QuotaExhausted | Self::FreeQuotaExhausted | Self::ModelQuotaExhausted => {
|
||||
ProviderErrorKind::QuotaExhausted
|
||||
}
|
||||
Self::Timeout => ProviderErrorKind::Timeout,
|
||||
Self::Transport => ProviderErrorKind::Transport,
|
||||
Self::Protocol => ProviderErrorKind::Protocol,
|
||||
Self::Unavailable => ProviderErrorKind::Unavailable,
|
||||
Self::Cancelled => ProviderErrorKind::Cancelled,
|
||||
}
|
||||
}
|
||||
|
||||
pub(crate) const fn diagnostic_message(self) -> &'static str {
|
||||
match self {
|
||||
Self::InvalidRequest => "上游拒绝了请求参数",
|
||||
Self::Unsupported => "上游不支持此请求",
|
||||
Self::Unauthorized => "上游账号凭据无效",
|
||||
Self::PermissionDenied => "上游账号无权执行此请求",
|
||||
Self::ModelAccessDenied => "上游账号无权使用此模型",
|
||||
Self::PaymentRequired => "上游要求付费",
|
||||
Self::SafetyRejected => "请求被上游安全策略拦截",
|
||||
Self::RateLimited => "上游请求频率受限",
|
||||
Self::QuotaExhausted => "上游账号额度已用完",
|
||||
Self::FreeQuotaExhausted => "上游账号免费额度已用完",
|
||||
Self::ModelQuotaExhausted => "此模型的免费额度已用完",
|
||||
Self::Timeout => "上游响应超时",
|
||||
Self::Transport => "上游连接失败",
|
||||
Self::Protocol => "上游协议处理失败",
|
||||
Self::Unavailable => "上游服务暂不可用",
|
||||
Self::Cancelled => "请求已取消",
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// 推理 transport 失败,公开分类与受控上游详情分别承载
|
||||
#[derive(Clone)]
|
||||
pub struct GrokInferenceTransportError {
|
||||
|
||||
@@ -1156,18 +1156,28 @@ async fn classify_inference_status(
|
||||
if let Some(raw) = raw {
|
||||
error = error.with_raw_upstream_error(raw);
|
||||
}
|
||||
let diagnostic_code = if status == StatusCode::BAD_REQUEST && reasoning_decode_failed(&metadata)
|
||||
let (code, message) = if status == StatusCode::BAD_REQUEST && reasoning_decode_failed(&metadata)
|
||||
{
|
||||
"reasoning_decode_failed"
|
||||
("reasoning_decode_failed", "上游无法解码加密的推理内容")
|
||||
} else {
|
||||
body_failure.map_or("upstream_failure", GrokBodyFailure::marker)
|
||||
let message = match (body_failure, kind) {
|
||||
(
|
||||
Some(GrokBodyFailure::ModelCapacity),
|
||||
GrokInferenceTransportErrorKind::RateLimited,
|
||||
) => "上游模型容量不足",
|
||||
(
|
||||
Some(GrokBodyFailure::EmptyUpstream),
|
||||
GrokInferenceTransportErrorKind::Unavailable,
|
||||
) => "上游未返回模型响应",
|
||||
_ => kind.diagnostic_message(),
|
||||
};
|
||||
(
|
||||
body_failure.map_or("upstream_failure", GrokBodyFailure::marker),
|
||||
message,
|
||||
)
|
||||
};
|
||||
error = error.with_diagnostic(
|
||||
ProviderDiagnostic::new(format!(
|
||||
"xAI upstream rejected request: status={status_code}"
|
||||
))
|
||||
.with_classification("upstream", diagnostic_code),
|
||||
);
|
||||
error = error
|
||||
.with_diagnostic(ProviderDiagnostic::new(message).with_classification("upstream", code));
|
||||
error = error.with_upstream_failure_fields(gateway_core::upstream::UpstreamFailureFields {
|
||||
status: Some(status_code),
|
||||
code: metadata.original_code,
|
||||
@@ -1221,7 +1231,7 @@ enum GrokBodyFailure {
|
||||
impl GrokBodyFailure {
|
||||
fn transport_kind(self) -> GrokInferenceTransportErrorKind {
|
||||
match self {
|
||||
Self::Quota(failure) => quota_transport_error_kind(failure),
|
||||
Self::Quota(failure) => GrokInferenceTransportErrorKind::from_quota(failure),
|
||||
Self::Billing => GrokInferenceTransportErrorKind::PaymentRequired,
|
||||
Self::EmptyUpstream => GrokInferenceTransportErrorKind::Unavailable,
|
||||
Self::ModelCapacity | Self::RateLimit => GrokInferenceTransportErrorKind::RateLimited,
|
||||
@@ -1372,7 +1382,7 @@ fn first_string(object: &serde_json::Map<String, Value>, fields: &[&str]) -> Opt
|
||||
fn classify_payment_required(metadata: &InferenceErrorMetadata) -> GrokInferenceTransportErrorKind {
|
||||
quota_failure(metadata).map_or(
|
||||
GrokInferenceTransportErrorKind::PaymentRequired,
|
||||
quota_transport_error_kind,
|
||||
GrokInferenceTransportErrorKind::from_quota,
|
||||
)
|
||||
}
|
||||
|
||||
@@ -1392,7 +1402,7 @@ fn classify_forbidden(
|
||||
} else if let Some(failure) = body_failure {
|
||||
failure.transport_kind()
|
||||
} else if let Some(failure) = quota_failure(metadata) {
|
||||
quota_transport_error_kind(failure)
|
||||
GrokInferenceTransportErrorKind::from_quota(failure)
|
||||
} else if model_access_denied(metadata) {
|
||||
GrokInferenceTransportErrorKind::ModelAccessDenied
|
||||
} else {
|
||||
@@ -1405,7 +1415,7 @@ fn classify_too_many_requests(
|
||||
) -> GrokInferenceTransportErrorKind {
|
||||
quota_failure(metadata).map_or(
|
||||
GrokInferenceTransportErrorKind::RateLimited,
|
||||
quota_transport_error_kind,
|
||||
GrokInferenceTransportErrorKind::from_quota,
|
||||
)
|
||||
}
|
||||
|
||||
@@ -1441,16 +1451,6 @@ fn quota_failure(metadata: &InferenceErrorMetadata) -> Option<GrokQuotaFailureKi
|
||||
)
|
||||
}
|
||||
|
||||
fn quota_transport_error_kind(failure: GrokQuotaFailureKind) -> GrokInferenceTransportErrorKind {
|
||||
match failure {
|
||||
GrokQuotaFailureKind::Account => GrokInferenceTransportErrorKind::QuotaExhausted,
|
||||
GrokQuotaFailureKind::FreeAccount => GrokInferenceTransportErrorKind::FreeQuotaExhausted,
|
||||
GrokQuotaFailureKind::FreeModelUsage => {
|
||||
GrokInferenceTransportErrorKind::ModelQuotaExhausted
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn model_access_denied(metadata: &InferenceErrorMetadata) -> bool {
|
||||
metadata.message.as_deref().is_some_and(|message| {
|
||||
let message = message.to_ascii_lowercase();
|
||||
|
||||
@@ -403,18 +403,7 @@ async fn xai_admin_provider_restores_full_pending_envelope_and_binds_owner() {
|
||||
let flow_id = "pending-envelope";
|
||||
let owner_ref = admin_session_owner_ref("admin-owner");
|
||||
let payload = pending_payload(flow_id, &owner_ref);
|
||||
pending.insert(flow_id, owner_ref, payload.clone());
|
||||
|
||||
let mutation = payload
|
||||
.expose_to_provider()
|
||||
.get("mutation")
|
||||
.and_then(Value::as_object)
|
||||
.expect("pending mutation");
|
||||
assert_eq!(mutation.get("expected_config_revision"), None);
|
||||
assert_eq!(
|
||||
mutation.get("started_request_id").and_then(Value::as_str),
|
||||
Some("request-start")
|
||||
);
|
||||
pending.insert(flow_id, owner_ref, payload);
|
||||
|
||||
let wrong_owner = bundle
|
||||
.admin_provider()
|
||||
@@ -610,8 +599,6 @@ async fn xai_admin_provider_projects_cached_quota_models_and_canonical_export()
|
||||
assert_eq!(window_data["onDemandCapCents"], 500);
|
||||
assert_eq!(window_data["onDemandUsedCents"], 100);
|
||||
assert_eq!(window_data["prepaidBalanceCents"], -500);
|
||||
assert!(!window_data.contains_key("monthlyLimitCents"));
|
||||
assert!(!window_data.contains_key("includedUsedCents"));
|
||||
let models = admin
|
||||
.models(account.id(), false)
|
||||
.await
|
||||
|
||||
@@ -26,7 +26,7 @@ fn repository() -> (Arc<MemoryProviderAccountStore>, GrokCredentialRepository) {
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
async fn create_persists_plaintext_oauth_json_without_envelope_fields() {
|
||||
async fn create_persists_oauth_method_and_tokens_in_provider_json() {
|
||||
let (store, _) = repository();
|
||||
let input = create_input("plain", "subject-plain");
|
||||
seed_input(&store, &input).await.expect("create account");
|
||||
@@ -47,8 +47,6 @@ async fn create_persists_plaintext_oauth_json_without_envelope_fields() {
|
||||
object.get("refresh_token").and_then(|v| v.as_str()),
|
||||
Some("refresh-plain")
|
||||
);
|
||||
assert!(!object.contains_key("secret_envelope"));
|
||||
assert!(!object.contains_key("secret_key_id"));
|
||||
}
|
||||
|
||||
#[tokio::test]
|
||||
|
||||
@@ -159,8 +159,7 @@ impl GrokEndpointPolicy for CatalogExitPolicy {
|
||||
timeout: Option<Duration>,
|
||||
proxy: Option<&OutboundProxy>,
|
||||
) -> Result<reqwest::Client, GrokReqwestTransportBuildError> {
|
||||
// “直连”也终止于本地 sink,旧实现漏代理时不会触达真实上游
|
||||
// 显式代理分支仍使用生产构造器及官方 HTTPS/CONNECT 目标
|
||||
// 直连请求落到本地监听器,显式代理请求通过生产构造器连接 HTTPS 目标
|
||||
OfficialGrokEndpointPolicy
|
||||
.build_inference_client(timeout, Some(proxy.unwrap_or(&self.direct_sink)))
|
||||
}
|
||||
|
||||
@@ -1604,6 +1604,10 @@ fn decoder_should_classify_free_quota_failed_event() {
|
||||
.push(body.as_bytes())
|
||||
.expect_err("free quota failure must surface");
|
||||
|
||||
assert_eq!(
|
||||
error.diagnostic().unwrap().as_str(),
|
||||
"上游账号免费额度已用完"
|
||||
);
|
||||
assert_eq!(
|
||||
error.kind(),
|
||||
gateway_core::error::ProviderErrorKind::QuotaExhausted
|
||||
|
||||
@@ -405,7 +405,7 @@ async fn inference_proxy_client_is_built_once_for_concurrent_same_binding() {
|
||||
for task in tasks {
|
||||
assert!(task.await.unwrap().iter().all(Result::is_ok));
|
||||
}
|
||||
// 启动时的直连 client + 一个代理 client;不再先构建并丢弃另一个直连 client
|
||||
// 一个启动时创建的直连客户端和一个并发请求共用的代理客户端
|
||||
assert_eq!(builds.load(Ordering::SeqCst), 2);
|
||||
assert!(origin_server.received_requests().await.unwrap().is_empty());
|
||||
}
|
||||
@@ -918,6 +918,10 @@ async fn inference_transport_should_classify_free_usage_429_as_account_free_quot
|
||||
error.kind(),
|
||||
GrokInferenceTransportErrorKind::FreeQuotaExhausted
|
||||
);
|
||||
assert_eq!(
|
||||
error.diagnostic().unwrap().as_str(),
|
||||
"上游账号免费额度已用完"
|
||||
);
|
||||
assert_eq!(error.status(), Some(429));
|
||||
assert_eq!(
|
||||
error.upstream_code().map(|code| code.as_str()),
|
||||
|
||||
@@ -1097,7 +1097,7 @@ fn history_sanitizer_should_only_strip_known_grok_injection_sites() {
|
||||
.expect("history normalization");
|
||||
let body = Value::Object(encoded.body().clone());
|
||||
|
||||
// 工具 schema 里恰好叫 phase 的属性与语义 null 不再被误删
|
||||
// 工具 schema 内的属性名和 null 值属于用户数据
|
||||
assert_eq!(
|
||||
body.pointer("/input/0/tools/0/input_schema/properties/phase"),
|
||||
Some(&json!({"type": "string"}))
|
||||
@@ -1312,7 +1312,7 @@ fn unsupported_tools_should_be_filtered_with_their_orphaned_choice() {
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ambiguous_tool_contracts_should_fail_before_upstream_io() {
|
||||
fn invalid_responses_requests_report_the_offending_field() {
|
||||
for (body, field) in [
|
||||
(
|
||||
json!({"model": "client", "input": "x", "tools": [
|
||||
@@ -1339,33 +1339,34 @@ fn ambiguous_tool_contracts_should_fail_before_upstream_io() {
|
||||
json!({"model": "client", "input": [{"type": "compaction_trigger"}]}),
|
||||
"input",
|
||||
),
|
||||
(
|
||||
json!({"input": [{"type":"local_shell_call", "call_id":"call_shell",
|
||||
"action":{"type":"exec", "command":["pwd"]}}]}),
|
||||
"input",
|
||||
),
|
||||
(
|
||||
json!({"input": [{"type":"local_shell_call_output", "call_id":"call_shell", "output":"ok"}]}),
|
||||
"input",
|
||||
),
|
||||
(
|
||||
json!({"input":"hello", "response_format":{"type":"json_object"}}),
|
||||
"response_format",
|
||||
),
|
||||
(
|
||||
json!({"input":"hello", "reasoning_effort":"high"}),
|
||||
"reasoning_effort",
|
||||
),
|
||||
(
|
||||
json!({"input":"hello", "reasoningEffort":"high"}),
|
||||
"reasoningEffort",
|
||||
),
|
||||
] {
|
||||
let request = raw_request(body);
|
||||
assert_eq!(
|
||||
GrokResponsesRequest::encode(&request, "grok-4.5", &client_key())
|
||||
.expect_err("invalid tool contract"),
|
||||
GrokRequestEncodeError::InvalidRequestField { field }
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn retired_wire_formats_are_rejected_without_fallback() {
|
||||
for field in ["response_format", "reasoning_effort", "reasoningEffort"] {
|
||||
let mut body = json!({"input":"hello"});
|
||||
body[field] = json!("high");
|
||||
assert!(
|
||||
GrokResponsesRequest::encode(&raw_request(body), "grok-4.6", &client_key()).is_err()
|
||||
);
|
||||
}
|
||||
for kind in ["local_shell_call", "local_shell_call_output"] {
|
||||
assert!(
|
||||
GrokResponsesRequest::encode(
|
||||
&raw_request(json!({"input":[{"type":kind,"call_id":"old"}]})),
|
||||
"grok-4.6",
|
||||
&client_key()
|
||||
)
|
||||
.is_err()
|
||||
.expect_err("invalid Responses request"),
|
||||
GrokRequestEncodeError::InvalidRequestField { field },
|
||||
"{field}"
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,10 +1,8 @@
|
||||
# 数据库迁移
|
||||
|
||||
sqlx 在服务启动、监听请求之前按编号执行迁移,并把文件 checksum 记入 `_sqlx_migrations`。
|
||||
已应用迁移的字节与记录不一致时,服务会拒绝启动
|
||||
服务监听请求前,sqlx 按编号执行本目录的 SQL,并将文件校验和写入 `_sqlx_migrations`。已应用文件的校验和不匹配时,服务拒绝启动
|
||||
|
||||
迁移按递增编号组织,完整清单以本目录 SQL 文件和 `.frozen-sha256` 为准。
|
||||
业务状态与存储职责见[状态所有权](../../docs/architecture.md#8-状态所有权),离线恢复见[部署文档](../../deploy/README.md#人工恢复数据库)
|
||||
[状态所有权](../../docs/architecture.md#8-状态所有权) · [离线恢复](../../deploy/README.md#人工恢复数据库)
|
||||
|
||||
## 命名约定
|
||||
|
||||
@@ -15,7 +13,7 @@ sqlx 在服务启动、监听请求之前按编号执行迁移,并把文件 ch
|
||||
|
||||
## 冻结规则
|
||||
|
||||
- 同一大版本内,已合入 main 的迁移文件**按字节永久冻结**,包括注释和空白。schema 变更及错误修正都须新增编号迁移,使用 `alter` 或回填补偿;修改原文件会导致已部署实例重启时 checksum 失配,且没有自动恢复路径
|
||||
- 同一大版本内,合入 `main` 的迁移文件**按字节永久冻结**,包括注释和空白。修改 schema 或修正错误须追加编号迁移,使用 `alter` 或数据回填
|
||||
- 跨大版本不支持在线升级,目标版本必须使用全新数据目录部署;此时可将已完成升级的 schema 折叠为新的初始化基线
|
||||
- 支持连续升级的预发行线从首次发布起同样冻结迁移。alpha、beta、rc 到对应正式版必须保留
|
||||
已发布迁移的编号与字节;同一轮 exp 的后续发行也只能追加迁移。发布前以该发行线已发布版本
|
||||
@@ -30,7 +28,7 @@ cd backend/migrations
|
||||
sha256sum --check --strict .frozen-sha256
|
||||
```
|
||||
|
||||
遇到 checksum 不一致,先核对运行版本和文件来源;不要修改数据库中的 checksum 来绕过校验
|
||||
校验和不一致时无法自动恢复。核对运行版本与文件来源,不要改写数据库中的校验和
|
||||
|
||||
## 本地测试库
|
||||
|
||||
@@ -41,19 +39,13 @@ export CPR_TEST_DATABASE_URL='postgres://<user>:<password>@127.0.0.1:5432/<db>'
|
||||
export CPR_TEST_REDIS_URL='redis://:<password>@127.0.0.1:6379'
|
||||
```
|
||||
|
||||
插件 Runtime 的真实子进程与持久化测试优先使用 `CPR_PLUGIN_TEST_DATABASE_URL` 和
|
||||
`CPR_PLUGIN_TEST_REDIS_URL`。设置插件数据库变量时必须同时提供对应 Redis 变量;未设置插件数据库变量时,
|
||||
使用上述标准测试服务。两种配置遵守相同的密码与隔离要求;缺少服务时的跳过和 CI 失败规则也相同
|
||||
插件 Runtime 的真实子进程与持久化测试可使用专用的 `CPR_PLUGIN_TEST_DATABASE_URL`,此时须同时设置 `CPR_PLUGIN_TEST_REDIS_URL`。省略插件数据库 URL 时使用上面的测试服务
|
||||
|
||||
测试自建随机 schema / key 前缀做隔离,但仍应使用专用开发或测试实例,不要连接生产库。
|
||||
凭据从自己的部署配置或 CI Secret 中读取,不要粘贴未脱敏的 `docker inspect` 输出。
|
||||
环境变量未设置导致的跳过不算数据库测试通过
|
||||
使用专用开发或测试实例,测试通过随机 schema 和 Redis key 前缀隔离数据。凭据取自部署配置或 CI Secret,不要分享未脱敏的 `docker inspect` 输出
|
||||
|
||||
PostgreSQL 的临时 schema 测试连接使用异步提交,保留事务可见性、回滚和完整迁移检查
|
||||
需要验证数据库崩溃后的持久性时,使用独立数据库与生产连接配置,不复用这类 fixture
|
||||
|
||||
运行包含 `StoreBundle` 初始化的完整集成测试时,两条测试 URL 都须包含密码,原始密码须满足
|
||||
[Store 密码要求](../../deploy/README.md#手动安装),在测试 URL 中按 URL 规则编码。
|
||||
仅能连接数据库并不代表该初始化合同通过。专用服务使用对应测试密码,
|
||||
并在测试进程中清除 `CPR_DATABASE_URL`、`CPR_REDIS_URL`、`CPR_DATABASE_PASSWORD` 和
|
||||
`CPR_REDIS_PASSWORD`,避免启动配置被部署环境覆盖
|
||||
在测试进程中清除 `CPR_DATABASE_URL`、`CPR_REDIS_URL`、`CPR_DATABASE_PASSWORD` 和 `CPR_REDIS_PASSWORD`,避免部署环境覆盖测试配置
|
||||
|
||||
+53
-55
@@ -1,8 +1,6 @@
|
||||
# 部署与运维
|
||||
|
||||
首次安装可按 [快速开始](../README.md#快速开始) 操作。
|
||||
本文补充客户端配置、权限、备份和升级;部署命令从安装目录 `codex-proxy-rs/` 执行,
|
||||
其中 `deploy/` 存放 Compose 文件和配置,`.runtime/` 存放持久化数据
|
||||
首次安装见[快速开始](../README.md#快速开始)。部署命令在安装目录 `codex-proxy-rs/` 执行。`deploy/` 存放 Compose 文件和配置,`.runtime/` 存放持久化数据
|
||||
|
||||
| 任务 | 入口 |
|
||||
| --- | --- |
|
||||
@@ -14,8 +12,6 @@
|
||||
|
||||
## 配置归属
|
||||
|
||||
配置按职责保存,不都在 YAML 中:
|
||||
|
||||
| 位置 | 内容 | 修改方式 |
|
||||
| --- | --- | --- |
|
||||
| `deploy/config.yaml` | 监听、数据库/Redis 连接、部署凭据、时区、日志与可选内存分配策略等启动配置 | 从模板创建,已有部署合并修改,不覆盖原文件 |
|
||||
@@ -237,11 +233,29 @@ flowchart LR
|
||||
|
||||
网关端口默认只绑定本机;数据库和 Redis 不对公网开放。插件以网关同一系统身份运行,不能作为不可信代码沙箱
|
||||
|
||||
## 安装脚本选项
|
||||
|
||||
[一键安装](../README.md#快速开始)需要当前用户能访问 Docker,并可通过 `sudo` 或 root 设置目录权限。脚本会启动网关、PostgreSQL 和 Redis,首次安装完成后输出访问地址和管理员密码
|
||||
|
||||
运行 `bash install.sh` 时可设置以下环境变量:
|
||||
|
||||
| 变量 | 用途 | 默认值 |
|
||||
| --- | --- | --- |
|
||||
| `INSTALL_DIR` | 安装目录,建议使用绝对路径 | 当前目录下的 `codex-proxy-rs/` |
|
||||
| `CPR_RELEASE_TAG` | 指定发布标签 | 最新正式版本 |
|
||||
| `ADMIN_PASSWORD` | 管理员初始密码,至少 12 位,不含 `$` 或控制字符,不能使用常见弱口令 | 随机生成 |
|
||||
|
||||
例如,将服务安装到指定目录:
|
||||
|
||||
```bash
|
||||
INSTALL_DIR="$HOME/services/codex-proxy-rs" bash install.sh
|
||||
```
|
||||
|
||||
重复运行时使用同一安装目录。检测到 `deploy/config.yaml` 后,[脚本](install.sh)会保留现有配置与部署文件,忽略传入的管理员密码。版本升级见[镜像升级与源码构建](#镜像升级与源码构建)
|
||||
|
||||
## 手动安装
|
||||
|
||||
本节适用于 Linux amd64/arm64,需准备 Docker Engine、Docker Compose Plugin、curl 和 OpenSSL,
|
||||
并确保当前用户能访问 Docker、可通过 `sudo` 或 root 设置目录权限。一键安装入口见
|
||||
[快速开始](../README.md#一键安装),脚本会自动完成本节准备和服务启动
|
||||
Linux amd64/arm64 需要 Docker Engine、Docker Compose Plugin、curl 和 OpenSSL。当前用户须可访问 Docker,并能通过 `sudo` 或 root 设置目录权限
|
||||
|
||||
下载同一正式 Release 的部署文件并设置目录权限:
|
||||
|
||||
@@ -390,11 +404,9 @@ PostgreSQL/Redis 启动密码。日常校验使用 `config --quiet`
|
||||
|
||||
### 安装管理端应用
|
||||
|
||||
使用 Chrome、Edge 等支持 PWA 的浏览器访问管理端,可通过地址栏或浏览器菜单安装应用,安装后以独立窗口打开站点首页,沿用现有登录流程
|
||||
用 Chrome、Edge 等支持 PWA 的浏览器通过 HTTPS、`http://localhost` 或 `http://127.0.0.1` 访问管理端,从地址栏或浏览器菜单安装。入口是否显示取决于浏览器、访问交互及安装状态
|
||||
|
||||
首次在 Chrome 中安装时,系统标题栏可能显示应用名称。可用窗口右上角的标题栏按钮隐藏名称,隐藏后仍可拖动顶部空白区域移动窗口
|
||||
|
||||
安装入口要求 HTTPS,或本机的 `http://localhost`、`http://127.0.0.1`;普通 HTTP 局域网地址不满足条件。入口是否显示还取决于浏览器、访问交互及是否已安装。应用需要联网访问网关,不提供离线使用
|
||||
应用在独立窗口打开首页,须联网并按原流程登录。Chrome 窗口右上角可隐藏标题栏名称,顶部空白区域仍可拖动窗口
|
||||
|
||||
### 启动后的运行设置
|
||||
|
||||
@@ -405,7 +417,7 @@ PostgreSQL/Redis 启动密码。日常校验使用 `config --quiet`
|
||||
| 上游客户端身份 | “系统设置 → 上游配置 → 客户端身份”;Key 可按 Provider 覆盖,OpenAI Key 可独立配置[安装身份种子](../docs/api.md#key-客户端身份) |
|
||||
| 并发与排队 | “系统设置 → 运行设置”;Key 与账号分别设置排队容量和超时,可选择账号排队失败后换号,见[排队规则](../docs/api.md#并发与排队) |
|
||||
| 账号错误保护 | “系统设置 → 运行设置 → 错误保护”;默认关闭,按[自定义规则](../docs/api.md#账号错误保护)暂停账号调度 |
|
||||
| 全局请求位置 | “系统设置 → 上游配置 → 请求位置覆盖”;默认关闭,不从 YAML 导入 |
|
||||
| 全局请求位置 | “系统设置 → 上游配置 → 请求位置覆盖”,默认关闭 |
|
||||
| 代理位置 | “代理管理”;优先于全局位置,全局关闭时仍可独立生效 |
|
||||
|
||||
位置覆盖只影响 OpenAI 请求中受支持的位置与时区信息,不改变上下文日期、真实出口 IP、epoch 时间戳或系统时区。
|
||||
@@ -532,6 +544,9 @@ OpenAI Responses 上游 WebSocket 每 25 秒发送 Ping 保活,并回应上游
|
||||
修改上限对后续请求生效,已存在的连接继续计数;调低上限不会强制中断在途或绑定下游 WS 的连接。
|
||||
预算仅覆盖宿主原生 OpenAI Responses 连接,插件自建连接及其他 HTTP/WS 流量仍需预留容量
|
||||
|
||||
允许回退 HTTP 的 Responses 新链和持久化续接,由 `openai.ws_pool.fast_path_budget_ms` 控制前台等待上游 WS 建连的时长,默认 800 毫秒,可设为 1–15000 毫秒,重启应用后生效。
|
||||
超出预算时,本次请求走 HTTP/SSE,已启动的池化建连在后台继续。高延迟出口可调大该值,代价是仍需回退的请求会等得更久
|
||||
|
||||
未绑定活跃客户端 WS 的池化连接,归池后按 `openai.ws_pool.idle_timeout_ms` 计时,默认 `300000`(5 分钟,必须大于零)。
|
||||
Ping/Pong 不延长空闲期限;默认每 5 秒扫描,通常在空闲 300~305 秒开始回收,复用前也检查是否到期。
|
||||
关闭先停止复用,最多等待 1 秒发送 Close,随后终止并等待 socket 释放,容量在物理连接释放后才归还。
|
||||
@@ -598,7 +613,13 @@ Caddy 与应用同在容器网络时,将回源地址改为 `codex-proxy-rs:808
|
||||
|
||||
## 客户端配置
|
||||
|
||||
在管理端创建客户端密钥。Responses、Chat Completions 和 Anthropic Messages 客户端的 Base URL 见[客户端接入](../README.md#客户端接入);
|
||||
在管理端创建客户端密钥,将其填入 API 客户端的 API Key 字段。根据客户端自动追加的请求路径选择 Base URL,远程接入时将 `http://127.0.0.1:8080` 替换为网关的 HTTPS 地址
|
||||
|
||||
| 客户端自动追加的路径 | Base URL(本机部署) |
|
||||
| --- | --- |
|
||||
| OpenAI Responses `/responses`、Chat Completions `/chat/completions` | `http://127.0.0.1:8080/v1` |
|
||||
| Anthropic Messages `/v1/messages` | `http://127.0.0.1:8080` |
|
||||
|
||||
直接发送 HTTP 请求可参考 [Messages 示例](../docs/api.md#messages-请求)
|
||||
|
||||
使用 Codex 时,打开「使用密钥」,按操作系统复制 `config.toml`。
|
||||
@@ -683,14 +704,12 @@ Codex OAuth 账号的上游传输方式默认 WS;固定为 SSE 的账号不承
|
||||
|
||||
### 语音通话
|
||||
|
||||
Codex 0.164.0 的 `/voice` 通过 Provider 的 `base_url` 创建通话,控制连接另用顶层
|
||||
`experimental_realtime_ws_base_url`,不会自动继承 Provider 地址。两者应指向同一网关的 `/v1`,
|
||||
使用相同的代理密钥,并确保反向代理允许 WebSocket Upgrade。此设置独立于 Responses 的
|
||||
`supports_websockets` 开关
|
||||
使用 `/voice` 时,将 Provider 的 `base_url`(创建通话)和顶层 `experimental_realtime_ws_base_url`(控制连接)
|
||||
都设为同一网关的 `/v1`,使用同一把客户端密钥。若单独设置了 `experimental_realtime_webrtc_call_base_url`,也要指向该地址。
|
||||
顶层设置写在第一个 TOML 表之前,保存后完全退出并重启 Codex
|
||||
|
||||
已有配置需把 `experimental_realtime_ws_base_url` 合并到第一个 TOML 表之前,修改后完全退出并重启
|
||||
Codex。创建通话成功后仍报 `realtime websocket handshake failed` 时,先检查客户端日志中的
|
||||
`connecting realtime websocket` 是否指向网关;若仍为 `api.openai.com`,说明控制连接未经过代理
|
||||
反向代理须允许 WebSocket Upgrade,Responses 的 `supports_websockets` 开关不影响语音。
|
||||
若通话已创建但报 `realtime websocket handshake failed`,检查客户端日志中 `connecting realtime websocket` 的目标是否为网关
|
||||
|
||||
语音使用具备上游权限的 OAuth 账号,音频流由客户端与上游直接传输,路由与限制见
|
||||
[Codex Live 语音通话](../docs/api.md#codex-live-语音通话)
|
||||
@@ -881,15 +900,9 @@ OAuth 恢复开关为 `host.logging.oauth_recovery`,默认关闭,与普通
|
||||
|
||||
## 密码语义
|
||||
|
||||
- `admin.default_password` 只在首次创建管理员时使用
|
||||
- 已有管理员在「系统设置 → 安全与访问 → 管理员密码」修改登录密码,需要验证当前密码;修改后所有管理员会话失效,使用新密码重新登录
|
||||
- PostgreSQL 官方镜像只在空数据目录初始化时使用 `database.password`
|
||||
- Redis 在每次容器创建时使用 `redis.password`
|
||||
|
||||
已有 PostgreSQL 数据目录后,直接修改 `database.password` 不会修改数据库用户密码,只会导致
|
||||
应用无法连接。轮换时必须先在 PostgreSQL 中修改用户密码,再同步更新 `config.yaml`。Redis
|
||||
密码变更后需要用新配置重新创建 Redis 和应用容器,不需要删除 Redis 数据目录。
|
||||
安排维护窗口,避免应用和 Redis 在过渡期间使用不同密码
|
||||
- **管理员**:`admin.default_password` 只在创建首个管理员时使用。已有管理员在「系统设置 → 安全与访问 → 管理员密码」验证当前密码后修改,所有管理员会话须重新登录
|
||||
- **PostgreSQL**:镜像只在空数据目录初始化时设置 `database.password`。轮换须先修改数据库用户密码,再同步更新 `config.yaml`,否则应用无法连接
|
||||
- **Redis**:容器创建时读取 `redis.password`。在维护窗口更新配置并重新创建 Redis 和应用容器,保留数据目录
|
||||
|
||||
## 镜像升级与源码构建
|
||||
|
||||
@@ -927,15 +940,13 @@ docker compose -f deploy/compose.yaml build codex-proxy-rs
|
||||
|
||||
### 升级前检查
|
||||
|
||||
- OpenAI 或 xAI 授权使用已保存代理,且代理的 WebSocket 连接上限非零:升级或回退后,重新发起尚未完成的授权,不复用旧回调或授权码。上限为 `0` 的在途授权和已保存的账号、凭据不受影响
|
||||
- Key 配置含 `installationId`:数据库自动转换为 `installationSeed`,API 调用方须使用[当前字段](../docs/api.md#key-客户端身份)。出站安装身份及关联的会话、缓存标识会变化,已有 WebSocket 精确续写需重发完整上下文
|
||||
- 数据库或备份含 `accountAutoFreeze*` 设置:升级后错误保护关闭、规则为空,需在管理端重新配置并启用;API 调用方使用 [`accountErrorProtection`](../docs/api.md#账号错误保护)。已有冻结到当前冷却截止后解除,账号并发上限保留,需调整时手动设置
|
||||
- OpenAI 或 xAI 的在途授权若因代理 WebSocket 连接上限与保存值不匹配而失败,须重新发起授权,使用新的回调和授权码
|
||||
- Key 配置含 `installationId` 时,迁移会将其转为 `installationSeed`。API 调用方使用[安装身份种子](../docs/api.md#key-客户端身份)。这些 Key 的安装身份、会话与缓存标识会变化,WebSocket 精确续写须重发完整上下文
|
||||
- 数据库或备份含 `accountAutoFreeze*` 设置时,迁移后错误保护默认关闭、规则为空。需要保护的部署须配置并启用 [`accountErrorProtection`](../docs/api.md#账号错误保护)。已有冻结到期解除,账号并发上限保留原值
|
||||
|
||||
### 版本命名与升级规则
|
||||
|
||||
管理端「系统更新」可临时选择通道检查更新,不保存选择,不会自动下载或安装。
|
||||
每次打开弹窗按当前运行版本匹配通道:正式版为 Stable,预发行按版本后缀匹配。
|
||||
升级并重启后按新运行版本匹配;侧栏更新提示始终使用当前运行通道。预发行编号 `N` 从 1 开始递增
|
||||
侧栏按运行通道提示更新。「系统更新」弹窗默认使用该通道,可临时切换,检查不会触发下载或安装。预发行编号 `N` 从 1 开始递增
|
||||
|
||||
| 通道 | 命名示例 | 接收的版本 |
|
||||
| --- | --- | --- |
|
||||
@@ -945,9 +956,7 @@ docker compose -f deploy/compose.yaml build codex-proxy-rs
|
||||
| Alpha | `X.Y.Z-alpha.N` | Alpha、Beta、RC、正式版 |
|
||||
| Exp | `X.Y.Z-exp.N` | 同一轮实验中编号更高的 exp,仅实验实例可选 |
|
||||
|
||||
普通通道在同一大版本内持续接收更高版本,包括后续小版本和补丁版本的预发行。
|
||||
切换通道不会降级,Stable 候选也必须高于当前运行版本。
|
||||
下载、安装或待重启期间不能切换通道
|
||||
普通通道只接收同一大版本内高于运行版本的候选,包括表中允许的小版本和补丁预发行。下载、安装或待重启期间不能切换通道
|
||||
|
||||
更新器读取更新仓库 `main` 分支的 `release/version.yaml`。`version` 是源码构建版本,只有 `published` 中当前大版本和通道对应的版本才参与更新检查
|
||||
|
||||
@@ -960,10 +969,7 @@ docker compose -f deploy/compose.yaml build codex-proxy-rs
|
||||
exp 不进入正式版、alpha、beta 或 rc,普通实例也不能选择 Exp。
|
||||
从 exp 切换正式版时需先备份,在目标版本的独立数据库中迁移业务数据,不能直接复用或整库还原实验数据库
|
||||
|
||||
版本大小遵循 [SemVer](https://semver.org/),构建元数据 `+...` 不参与比较。未知预发行标识不提供在线更新。
|
||||
更新器先过滤不允许的目标,再选择版本最高的候选;其他通道或更高大版本领先,不影响当前发行线的更新。
|
||||
只有当前官方构建满足在线更新条件且存在允许安装的新版本时,才返回“有可用更新”。否则不显示更新标记、
|
||||
其他通道的版本及发布说明,手动检查显示“当前没有可用更新”。检查失败单独报告,不能当作没有更新
|
||||
更新器按 [SemVer](https://semver.org/) 选取允许的最高版本,忽略构建元数据 `+...`。未知预发行标识不支持在线更新。无候选时,手动检查显示“当前没有可用更新”,检查失败单独提示
|
||||
|
||||
alpha、beta、rc、exp 在 GitHub 标记为 Pre-release,不覆盖 GitHub Latest 或镜像 `latest`。
|
||||
升级前确认 PostgreSQL 满足目标版本的[部署要求](#部署结构)。可连续升级的发行线与约束见[迁移冻结规则](../backend/migrations/README.md#冻结规则)
|
||||
@@ -1031,27 +1037,21 @@ Release 必须提供当前 OS/架构的 `codex-proxy-rs_<version>_<os>_<arch>.ta
|
||||
| `plugins/official/plugin-release-manifest.json` | 随平台安装包和镜像分发,记录宿主版本、提交与支持的插件合同 |
|
||||
| 可执行文件同目录的 `plugins/official` | 随受信宿主发行物部署的只读目录,与二进制、Web 资源成套更新或恢复 |
|
||||
|
||||
- 下载更新时校验发行身份,插件合同不兼容不阻止安装。点击重启时检查已安装目标版本,列出不兼容插件的名称和原因;确认后重启,不兼容实例保持未启动,启用配置、绑定、密钥和私有数据保留
|
||||
- 回滚同样在重启前提示插件兼容风险,启动时重新检查,不改写持久启用配置。更新或回滚期间的并发配置变更会阻止切换,文件替换失败或取消时恢复整组文件
|
||||
- 更新和回滚时校验发行身份。插件版本不兼容仍可安装,重启前列出受影响的插件和原因,由管理员确认。并发配置变更阻止切换,文件替换失败或取消时恢复整组文件
|
||||
- 非空官方清单中的包经身份、平台和摘要校验后幂等导入;导入不确认信任、不创建配置、不启用,也不删除旧包。管理员确认信任后才执行默认配置流程;重复摘要保留首次安装出处
|
||||
- `sealed` 是构建封口标记,不是密码学签名。普通上传、URL 或 GitHub 安装不能获得 `builtin` 身份,独立教学示例也不例外
|
||||
|
||||
宿主启动检查覆盖管理页更新、Docker 与手工替换二进制。不兼容实例不挂载任何能力或故障占位,其额外认证和拦截停止生效,宿主原生认证继续执行。
|
||||
宿主范围或能力版本不匹配时,可在插件页确认风险后尝试本次启动;清单、RPC、平台或包完整性错误不能绕过。具体操作见[插件故障处理](../docs/plugins.md#故障处理)
|
||||
所有部署在启动时检查插件兼容性。不兼容实例保持未启动,保留配置、绑定、密钥和私有数据。原生认证继续执行,插件提供的认证和拦截不生效。可确认的版本风险与须更换包的错误见[插件故障处理](../docs/plugins.md#故障处理)
|
||||
|
||||
部署须保留完整的二进制、Web 资源与官方插件目录;不要手动修改制品元数据或迁移 checksum 绕过校验。
|
||||
插件安装包必须匹配宿主 OS 和架构,部署前需验证目标平台的插件运行与上游调用,不能只以打包成功判断可用
|
||||
|
||||
## 备份与恢复
|
||||
|
||||
管理端 S3/R2 提供业务备份;需要完整请求历史时,另做 PostgreSQL 整库备份或基础备份与 WAL 归档
|
||||
|
||||
不要在 PostgreSQL 写入期间直接复制数据目录作为一致性备份
|
||||
|
||||
| 需要保留的内容 | 备份方式 |
|
||||
| --- | --- |
|
||||
| 账号、Key、设置、插件、已用额度与用量汇总 | 管理端 S3/R2 业务备份 |
|
||||
| 完整请求、诊断和审计历史 | 独立整库备份,或停库后备份 `.runtime/postgres` |
|
||||
| 完整请求、诊断和审计历史 | PostgreSQL 整库备份、基础备份与 WAL 归档,或停库后备份 `.runtime/postgres` |
|
||||
| 部署配置与凭据 | 单独备份 `deploy/config.yaml` 及 Compose 自定义配置 |
|
||||
| 应用日志与已启用的 OAuth 恢复记录 | 单独备份 `.runtime/logs`,不包含在数据库归档中 |
|
||||
| 会话锚点与节点运行文件 | 按需备份 `.runtime/data` |
|
||||
@@ -1064,9 +1064,7 @@ OpenAI 主动额度重置卡及消费结果由上游持有,不属于本地备
|
||||
### 备份内容与限制
|
||||
|
||||
业务归档为 `.sql.gz`,保留完整数据库结构和迁移记录,但不包含请求明细、诊断与审计日志、
|
||||
逐请求费用去重记录和可重建的统计明细。Key 当前日、周的边界与已用额度独立保留。
|
||||
恢复后,已有窗口可继续使用;更改边界时不能重算恢复前的消费,以恢复后开始的新周期接续即可。
|
||||
从未记录费用历史完整范围的版本升级时,宿主以库中最早留存的费用判断可重算范围;没有费用事件时采用升级时间
|
||||
逐请求费用去重记录和可重建的统计明细。归档保留 Key 当前日、周的窗口边界与已用额度。恢复后可沿用原窗口,更改边界须从恢复后的新周期开始
|
||||
|
||||
原生用量按 UTC 小时保留全局请求数、成功/失败数、Token 和实际费用,每小时至多一行;
|
||||
插件维护的用量贡献按其原维度保留。原生汇总只覆盖备份快照中已发布且尚未被历史清理撤销的统计,
|
||||
|
||||
@@ -85,11 +85,12 @@ openai:
|
||||
residency: us
|
||||
# 账号路由参考值:us、us_cr
|
||||
account_routing_override: null
|
||||
# 可选:完整的 Responses 上游 WS 池配置;省略整段使用以下默认值。
|
||||
# Responses 上游 WS 池配置,可单独覆盖下列默认值
|
||||
# ws_pool:
|
||||
# enabled: true
|
||||
# max_age_ms: 3300000
|
||||
# max_connecting: 8
|
||||
# fast_path_budget_ms: 800 # 回退 HTTP 前等待 WS 建连的时长,范围 1–15000 毫秒
|
||||
# idle_timeout_ms: 300000 # 仅回收未绑定活跃客户端 WS 的空闲连接,必须大于零。
|
||||
# stream_idle_timeout_ms: 300000
|
||||
|
||||
|
||||
+61
-72
@@ -1,8 +1,6 @@
|
||||
# Codex Proxy RS 接口
|
||||
|
||||
本文描述当前源码的公开 HTTP 合同,路由以 `backend/crates/gateway-api/src` 中的 router 为准
|
||||
|
||||
配置客户端见[部署文档](../deploy/README.md#客户端配置),内部职责见[系统架构](architecture.md),部署实例的功能以实际运行版本和 revision 为准
|
||||
公开 HTTP 路由位于 `backend/crates/gateway-api/src`。客户端接入见[部署文档](../deploy/README.md#客户端配置),模块职责见[系统架构](architecture.md)
|
||||
|
||||
| 查找内容 | 入口 |
|
||||
| --- | --- |
|
||||
@@ -26,8 +24,7 @@
|
||||
Authorization: Bearer sk_...
|
||||
```
|
||||
|
||||
自动生成的 Key 保持 `sk_` 格式;迁入的自定义 Key 使用保存时的原值,不限制前缀或固定长度。
|
||||
无论格式如何,只有已保存且启用的 Client Key 能通过鉴权
|
||||
自动生成的 Key 以 `sk_` 开头,自定义 Key 按原值鉴权,无固定前缀或长度。仅已保存且启用的 Key 有效
|
||||
|
||||
`/v1/messages`、`/v1/messages/count_tokens`、`/v1/models` 和 `/v1/models/{model_id}` 也接受 `x-api-key: <Client Key>`。
|
||||
同时提供两个认证头时优先使用 `Authorization`;客户端提交的是网关 Client Key,上游密钥由选中的账号提供
|
||||
@@ -55,6 +52,10 @@ Client Key 通过账号分组限定路由范围:未绑定分组时可使用全
|
||||
`codex_python_sdk`、`codex-app-server`、`codex-app-server-sdk` 与 `codex_mcp_server`
|
||||
名称按完整标识匹配且不区分大小写,括号后缀中的应用或 SDK 版本不能替代 Core 版本
|
||||
|
||||
TUI 连接共享 App Server 时,User-Agent 可以是 `Codex Desktop/<Core 版本> … (codex-tui; <TUI 版本>)`。
|
||||
这种请求按 CLI 门槛检查前缀中的 Core 版本,`version` 头可以省略或与 Core 版本相同。
|
||||
若该头提供不同的值,或 UA 另含 Desktop 应用版本后缀,则按 Desktop 规则校验
|
||||
|
||||
Desktop 应用版本优先取 `version` 头,未提供时取 User-Agent 中的 `(Codex Desktop; <版本>)`。
|
||||
ChatGPT 远程控制使用 `(codex_chatgpt_<平台>_remote; <版本>)` 形式的 User-Agent 后缀,已知平台包括
|
||||
`android` 和 `ios`。网关按该命名格式识别非空的平台名,后缀须完整,平台名和版本均不能含空白、括号或分号。
|
||||
@@ -168,7 +169,7 @@ Codex PAT 验证服务不可用和身份响应无效分别返回 `50301`、`5020
|
||||
`YYYY-MM-DD HH:mm:ss`,短时间、相对时间和图表标签按对应视图返回;缺失时间的展示字段为 `null` 或占位文本。
|
||||
调用者直接显示文本,使用原始时间点进行排序、比较和输入,不把展示文本转回请求时间
|
||||
|
||||
账号、模型用量和 Key 列表的最近使用时间由前端根据原始 RFC3339 时间点,通过 VueUse `useTimeAgoIntl` 按界面语言显示短相对时间,并随时间更新;悬停的完整日期仍使用后端 `lastUsedAtFullDisplay`,不使用浏览器本地时区重算
|
||||
账号、模型用量和 Key 列表使用 RFC3339 时间点 `lastUsedAt` 显示随时间更新的本地化相对时间,悬停时显示服务端返回的 `lastUsedAtFullDisplay`
|
||||
|
||||
Dashboard 的 `lastUsedRelative` 和账号额度的 `refreshedAtRelative` 由后端确定时间语义,
|
||||
分别以查询锚点和服务端当前时间计算,随接口刷新更新。前端只翻译分类与单位,不使用浏览器时钟或时区重算
|
||||
@@ -178,7 +179,7 @@ Dashboard 的 `lastUsedRelative` 和账号额度的 `refreshedAtRelative` 由后
|
||||
- `kind=elapsed` 包含整数 `value` 和 `unit=minute|hour|day`,分钟不足 60、小时不足 24,之后始终用天;数值向下取整
|
||||
- `kind=absolute` 的 `value` 是后端按部署 `host.timezone` 生成的完整日期文本,用于按整秒判断的未来时间点
|
||||
|
||||
原始 RFC3339 `lastUsedAt`、`quota.refreshedAt` 与兼容展示字段保持可用,不用于前端重新决定上述展示方式
|
||||
账号额度的原始刷新时间为 RFC3339 字段 `quota.refreshedAt`
|
||||
|
||||
账号冷却返回 RFC3339 `rateLimitedUntil` 和 `rateLimitRecoveryDisplay`,后者包含剩余时长、
|
||||
到期时间或等待恢复探测的提示,随账号数据刷新;前端不解析展示文本或自行计算恢复提示
|
||||
@@ -302,9 +303,8 @@ print(completion.choices[0].message.content)
|
||||
`logit_bias` 和 `prediction` 没有对应的 Responses 控制语义,接受后忽略,不保证生效。
|
||||
消息的 `reasoning_content` 和 `reasoning` 作为辅助历史忽略,不转为用户正文
|
||||
|
||||
本地保留以下限制:`n` 只能为 `1`,`store` 和 `background` 只能为 `false`,
|
||||
`modalities` 只能为 `["text"]`,旧式 `functions` 只能为空数组;这些字段也可省略或为 `null`。
|
||||
非空旧式函数定义、`function_call`、旧式 `function` 角色、音频输出以及无法映射的内容类型会被拒绝。
|
||||
`n`、`store`、`background`、`modalities` 和 `functions` 可省略或为 `null`。非空值仅接受 `n: 1`、`store: false`、`background: false`、`modalities: ["text"]` 和 `functions: []`。
|
||||
网关拒绝 `function_call`、`function` 消息角色、音频输出和无法映射的内容类型。
|
||||
入口不接收 `input`、`previous_response_id` 或 `conversation`;需要服务端续接时使用 `/v1/responses`
|
||||
|
||||
未知客户端附加字段在协议包装对象中忽略,不据名称自动转交 Responses;schema、metadata、工具参数和
|
||||
@@ -351,11 +351,10 @@ Responses 上游使用 `$.input`,Messages 上游使用 `$.messages`
|
||||
转向 OpenAI Responses 上游时,`max_tokens` 仍为入站必填字段,但不限制实际输出。
|
||||
消息角色为 `user`、`assistant` 或 `system`,`content` 为字符串或内容块数组;初始系统指令放在顶层 `system`,
|
||||
会话中的 `system` 消息保留其位置,具体模型支持情况由上游校验。
|
||||
`stream` 缺省或 `false` 返回 JSON,`true` 返回 SSE。每轮由客户端携带所需的完整上下文。Claude Code 用 `--resume` 恢复本地会话后,仍通过 `messages` 发送上下文;网关不缓存对话正文用于下一轮。
|
||||
Messages 没有服务端历史续接或 WebSocket 入口
|
||||
`stream` 缺省或为 `false` 时返回 JSON,`true` 返回 SSE。每轮须通过 `messages` 发送完整上下文,包括 Claude Code 用 `--resume` 恢复的本地会话。此入口不支持服务端续接或 WebSocket
|
||||
|
||||
Messages 生成请求通过 OpenAI Provider 选号时,优先使用 `x-claude-code-session-id` 识别 Claude Code 会话,
|
||||
缺少有效头部时读取 `metadata.user_id` JSON 字符串中的 `session_id` 或旧格式 `_session_<id>` 后缀。
|
||||
缺少有效头部时,从 `metadata.user_id` 的 JSON 字符串读取 `session_id`,或读取字符串的 `_session_<id>` 后缀(此处 ID 只接受十六进制字符与连字符)。
|
||||
会话标识最长 256 字节,不接受控制字符;普通用户标识和对话内容不用于绑定账号。
|
||||
同一 Client Key 下的会话沿用[账号亲和与换号](#账号亲和与换号)设置,转向 Responses 上游时也适用
|
||||
|
||||
@@ -652,7 +651,8 @@ OAuth 账号默认 `prefer_websocket`,客户端使用 HTTP/SSE 时仍可能选
|
||||
客户端可跳过预热继续正式请求,外部插件 adapter 按各自的协议能力处理
|
||||
|
||||
OpenAI Responses 上游 WS 按握手响应头 `x-codex-websocket-max-message-bytes` 声明的上限,
|
||||
检查最终 `response.create` 文本的 UTF-8 字节数。超过上限时,新链、持久化续接和未知外部 previous ID
|
||||
检查最终 `response.create` 文本的 UTF-8 字节数。允许发送的文本超过 1 MiB 时,每 1 MiB 分一帧,接收方仍收到一条消息。
|
||||
超过握手声明的消息上限时,新链、持久化续接和未知外部 previous ID
|
||||
在上传正文前改用 HTTP/SSE;等于上限仍可发送。OAuth 和 API Key 账号、HTTP 和 WS 入站均适用。
|
||||
该上限只属于当前上游连接;响应头缺失或无效时不预判超限。显式 warmup 保持 WS 合同,超限时
|
||||
返回 `websocket_message_too_large`,不重复发送或改用 HTTP
|
||||
@@ -667,19 +667,14 @@ OpenAI Responses 上游 WS 按握手响应头 `x-codex-websocket-max-message-byt
|
||||
此规则适用于所有客户端。下一步请求应在新连接上发送完整输入,省略 `previous_response_id`。
|
||||
已接收的后续请求按序处理,若增量先到,仍按上述 400 合同恢复。启用 WS 帧中间件时保留连接
|
||||
|
||||
已建立模型执行的 HTTP 响应(生成请求、Messages 输入计数、Images 和 Search)按以下规则返回关联 ID:
|
||||
`x-gateway-request-id` 为模型执行 ID;`x-request-id` 保留有效上游值,只有上游
|
||||
`x-oai-request-id` 时复用其值,没有上游 ID 时使用模型执行 ID。`x-oai-request-id` 不是必需字段,
|
||||
也不要求客户端识别它;OpenAI 与 xAI 路由使用相同规则。失败响应的关联 ID 不采用会话 opening ID,
|
||||
错误正文读取失败时仍返回已知上游 ID;已采集的 turn state 等允许的会话头继续按原合同交付。
|
||||
尚未建立执行的入口拒绝继续使用 middleware 的入口关联
|
||||
生成请求、Messages 输入计数、Images 和 Search 的 HTTP 响应在建立模型执行后返回两个关联 ID,OpenAI 与 xAI 规则相同:
|
||||
|
||||
WebSocket 在尚未交付上游业务事件时合成的错误,除下述容量恢复合同外,保留已确认的失败状态,
|
||||
以及 Provider 提取的结构化 message/type/code;没有结构化错误时使用稳定安全文案,不把原始
|
||||
HTML 或截断正文当作 message。
|
||||
合成错误自身的 `headers` 携带允许下发的响应头:优先保留实际失败的上游 request ID,无上游 ID 时
|
||||
提供网关关联 ID,并用 `x-gateway-request-id` 独立标识网关请求。除下述客户端错误兼容与原生续写额度恢复外,
|
||||
已经取得的原始上游错误帧不重写
|
||||
- `x-gateway-request-id` 为模型执行 ID
|
||||
- `x-request-id` 优先取有效的上游同名头,其次取上游 `x-oai-request-id`,最后取模型执行 ID
|
||||
|
||||
错误正文读取失败时仍返回已知上游 ID 与允许下发的会话头(如 turn state)。只有在建立执行前拒绝请求时才使用中间件的入口关联
|
||||
|
||||
WebSocket 在交付业务事件前合成的错误保留已确认的失败状态和结构化 `message/type/code`,容量恢复按[重试规则](#容量拒绝与重试)处理。缺少结构化错误时使用安全提示。错误的 `headers` 携带允许下发的响应头,优先返回失败的上游 request ID,缺失时使用网关关联 ID。`x-gateway-request-id` 单独标识网关请求
|
||||
|
||||
### 模型目录
|
||||
|
||||
@@ -721,11 +716,8 @@ OpenAI 聚合当前 Key 范围内合格 OAuth 和 API Key 账号的目录。每
|
||||
服务启动时批量恢复账号目录;目录读取只检查本地账号资格和 Client Key 范围,不等待上游查询。
|
||||
成功目录响应带 `Cache-Control: private, no-store`,不借用上游 ETag 标识经过选择/别名/聚合后的正文
|
||||
|
||||
`service_tiers` 的 `name` 用于生成 `/fast` 等命令,`id` 是请求使用的 `service_tier` 值,二者不能互换。
|
||||
上游未声明或明确返回空数组时不补档位,也不根据模型名推断 Fast。
|
||||
该合同对齐
|
||||
[官方 Codex 0.154.0 的模型元数据](https://github.com/openai/codex/blob/6b9826e3aa83b1a5947db50f4332cb9c65f1b340/codex-rs/protocol/src/openai_models.rs)
|
||||
与其动态服务档位命令;客户端需重新加载模型目录才能使用更新后的档位信息
|
||||
`service_tiers` 中的 `name` 用于生成 `/fast` 等命令,`id` 用作请求的 `service_tier` 值。
|
||||
上游未声明档位或返回空数组时,网关不补充档位。档位更新后,客户端需重新加载模型目录
|
||||
|
||||
Codex 专用目录中的 `context_window` 与 `max_context_window` 分别表示默认上下文窗口和客户端本地
|
||||
覆盖的上限。OpenAI Provider 原样保留上游对应字段,缺失与 `null` 不互相转换;网关不通过部署配置
|
||||
@@ -788,6 +780,9 @@ HTTP 瞬时建连失败(含 TLS 握手 EOF),或 WebSocket 新请求在发
|
||||
`turn_rate_limit_exceeded` 保留原始错误和 `Retry-After`,由客户端按自身重试预算等待。
|
||||
代理不因此写入账号冷却、换号或透明重试,其他会话仍可使用该账号
|
||||
|
||||
`/v1/responses` 流式请求尚未发出数据或心跳时,若上游 WS `error` 明确返回 400,
|
||||
且网关判定为普通请求参数错误,客户端收到 HTTP 400 和原始 `error` 对象。
|
||||
已发出数据或心跳时,同一错误通过 SSE `response.failed` 和 `[DONE]` 结束。
|
||||
上游 WS `error` 转为 SSE `response.failed` 时,事件级的有效 `Retry-After` 同时放入
|
||||
`response.error.headers`,供客户端读取;错误对象已有有效重试头时优先保留
|
||||
|
||||
@@ -1143,12 +1138,12 @@ call 与账号的绑定保存在网关进程内,未连接时一小时过期;
|
||||
普通业务请求和状态轮询不会续期。管理员访问凭据到期后,仍可通过续期 Cookie 恢复登录;续期成功会轮换两种凭据,
|
||||
并重新计算不活动期限,但不能超过登录时确定的最长有效期。访问凭据仍有效时,refresh 返回同一组凭据和期限。
|
||||
轮换后 30 秒内重试上一代续期凭据返回同一组新凭据;超出窗口再次使用已识别的上一代凭据会撤销该会话。
|
||||
续期已过期或会话已撤销时不会重新创建;未认证返回 `{ authenticated: false, session: null }`,不写 Cookie;依赖故障返回 503。
|
||||
续期过期或会话已撤销时返回未认证状态,不重建会话或写入 Cookie。依赖故障返回 503。
|
||||
退出可以只携带续期 Cookie,并清除两种 Cookie。Key 登录清除续期 Cookie,密钥身份会话保持固定期限。
|
||||
期限配置见[部署配置](../deploy/README.md#手动安装)
|
||||
|
||||
每次恢复密钥会话时重新确认 Key 存在且启用;停用或删除后会话失效,重新启用不会恢复已撤销会话。
|
||||
依赖不可用时返回 503,不返回已认证或假装未登录。预算耗尽不妨碍登录
|
||||
密钥校验依赖不可用时返回 503。预算耗尽不妨碍登录
|
||||
|
||||
密钥会话访问管理接口返回 403,不清除仍然有效的会话。
|
||||
浏览器会话不能替代 `/v1/*` 的 Client Key,Client Key 也不能替代浏览器会话
|
||||
@@ -1522,7 +1517,7 @@ API 的 `autoLocation` 默认为 `false`;开启时使用已检测位置,测
|
||||
导入请求可以携带顶层 `outboundProxyId`,在令牌交换前解析为默认出口;文件中显式的代理配置优先。
|
||||
文件及 AT/RT 导入从凭据交换到落库期间保护所选代理;此时修改、删除或写入测试结果返回 409,
|
||||
避免已轮换的凭据因代理状态变化而丢失。完成导入或请求取消后自动释放保护。
|
||||
OAuth 等待回调期间不持有保护;提交仍拒绝已删除或连接配置改变的代理
|
||||
OAuth 等待回调期间允许修改代理。提交时若代理已删除、停用,或地址、WebSocket 连接上限与授权开始时不匹配,须使用有效代理重新发起授权
|
||||
|
||||
### 账号连接测试 SSE
|
||||
|
||||
@@ -1796,7 +1791,7 @@ OpenAI 授权码交换与令牌刷新请求的连接超时为 30 秒,单次上
|
||||
`quota_exhausted`。额度观测不会清除凭据过期、无效或封禁事实;这些事实统一投影为 `error`,并由
|
||||
`errorReason` 区分。额度接口的 401/403 也不足以判定 refresh token 永久失效,credential 终态只由
|
||||
OAuth refresh 的明确永久错误写入
|
||||
- xAI 额度百分比只读取 `creditUsagePercent`,缺失时保持未知,不由旧月额度与用量计算。
|
||||
- xAI 额度百分比取自 `creditUsagePercent`,缺失时为未知。
|
||||
预付余额保留上游账本符号,非零余额及剩余按量额度可独立证明可用;窗口已过期或缺少可用证据时,
|
||||
不凭旧快照恢复账号
|
||||
- 正常 Responses 请求会解析上游响应的 rate-limit headers,合并进同一 quota 快照并同步状态。Free、
|
||||
@@ -2059,15 +2054,14 @@ OpenAI Key 的 `installationSeed` 接受带连字符的 UUID,保存时规范
|
||||
- 种子不发送给上游,也不改写账号凭据;更改或清除种子使生效身份变化时,WebSocket 精确续写须重发完整上下文
|
||||
|
||||
兼容字段 `openaiClientProfileOverride` 和 `xaiClientProfileOverride` 分别对应上述映射中的 `openai`、`xai`。
|
||||
创建时省略或 `null` 表示无覆盖;更新时省略保留、`null` 清除。与通用字段同时提交时必须一致,否则拒绝整个请求;
|
||||
响应中的兼容字段从同一映射派生,不是第二份配置
|
||||
创建时省略或为 `null` 表示无覆盖。更新时省略保留,`null` 清除。与通用字段同时提交时须一致,否则整次请求被拒绝
|
||||
|
||||
### 名称与密钥值
|
||||
|
||||
密钥列表的 `search` 仅匹配名称和标签,不匹配密钥值或可见前缀;搜索不区分大小写,使用字面量包含匹配,`%`、`_` 和 `\` 按普通字符处理。
|
||||
创建和更新时去除名称首尾空白,并按忽略大小写、首尾空格的名称查重,重复返回 `409`。
|
||||
更新排除当前记录,并发写入同样执行查重;失败不会留下审计或配置版本变更。
|
||||
历史重名数据不自动改名,已有凭据继续有效;再次保存时需使用未被其他密钥占用的名称
|
||||
已有同名 Key 的凭据有效,编辑时须使用未被其他 Key 占用的名称
|
||||
|
||||
`customKey` 仅用于创建:省略、`null` 或空字符串时继续自动生成;非空时按原值保存,不追加前缀、
|
||||
不截断、不修剪空白,也不要求固定长度。Key 须为 HTTP Bearer 可传输的非空可见 ASCII 字符,
|
||||
@@ -2384,7 +2378,8 @@ Chat Completions 和 Responses 通过原生 OpenAI Provider 选号时,缺少
|
||||
缺少必填系数、系数为 `null`、未知字段及无效数值均返回 `422`,不写入配置。读取设置额外返回只读
|
||||
`smartSchedulingDefaults`,内容为上述默认对象,用于恢复默认与自定义状态比较,不可提交到更新接口
|
||||
|
||||
`resetWeight` 控制重置分在总评分中的比重。`resetWindowWeights` 中的 `fiveHour`、`weekly`、`monthly` 分别表示 5 小时、周和月的相对系数。三项均为 0~10、最多一位小数。默认均为 0,旧配置省略整个字段时也取 0;全部为 0 时不计重置分。设为 `{"fiveHour":0,"weekly":1,"monthly":0}` 可只按周重置评分。只计算账号通用窗口,未知、缺失或已过期的周期贡献为零
|
||||
`resetWeight` 控制重置分在总评分中的比重。`resetWindowWeights` 的 `fiveHour`、`weekly`、`monthly` 分别是 5 小时、周和月的相对系数,取值为 0~10,最多一位小数。省略整个字段时三项均为 0。
|
||||
全部为 0 时不计重置分。设为 `{"fiveHour":0,"weekly":1,"monthly":0}` 可只按周重置评分。只计算账号通用窗口,未知、缺失或已过期的周期贡献为零
|
||||
|
||||
`queueWeight` 只在没有可立即使用的账号、需要选择等待队列时参与评分,越大越偏向等待人数少的账号。
|
||||
设为 `0` 时沿用最短队列规则;启用后结合其余五项评分选择队列。队列人数限于当前进程,只有开启账号排队才会生效,
|
||||
@@ -2459,16 +2454,14 @@ models.dev 同步只导入可表示为当前文本 Token 计价的 OpenAI/xAI
|
||||
更新时省略某项保留原值,对象替换该项,`null` 删除显式选择并使用 Provider 默认值;不清除其他 Provider 的配置。
|
||||
配置内容由对应 Provider 校验,不包含账号凭据。Key 可通过 `providerRequestProfileOverrides` 整体覆盖所属 Provider 的选择
|
||||
|
||||
`openaiClientProfile` 与 `xaiClientProfile` 是同一映射的兼容字段:省略保留,不能显式提交 `null`;
|
||||
与通用字段同时提供时必须一致,否则整次更新拒绝。读取响应从映射派生这两个字段,不维护平行状态
|
||||
`openaiClientProfile` 与 `xaiClientProfile` 读写同一映射中的对应项。省略保留,显式提交 `null` 或与通用字段冲突时拒绝整次更新
|
||||
|
||||
直接读取 `openai` 或 `xai` 的选项与预览。OpenAI 选项返回六个 `presets` 与 `maxVersionLag`,xAI 返回 `defaults`;
|
||||
响应均包含 `globalConfiguration`
|
||||
|
||||
### OpenAI 上游客户端身份
|
||||
|
||||
`openaiClientProfile` 保存通用选择,首次默认 `MacOS · Desktop · 自动最新`。
|
||||
兼容字段的更新语义见上节。初始化不读取 YAML 身份字段。
|
||||
OpenAI 通用身份默认使用 `MacOS · Desktop · 自动最新`。
|
||||
该配置作用于 Client Key 的 OpenAI 模型请求,适用于 HTTP/SSE、WebSocket、Images 和 Search,
|
||||
也用于账号模型目录的后台发现、手动刷新、导出及定时预热;下次执行时采用当前全局选择,不使用单个 Key 的覆盖。
|
||||
不改变 xAI、入站客户端版本门禁、账号认证或后台 Desktop 专属操作
|
||||
@@ -2537,9 +2530,7 @@ WebSocket 精确续写沿用所属连接;安装身份配置与变更限制见
|
||||
|
||||
### xAI 上游客户端身份
|
||||
|
||||
`xaiClientProfile` 保存 Grok CLI 的通用身份选择;首次使用内置 `grok-shell / headless / linux / x86_64`
|
||||
并采用自动更新版本。初始化不读取 YAML 身份字段,数据库已有选择时不覆盖。
|
||||
更新设置省略该字段保留现值,不能提交 `null`
|
||||
Grok CLI 通用身份默认使用 `grok-shell / headless / linux / x86_64`,版本自动更新
|
||||
|
||||
| 字段 | 取值与语义 |
|
||||
| --- | --- |
|
||||
@@ -2742,8 +2733,7 @@ Dashboard 的当前账号摘要包含 `upstream`,结构与账号列表一致
|
||||
| `GET` | `/api/admin/operations/errors` | 运维错误分页列表 |
|
||||
| `GET` | `/api/admin/diagnostics/export` | 按 `requestId` 或 `errorId` 下载诊断 ZIP 附件 |
|
||||
|
||||
用量汇总的 `averageLatencyMsValue` 为可空毫秒数,前端按持续时长格式化;无延迟样本时为 `null`,
|
||||
`averageLatencyMs` 保留为兼容展示字段
|
||||
用量汇总的 `averageLatencyMsValue` 为平均延迟毫秒数,无样本时为 `null`。`averageLatencyMs` 提供格式化文本
|
||||
|
||||
### Dashboard 趋势指标
|
||||
|
||||
@@ -2781,7 +2771,7 @@ Dashboard 的 `capacityInfo` 统计普通容量,不含独立审批池;`maxCo
|
||||
Dashboard 的 `accountUsage[]` 返回稳定指标 `metric=requests|tokens`、可空原始数值 `metricValueRaw` 和
|
||||
可空 RFC3339 `lastUsedAt`;前端负责指标名称和数字本地化,相对时间按[页面时间合同](#页面时间合同)翻译 `lastUsedRelative`。
|
||||
`requests` 使用代表性额度窗口的本地请求数,`tokens` 使用今日 Token;未知数值为 `null`,零值保留 `0`。
|
||||
`metricLabel`、`metricValue` 和 `lastUsed` 保留给兼容调用方,当前管理端不解析或显示这些字段
|
||||
`metricLabel`、`metricValue` 和 `lastUsed` 提供兼容的展示文本
|
||||
|
||||
`accountUsage[].notes` 为账号当前备注,无备注时为 `null`
|
||||
|
||||
@@ -2795,7 +2785,7 @@ Dashboard 的 `accountUsage[]` 返回稳定指标 `metric=requests|tokens`、可
|
||||
Dashboard 默认 `period=today`,用量、诊断和错误查询默认 `period=7d`,范围参数遵循[页面时间合同](#页面时间合同)。
|
||||
Dashboard 返回原始 `asOf` 及 `asOfDisplay`,作为当前数据的查询锚点
|
||||
|
||||
请求明细列表接受 `currentPage`、`pageSize`、时间范围、`provider`、`clientApiKeyName`、`accountSearch`、`model` 和 `status`。
|
||||
请求明细列表接受 `currentPage`、`pageSize`、时间范围、`provider`、`clientApiKeyName`、`accountSearch`、`model`、`status` 和 `errorOrigin`。
|
||||
汇总和洞察接受时间范围与 `provider`;性能和成本另要求 `metric`,诊断另接受 `dimension`、`model` 和 `statusCode`。
|
||||
各接口拒绝未知参数,明细筛选不改变顶部统计范围
|
||||
|
||||
@@ -2805,7 +2795,11 @@ Dashboard 返回原始 `asOf` 及 `asOfDisplay`,作为当前数据的查询锚
|
||||
重试中间错误不改变请求最终分类;`logicalOutcome` 保留真实结果。状态筛选只影响明细列表,
|
||||
不改变顶部统计,独立运维事件仍通过 `/api/admin/operations/errors` 查询
|
||||
|
||||
请求列表的 `errorCode` / `errorMessage` 提供最终请求的错误码与错误信息,未记录时为 `null`。
|
||||
当 `status=error` 时,可传 `errorOrigin=upstream|proxy|connection|unknown` 筛选错误来源。
|
||||
省略时包含全部来源。筛选与列表、详情共用下述来源规则,并在统计总数和分页前与其他明细条件一同生效。
|
||||
其他状态携带 `errorOrigin` 或来源值无效时返回 `400`
|
||||
|
||||
请求列表的 `errorCode` 保留已记录的错误码,`errorMessage` 是最终失败的安全摘要,例如账号额度耗尽或模型容量不足。两者各自缺失时为 `null`。
|
||||
`clientStatusCode` / `upstreamStatusCode` 分别提供已记录的客户端与上游状态码,未记录时为 `null`。
|
||||
HTTP SSE 请求可能在返回 HTTP 200 后流内失败;WebSocket 已升级时,客户端错误状态码不代表 HTTP 握手状态或 WebSocket 关闭码。
|
||||
两侧状态码不互相替代,也不覆盖 `logicalOutcome`
|
||||
@@ -3067,30 +3061,25 @@ Provider metadata 分别保留 `requestedServiceTier` 与 `upstreamServiceTier`
|
||||
| `GET` | `/api/admin/system/restart/check` | 无 | 只读检查重启目标与启用插件 |
|
||||
| `POST` | `/api/admin/system/restart` | `{ confirmation? }` | 复核兼容性风险确认并重启,保留插件启用配置 |
|
||||
|
||||
在线更新遵循[版本命名与升级规则](../deploy/README.md#版本命名与升级规则)。版本接口的
|
||||
`updateChannel` 由当前版本推导,取值为 `stable`、`alpha`、`beta`、`rc`、`exp`,无法识别时为 `unknown`。
|
||||
详情接口的可选 `channel` 仅作用于本次查询,不保存实例偏好;省略时按当前运行版本推导。
|
||||
响应的 `policy` 包含本次 `channel` 与 `availableChannels`,普通实例可选 `stable`、`rc`、`beta`、`alpha`,
|
||||
实验实例仅允许 `exp`。不可用通道返回 `40901`,未知枚举值返回参数错误。
|
||||
执行时应同时发送页面确认的 `channel` 与 `targetVersion`,服务端冻结该通道并重新复核远端目标;
|
||||
省略通道时按运行版本推导。版本接口只读本地构建和已有运行通道摘要,缓存未就绪时 `updateCached=false`,不会发起网络请求。
|
||||
检查与执行使用同一规则,禁止的通道转换、跨实验线、跨大版本、降级或同版本重装均以 `40901` 拒绝。
|
||||
`hasUpdate=true` 仅表示当前构建支持在线更新,且存在允许的更高版本;`latestVersion`、`releaseUrl` 和
|
||||
`notes` 对应这个候选。没有可升级候选时,`hasUpdate=false`、`latestVersion` 为当前版本,
|
||||
`releaseUrl` 和 `notes` 保留当前版本的已发布 Release 信息;找不到匹配当前版本的 Release 时为空。
|
||||
当前构建不支持在线更新时不查询 Release,`hasUpdate=false`、`latestVersion` 为当前版本,
|
||||
`releaseUrl` 和 `notes` 为空,不支持原因通过 `updateSupported=false`、`unsupportedReason` 返回。
|
||||
版本接口只读本地构建和通道摘要,缓存未就绪时返回 `updateCached=false`。`updateChannel` 按运行版本推导,为 `stable`、`alpha`、`beta`、`rc`、`exp` 或 `unknown`
|
||||
|
||||
详情与安装接口的 `channel` 只对本次操作有效,省略时取运行通道。响应的 `policy` 包含 `channel` 和 `availableChannels`。普通实例可选 `stable`、`rc`、`beta`、`alpha`,实验实例仅可选 `exp`。
|
||||
未知枚举值返回参数错误。禁用通道、跨实验线、跨大版本、降级或同版本重装返回 `40901`。安装时同时提交已确认的 `channel` 和 `targetVersion`,服务端按[升级规则](../deploy/README.md#版本命名与升级规则)复核目标
|
||||
|
||||
| 详情查询结果 | `hasUpdate` | `latestVersion` | `releaseUrl`、`notes` |
|
||||
| --- | --- | --- | --- |
|
||||
| 有可安装的更高版本 | `true` | 候选版本 | 候选 Release 信息 |
|
||||
| 无可升级候选 | `false` | 当前版本 | 当前 Release 信息,未找到时为空 |
|
||||
| 构建不支持在线更新 | `false` | 当前版本 | 为空。跳过 Release 查询,通过 `updateSupported=false` 与 `unsupportedReason` 返回原因 |
|
||||
|
||||
`summaryOnly=true` 优先于 `refresh`,按发布索引检查版本,仅对更高候选核对公开 Release 和当前平台附件;`notes`、`releaseUrl` 为空。详情或摘要检查失败时返回 `warning` 和 `hasUpdate=false`,此时 `latestVersion` 不代表已确认的通道版本。GitHub 限流时,`retryAt` 为最早可重试的 RFC 3339 时间,`retryAtDisplay` 按部署时区展示;其他情况两者均为 `null`。
|
||||
普通查询缓存 20 分钟,手动刷新最短间隔为 60 秒;临时错误缓存 60 秒,限流按来源退避。
|
||||
后台安装重新核对通道和目标版本,目标变化须再次检查并确认;下载与校验流程见[在线更新](../deploy/README.md#管理端在线更新)
|
||||
目标变化须重新检查并确认。下载与校验见[在线更新](../deploy/README.md#管理端在线更新)
|
||||
|
||||
更新 POST 在本地校验目标版本并持久化任务后返回 `202`,数据包含 `operationId`、`targetVersion`、
|
||||
`deploymentMode` 和 `message`,只表示已受理。Release 查询、远端目标复核、下载、校验及文件替换在后台
|
||||
执行,结果通过 `/update/status` 的 `operation` 查询:`status` 为 `idle`、`running`、`succeeded` 或 `failed`,
|
||||
终态包含 `finishedAt`,失败原因在 `error` 中。SSE 的 `operationId` 用于关联进度;终态事件发出前状态已落盘。
|
||||
连接中断不取消已受理任务;响应丢失时先查询状态,不自动重复提交。打开更新页面时也会恢复最近一次任务。
|
||||
下载并解包后校验发行身份,插件版本不匹配不阻止更新或回滚,兼容性风险在重启前提示。
|
||||
两条路径在文件交换前后复核全局配置版本,文件替换失败或取消时成组恢复二进制、Web 资源和官方插件目录
|
||||
更新 POST 在本地校验目标版本、保存任务后返回 `202`,含 `operationId`、`targetVersion`、`deploymentMode` 和 `message`。后台负责复核 Release、下载、校验及替换文件。
|
||||
通过 SSE 的 `operationId` 跟踪进度,或查询 `/update/status` 的 `operation`。`status` 取 `idle`、`running`、`succeeded` 或 `failed`。终态含 `finishedAt`,失败原因在 `error`,状态落盘后发送终态事件。
|
||||
断开连接不取消任务。响应丢失时先查询状态,重新打开更新页面可查看最近任务。
|
||||
更新和回滚均校验发行身份,在文件交换前后复核全局配置版本。失败或取消时成组恢复二进制、Web 和官方插件目录。插件兼容风险在重启前确认
|
||||
|
||||
客户端重启前调用 `restart/check`,返回 `targetVersion`、`releaseManifestSha256`、`configRevision` 和 `incompatiblePlugins`,
|
||||
每项包含 `instanceId`、`name`、`reason`,检查不修改插件状态。源码运行的目标版本与发行摘要为空,检查当前宿主兼容性。
|
||||
|
||||
+15
-28
@@ -1,8 +1,6 @@
|
||||
# Codex Proxy RS 架构
|
||||
|
||||
本文说明模块职责、请求流程、状态存储和必须保持的约束。
|
||||
具体 HTTP 字段见 [接口文档](api.md),部署参数见 [部署文档](../deploy/README.md);上游 URL、超时、
|
||||
重试间隔和 UI 布局属于源码或配置,不在架构文档重复维护
|
||||
HTTP 字段见[接口文档](api.md),部署参数见[部署文档](../deploy/README.md)
|
||||
|
||||
| 阅读目标 | 章节 |
|
||||
| --- | --- |
|
||||
@@ -26,9 +24,7 @@ Codex Proxy RS 是单进程、单副本运行的多 Provider AI 网关,同时
|
||||
|
||||
Responses、Chat Completions 和 Messages 共用生成执行链,API Key 账号可选择 Responses 或 Messages 上游协议,
|
||||
仍由 OpenAI Provider 管理。Chat 在 API 层转为 Responses,Provider 在选定账号后处理 Messages 与 Responses 的转换。
|
||||
系统不存在 Provider Instance 层,也不支持通过复制应用容器进行多副本扩容。
|
||||
Client Key 限定账号分组,而不是绑定某个 Provider;一次请求的
|
||||
Provider 候选由账号范围、模型能力和运行时健康共同决定
|
||||
Client Key 限定账号分组,账号范围、模型能力与运行时健康决定候选 Provider。网关没有独立的 Provider Instance 层
|
||||
|
||||
| 概念 | 所有者与含义 |
|
||||
| --- | --- |
|
||||
@@ -37,8 +33,7 @@ Provider 候选由账号范围、模型能力和运行时健康共同决定
|
||||
| 认证方式 | Provider 解释账号 credential schema,并生成对应上游认证材料 |
|
||||
| 上游协议 | Provider 根据所选账号的配置与能力决定实际发送格式,调用协议层转换器 |
|
||||
|
||||
Provider 注册名与协议标识分别维护,即使字符串相同也不互相代替。
|
||||
`providers/openai` 执行兼容 API Key 账号的 Messages 请求,表示该适配器支持此账号与协议组合,不代表入站协议决定 Provider 身份
|
||||
Provider 注册名与协议标识分别维护,同名也不能互换
|
||||
|
||||
## 2. 运行拓扑
|
||||
|
||||
@@ -218,7 +213,7 @@ flowchart LR
|
||||
协议与容量见 [SDK 通信边界](../backend/crates/gateway-plugin/sdk/README.md#通信边界)
|
||||
- **主动 HTTP 请求复用总路由**:Runtime 通过 Core 的 `http::Dispatcher` 调用 API 已组装的路由,SDK 的 `dispatch_http` 与 `next` 共用正文资源池。
|
||||
子调用持有父子关联、冻结计划和取消信号,跳过祖先发起实例;模型 request 与 attempt 延续该集合。内部管理请求使用宿主签发的插件身份,审计记录插件与调用来源,普通客户端不能用 headers 声明此身份。
|
||||
正文转交延续真实交付寿命,EOF、显式关闭或父级取消释放资源;组合根保活 Dispatcher,Runtime 只保存 Weak,不增加逐接口注册清单
|
||||
正文转交后存续至 EOF、显式关闭或父调用取消。组合根持有 Dispatcher,Runtime 只保存弱引用
|
||||
- **主动服务调用在注册表统一组合**:Admin 按类型登记操作,Core 组合器只负责续体,Runtime 搬运跨进程调用。
|
||||
插件与 CLI 主动调用公开服务时进入 `service` 中间件一次;原生 HTTP 接口由总入口包裹,业务方法及其内部调用不重复组合。
|
||||
主动子调用继承冻结计划、父子关联和取消信号,无 service 绑定时也保留空计划快照;调用结束回收资源。
|
||||
@@ -568,7 +563,7 @@ OpenAI 模型目录用于发现与原生 Responses 账号资格筛选。
|
||||
同协议业务响应使用原始 wire,跨协议才调用转换器;客户端错误兼容与原生续写额度恢复按明确例外处理,见 [OpenAI 透传](api.md#openai-透传)。
|
||||
`transport/correlation` 在出站副本上按本次安装身份统一映射关联标识。
|
||||
Responses 的账号归属判断及换号头部清理由 Provider 统一执行,各传输消费同一出站请求。
|
||||
原生安装身份由 OpenAI Provider 按 Key 种子、Key ID 与选中账号 ID 确定性派生,无需额外映射表;未配置种子时取自账号,与 UA 继承方式无关。Live 后续阶段使用引导时冻结的种子;插件的身份生成、持久化及关联字段改写通过既有中间件链路自行完成
|
||||
安装身份独立于 UA,派生规则见 [Key 客户端身份](api.md#key-客户端身份)。Live 沿用引导时冻结的种子。插件通过中间件生成并保存身份、改写关联字段
|
||||
内部选号、亲和、连接池与本地诊断继续读取原始身份;具体字段边界见 [API 协议](api.md#请求头与身份)
|
||||
canonical facts 从同一数据旁路提取,用于路由、恢复判断、观测和计费。
|
||||
WebSocket transport 按完整文本消息交付,wire 同时保留原文与可选解析视图;同协议出口使用原文,
|
||||
@@ -602,7 +597,7 @@ OpenAI 模型目录用于发现与原生 Responses 账号资格筛选。
|
||||
- OpenAI 与 xAI 用户身份选择由 PostgreSQL 保存,Core 在 `FrozenAccountScope` 中按 Key 整体覆盖通用选择,
|
||||
以 Provider-owned 不透明对象沿路由计划传递;执行会话复用首次解析结果,使重试不受发布更新影响。
|
||||
各 Provider 唯一负责默认值、校验、版本来源及 UA 生成,Admin 提供管理和生效预览。
|
||||
首次初始化只写入内置默认选择;YAML 不定义客户端身份,也不作为数据库初始化或请求解析的来源。
|
||||
首次初始化使用 Provider 内置默认值。
|
||||
官方发布资料与用户选择分开:OpenAI 在 Redis 按 Provider、客户端、平台、架构隔离可重建版本缓存,
|
||||
离线版本、制品身份及预设环境默认值集中在
|
||||
[`transport/profile/baseline.rs`](../backend/crates/providers/openai/src/transport/profile/baseline.rs),由发布检查与预设解析共用。
|
||||
@@ -615,7 +610,7 @@ OpenAI 模型目录用于发现与原生 Responses 账号资格筛选。
|
||||
其余后台账号和 Desktop 专属操作使用独立官方 Desktop 画像。
|
||||
管理端连接测试从本次发布快照携带全局画像,经 Provider 解析后冻结为探测身份。
|
||||
xAI 以内置画像为版本检查基线,在进程内更新 Grok CLI 发布资料;模型与压缩请求使用已保存的用户选择,
|
||||
OAuth、后台目录和额度查询使用内置官方画像。两者均不回写 `config.yaml`
|
||||
OAuth、后台目录和额度查询使用内置官方画像
|
||||
|
||||
xAI Provider 负责 Codex custom 工具与 Grok function 工具的双向转换,保持工具类型、item ID 与
|
||||
`call_id` 配对;超限或转换失败终止流。默认 `store: false` 的续接由现有会话 owner 重放完整历史;
|
||||
@@ -669,8 +664,7 @@ OpenAI Provider 的账号资格模块统一解释请求类型、认证与套餐
|
||||
其余原生 OpenAI 请求按来源账号、凭据版本和套餐匹配最近一次成功的目录,排除未列出的模型。大池可在读取账号时按目录摘要筛选,白名单和受管适配器由选号时单独判断。
|
||||
xAI 按套餐读取有效期内的目录缓存。两者在没有对应目录时保留上游验证,选号不请求上游目录
|
||||
|
||||
原生 OpenAI Responses 按[官方 Codex 0.166.0](https://github.com/openai/codex/blob/6ff1e1ca3b30fc8b914720681fcf5fe62e95f856/codex-rs/codex-api/src/error.rs#L73)的结构化 `model_not_found` 错误码与状态合同识别模型拒绝,
|
||||
不从消息或任意正文推断模型权限;通过既有模型级冷却端口记录账号、凭据版本与上游模型,30 分钟内不再选用该组合。
|
||||
原生 OpenAI Responses 按结构化错误码 `model_not_found` 识别模型拒绝。状态码缺失或为 400、403、404 时,将账号、凭据版本与上游模型的组合冷却 30 分钟。错误消息文本不参与判断。
|
||||
该反馈不冻结整个账号,不改写管理员模型政策,也不占用 WS 传输恢复预算;重试仍遵守交付边界与原生续写固定账号约束。
|
||||
管理员诊断旁路目录资格与模型拒绝冷却,OpenAI 的受管上游适配器不继承这两项原生限制
|
||||
|
||||
@@ -863,9 +857,8 @@ Arc 随 RoutingPlan 冻结并进入所有 attempt,不在推理请求中读取
|
||||
整份价目。Provider 按当前 attempt 实际发送的上游模型查价,响应声明的模型只作观测,费用明细复用同一口径;
|
||||
自定义倍率只作用于本地计算费用,上游报告金额不变
|
||||
|
||||
本地计算费用携带当次拆分、有效单价和倍率,终态观测将其写入版本化费用快照。查询优先还原快照,
|
||||
不使用新配置解释历史;无快照的旧记录保留总额核对后补充拆分的路径。Client Key 账本使用同一费用
|
||||
结果沿既有幂等结算流程累计,不依赖请求明细写入成功
|
||||
终态观测将本地费用拆分、有效单价和倍率写入版本化快照。查询优先展示快照,缺少快照时仅在按内置规则核算的总额与记录一致时补充拆分。
|
||||
Client Key 账本按同一费用幂等结算,独立于请求明细写入
|
||||
|
||||
## 7. 控制面与 revision
|
||||
|
||||
@@ -1099,7 +1092,7 @@ Admin 集中校验与裁剪公开能力,展示和调度消费同一份观测
|
||||
Admin 为账号聚合设置独立并发上限,满额立即返回可重试的限流响应;模型展开按响应字节预算提前拒绝必然超限的组合,批量投影定期让出执行时间,避免重查询占满共享数据库与执行资源
|
||||
|
||||
Admin 的 `peer_link` 分别拥有共享导出与上游消费用例;上游消费统一处理发现、协议校验、同步、展示和调度投影。
|
||||
Provider 声明可连接的认证种类,并从本轮凭据中提取连接材料;当前 OpenAI API Key 提供该适配,xAI 原生账号继续参与共享导出。
|
||||
Provider 声明可互联的认证类型并提取连接信息。OpenAI 支持从 API Key 账号接入,xAI 原生账号可参与共享导出。
|
||||
Host 执行有界 HTTP 请求,复用组合根注入的证书策略和账号出口;Store 通过通用账号额度端口保存不透明观测,不解释互联或 Provider 协议。
|
||||
互联与原生额度共用 `provider_quota_json`、`quota_observed_at`、凭据版本和额度访问事实,每个账号仅保存当前来源的观测。
|
||||
Admin 将明确不支持互联的结果绑定连接身份保存于同一观测,不伪造额度快照或改变额度访问状态。
|
||||
@@ -1113,7 +1106,7 @@ OAuth 额度解析属于 Provider,CPR 发现、解析与投影属于 Admin;
|
||||
额度时间戳支持轻量缓存校验,普通账号和凭据查询不加载额度正文,完整观测分批读取
|
||||
|
||||
共享端按 Core 的预算规则从本地账本生成明确的访问状态,与本地准入共用口径;金额字段只供接入端展示。
|
||||
接入端 Admin 的独立额度模块解释默认公开的访问状态,展示、调度投影与同步共用,不要求公开账号池额度;未知或过期事实保留已有状态,Provider 不新增 CPR 错误码分类。
|
||||
共享端默认公开访问状态,无需公开账号池额度。接入端 Admin 统一解释该状态,供展示、调度和同步使用,未知或过期时保留已有状态。
|
||||
通用额度写入按凭据版本和查询开始时间提交快照,并独立保护访问事实的观察时间;网络查询可附带连接校验,在同一事务核对出口与启用状态。
|
||||
互联账号重新授权或出口变更使旧快照及互联识别记录失效,正常 token 续期保留额度;授权撤销提交不含共享内容的观测和时间屏障,阻止更早响应重新发布旧内容。
|
||||
互联解析只提交有效且明确的预算访问事实,额度同步不改变凭据或独立冷却
|
||||
@@ -1427,15 +1420,11 @@ Store 在同一可重复读快照下导出业务表和已发布小时汇总,
|
||||
导出进程、快照事务和压缩文件由同一次任务持有;取消、15 分钟超时或失败会终止子进程并删除部分文件。
|
||||
压缩后限额和 SHA-256 覆盖实际上传字节,完整 schema 与迁移记录保留在归档内
|
||||
|
||||
PostgreSQL 备份恢复属于人工维护操作。当前没有部署级维护模式开关,需要先停止应用,
|
||||
离线处理快照中的非终态任务、计划游标和到期清理条件,再重新验证对象存储并恢复计划。
|
||||
关闭计划开关只阻止新计划任务,不会停止 Worker 的任务恢复和删除流程。
|
||||
未经核对就启动旧快照,可能触发远端对象删除;操作步骤见 [部署文档](../deploy/README.md#人工恢复数据库)
|
||||
恢复 PostgreSQL 前须停止应用。关闭计划只阻止新任务,Worker 仍可恢复任务并删除远端对象。
|
||||
离线核对非终态任务、计划游标和到期清理条件,再验证对象存储并恢复计划。步骤见[人工恢复数据库](../deploy/README.md#人工恢复数据库)
|
||||
|
||||
## 12. 修改与验收
|
||||
|
||||
变更按事实与资源的所有者分配,不能仅按“协议”或“生命周期”等宽泛标签决定目录:
|
||||
|
||||
| 改动内容 | 所属边界 |
|
||||
| --- | --- |
|
||||
| 入口解码与规范化、客户端连接和协议交付 | API |
|
||||
@@ -1447,9 +1436,7 @@ PostgreSQL 备份恢复属于人工维护操作。当前没有部署级维护模
|
||||
| 进程启动关闭、受管资源与后台任务监督 | Host |
|
||||
| 插件 RPC、调用关联与调用资源回收 | Runtime |
|
||||
|
||||
Chat 兼容入口在 API 中规范化为 Responses;Provider 在选号后按账号协议调用 `gateway-protocol` 的 Responses/Messages 转换器。
|
||||
请求、连接和 RPC 的寿命由各自所有者管理。
|
||||
状态归属与失败后的保证见[状态所有权](#8-状态所有权)。不以兼容 shim、第二套状态机或跨层旁路绕开已有合同
|
||||
协议转换见 [Provider 与协议边界](#5-provider-与协议边界),资源生命周期与失败保证见[状态所有权](#8-状态所有权)。扩展现有合同,避免增设平行状态机或跨层旁路
|
||||
|
||||
### 后端自审
|
||||
|
||||
|
||||
+12
-49
@@ -1,8 +1,6 @@
|
||||
# 开发与源码联调
|
||||
|
||||
本文说明开发环境、服务启动与跨仓库联调,命令均从宿主仓库根目录执行
|
||||
|
||||
协作与检查要求见 [贡献与审查](../CONTRIBUTING.md),部署实例的配置与数据维护见 [部署与运维](../deploy/README.md)
|
||||
除克隆仓库外,命令均在宿主仓库根目录执行。协作与验收见 [贡献与审查](../CONTRIBUTING.md),部署配置与数据维护见 [部署与运维](../deploy/README.md)
|
||||
|
||||
| 任务 | 入口 |
|
||||
| --- | --- |
|
||||
@@ -14,12 +12,8 @@
|
||||
|
||||
## 环境与依赖
|
||||
|
||||
需要 Node.js 26.13.1、pnpm、[Rust 工具链](architecture.md#验证命令)、PostgreSQL 和 Redis
|
||||
|
||||
各前端的 `packageManager` 固定 pnpm 版本,宿主 CI 和 Docker 从 `frontend/package.json` 读取
|
||||
|
||||
Rust 工具链声明位于 `backend/rust-toolchain.toml`,从仓库根目录运行 Cargo 时显式选择该工具链;
|
||||
`--manifest-path` 只选择 manifest,不切换 rustup 按当前目录选定的工具链
|
||||
使用 Node.js 26.13.1、PostgreSQL、Redis 和各前端 `packageManager` 指定的 pnpm。宿主 CI 与 Docker 读取 `frontend/package.json`。
|
||||
在仓库根目录运行 Cargo 时,用 `+版本号` 选择 `backend/rust-toolchain.toml` 指定的[工具链](architecture.md#验证命令)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zyycn/codex-proxy-rs.git
|
||||
@@ -27,11 +21,11 @@ cd codex-proxy-rs
|
||||
pnpm --dir frontend install --frozen-lockfile
|
||||
```
|
||||
|
||||
前端依赖、锁文件与 ESLint 配置由 `frontend/` 管理,根目录不维护 Node 包
|
||||
宿主前端的依赖、锁文件与 ESLint 配置位于 `frontend/`
|
||||
|
||||
- **版本固定**:`@codex-proxy/ui` 使用固定 GitHub 标签或提交,锁文件记录实际提交、源码归档地址及完整性摘要
|
||||
- **安装与构建**:pnpm 按 UI 自身锁文件准备依赖,执行 `prepack` 生成 JS、CSS 和类型声明,普通 `dev`、`build`、发行 CI 和 Docker 使用编译产物,无需初始化子模块
|
||||
- **构建许可**:`frontend/pnpm-workspace.yaml` 的 `allowBuilds` 按仓库放行自有 UI 包脚本,升级时核对源码并更新锁文件,无需逐次修改许可,不开放全部依赖脚本
|
||||
- **构建许可**:`frontend/pnpm-workspace.yaml` 的 `allowBuilds` 按仓库放行自有 UI 包脚本。升级时核对源码并更新锁文件
|
||||
|
||||
## 启动宿主
|
||||
|
||||
@@ -60,10 +54,7 @@ pnpm --dir frontend dev
|
||||
|
||||
## 源码入口
|
||||
|
||||
后端职责和依赖方向见 [Workspace 边界](architecture.md#3-workspace-边界),页面与共享逻辑见 [前端模块职责](architecture.md#34-前端模块职责)。
|
||||
先按所属模块定位,再跟踪请求、状态与展示的调用关系
|
||||
|
||||
共享 UI 的命名与目录见[组件架构](../modules/ui/playground/guide/architecture.md)
|
||||
[后端 Workspace 边界](architecture.md#3-workspace-边界) · [前端模块职责](architecture.md#34-前端模块职责) · [共享 UI 组件架构](../modules/ui/playground/guide/architecture.md)
|
||||
|
||||
Messages 与 Responses 的纯协议转换位于 `backend/crates/gateway-protocol/src/anthropic/`,
|
||||
HTTP 入口位于 `backend/crates/gateway-api/src/openai/messages.rs`,
|
||||
@@ -75,31 +66,7 @@ HTTP 入口位于 `backend/crates/gateway-api/src/openai/messages.rs`,
|
||||
再核对工具往返、取消、错误和输入计数;请求格式及六种组合见 [模型数据面](api.md#3-模型数据面与模型目录)。
|
||||
Messages 账号只配置 HTTP;本地计数估算不能替代上游计费核对
|
||||
|
||||
TLS 指纹在发布目标对应的操作系统和架构上核验,参考程序使用同机运行的官方 Codex CLI 可执行文件。
|
||||
`CODEX_PROXY_TEST_REFERENCE_BINARY` 指向实际二进制,Windows 使用 `.exe`,npm 安装时使用平台包中的二进制。
|
||||
macOS / Linux 可设置:
|
||||
|
||||
```bash
|
||||
export CODEX_PROXY_TEST_REFERENCE_BINARY=/absolute/path/to/codex
|
||||
export RUST_MIN_STACK=16777216
|
||||
```
|
||||
|
||||
Windows PowerShell 可设置:
|
||||
|
||||
```powershell
|
||||
$env:CODEX_PROXY_TEST_REFERENCE_BINARY = 'C:\path\to\codex.exe'
|
||||
$env:RUST_MIN_STACK = '16777216'
|
||||
```
|
||||
|
||||
随后在仓库根目录执行:
|
||||
|
||||
```text
|
||||
cargo +1.99.1 test --manifest-path backend/Cargo.toml --locked -p provider-openai --test main transport::tls:: -- --include-ignored --nocapture --test-threads=1
|
||||
```
|
||||
|
||||
对照用例记录官方版本及运行平台,分别采样默认 HTTP、自定义 CA 的 HTTP 和 WebSocket,各重复三次。
|
||||
默认 HTTP 保留扩展顺序逐项比较;rustls 路径对随机扩展顺序排序后比较,算法列表、密钥交换组和 ALPN 仍核对原有顺序。
|
||||
采集在本机 TLS 握手阶段结束,使用测试认证值,无需真实账号。普通测试默认忽略官方二进制对照用例,须以上述命令显式执行
|
||||
OpenAI 的 `transport::tls::` 测试在本机回环地址采集 ClientHello,覆盖默认 HTTP、自定义 CA 的 HTTP 和 WebSocket。运行方式见[后端验证命令](architecture.md#验证命令)
|
||||
|
||||
## 源码联调
|
||||
|
||||
@@ -111,7 +78,7 @@ cargo +1.99.1 test --manifest-path backend/Cargo.toml --locked -p provider-opena
|
||||
| `modules/ui` | `codex-proxy-ui`,共用组件与主题 |
|
||||
| `modules/plugins` | `codex-proxy-plugins`,官方插件示例 |
|
||||
|
||||
各仓库的常规 CI 验证自身代码和锁定依赖。源码模式用于按需联调,运行前确认所选版本或提交组合及其公开合同兼容
|
||||
各仓库的 CI 使用锁定依赖。联调前确认所选提交的公开接口兼容
|
||||
|
||||
### 检出与安装
|
||||
|
||||
@@ -122,7 +89,7 @@ git clone --recurse-submodules https://github.com/zyycn/codex-proxy-rs.git
|
||||
cd codex-proxy-rs
|
||||
```
|
||||
|
||||
已有仓库运行 `git submodule update --init --recursive`。子模块固定到具体提交;拉取宿主更新后,同样用此命令对齐。执行前先保存子模块中的改动,避免切换正在开发的分支
|
||||
在已有仓库中,先保存子模块改动,再用 `git submodule update --init --recursive` 检出宿主指定的提交。拉取宿主更新后也用此命令对齐
|
||||
|
||||
在宿主根目录安装各项目依赖:
|
||||
|
||||
@@ -177,12 +144,8 @@ pnpm --dir modules/plugins/examples/workbench/frontend build:source
|
||||
|
||||
## 编辑与提交
|
||||
|
||||
直接打开宿主目录即可开发,分别在对应仓库目录操作 Git
|
||||
|
||||
1. 在要修改的子模块内先创建分支,例如 `git -C modules/ui switch -c feat/select`。初次初始化的子模块通常处于 detached HEAD
|
||||
2. 在子模块运行自身检查,并在宿主根目录运行所需联调检查
|
||||
3. 分别提交、推送并合并组件库或插件 PR。宿主只记录子模块提交号,不能替代子仓库的提交与推送
|
||||
4. 管理端与插件页面按需升级 UI 依赖,各自固定标签或提交并维护锁文件,无需与 `modules/ui` 同步版本
|
||||
5. 提交宿主改动及 `modules/ui`、`modules/plugins` 指针。指针必须指向远程可取得的提交,不能只存在于开发机
|
||||
|
||||
更新子模块指针不会自动升级消费方依赖。正式依赖不能写成开发机路径或浮动分支;SDK 仍由插件仓库固定到包含所需合同的宿主提交
|
||||
3. 在对应仓库提交、推送并合并组件库或插件 PR
|
||||
4. 需要升级依赖时,在管理端或插件仓库固定 UI 标签或提交并更新锁文件。插件 SDK 固定到提供所需合同的宿主提交
|
||||
5. 在宿主仓库提交代码和子模块指针。指针须可从远程检出,更新指针不会升级消费方依赖
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 6.5 KiB |
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user