i/Aether
1
0
Fork 0
mirror of https://github.com/fawney19/Aether.git synced 2026-10-08 10:27:46 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat(claude-code): 增加动态 CLI 客户端画像并按官方发布刷新版本

Browse Source 
- 将 Claude Code 传输身份拆分为带版本的静态模板（Stainless/运行时/beta 策略）与动态 CLI 画像（cli_version / User-Agent），请求按快照读取保证 UA 与 billing cc_version 一致
- 将 codex_profile 泛化为 cli_client_profile，Codex 与 Claude Code 共享发布校验、缓存恢复、防回退与每日刷新逻辑
- Claude Code 跟随 npm latest，要求 8 个平台包版本与主包一致；支持 AETHER_CLAUDE_CODE_CLIENT_PROFILE_REFRESH 与 AETHER_CLAUDE_CODE_CLIENT_VERSION
- 新增定时任务 maintenance.claude_code.client.profile，启动时与 Codex 画像并发预热
- 额度查询 User-Agent 改用动态画像，移除硬编码 CLAUDE_CODE_USAGE_USER_AGENT
This commit is contained in:
dalamudx
2026-10-01 15:56:21 +08:00
parent 54fbcc25a1
commit d13f52bdf8
15 changed files with 975 additions and 556 deletions
Download Patch File Download Diff File Expand all files Collapse all files
apps/aether-gateway/src/cli_client_profile.rs
+690
View File
@@ -0,0 +1,690 @@
//! CLI 客户端画像（Codex / Claude Code）的运行时发布与官方版本刷新。
//!
//! 每个客户端由一份 [`CliClientProfileSpec`] 描述：官方 npm 发布源、平台包校验规则、
//! 运行时缓存键、环境变量开关与画像发布函数。刷新逻辑本身与客户端无关。
use std::collections::BTreeMap;
use std::future::Future;
use std::time::Duration;
use aether_runtime_state::RuntimeState;
use futures_util::StreamExt as _;
use reqwest::{redirect::Policy, Client};
use semver::Version;
use serde::{Deserialize, Serialize};
use tracing::{info, warn};
use crate::ai_serving::api::{codex_client_version, set_codex_cli_version};
use crate::ai_serving::transport::claude_code::{
claude_code_client_version, set_claude_code_cli_version,
};
use crate::task_runtime::{TASK_KEY_CLAUDE_CODE_CLIENT_PROFILE, TASK_KEY_CODEX_CLIENT_PROFILE};
use crate::AppState;
const PROFILE_CACHE_TTL: Duration = Duration::from_secs(30 * 24 * 60 * 60);
const PROFILE_REFRESH_INTERVAL: Duration = Duration::from_secs(24 * 60 * 60);
const RELEASE_CONNECT_TIMEOUT: Duration = Duration::from_secs(10);
const RELEASE_REQUEST_TIMEOUT: Duration = Duration::from_secs(30);
const MAX_RELEASE_BYTES: usize = 256 * 1024;
/// 单个 CLI 客户端的发布源、校验规则、缓存与运行时画像发布方式。
pub(crate) struct CliClientProfileSpec {
/// 日志中的客户端标识。
client: &'static str,
/// 官方 npm stable 标签的发布元数据地址。
release_endpoint: &'static str,
package_name: &'static str,
/// 同一发布必须同时携带的平台二进制包。
platform_targets: &'static [&'static str],
/// 根据包名、平台与版本给出期望的 optionalDependencies 条目。
platform_dependency: fn(&str, &str, &str) -> (String, String),
cache_key: &'static str,
refresh_env: &'static str,
fixed_version_env: &'static str,
task_key: &'static str,
active_version: fn() -> String,
publish_version: fn(&str) -> Result<(), &'static str>,
}
fn codex_platform_dependency(package: &str, target: &str, version: &str) -> (String, String) {
(
format!("{package}-{target}"),
format!("npm:{package}@{version}-{target}"),
)
}
fn claude_code_platform_dependency(package: &str, target: &str, version: &str) -> (String, String) {
(format!("{package}-{target}"), version.to_owned())
}
fn publish_codex_version(version: &str) -> Result<(), &'static str> {
set_codex_cli_version(version).map(|_| ())
}
fn publish_claude_code_version(version: &str) -> Result<(), &'static str> {
set_claude_code_cli_version(version).map(|_| ())
}
pub(crate) static CODEX_CLI_PROFILE: CliClientProfileSpec = CliClientProfileSpec {
client: "codex",
release_endpoint: "https://registry.npmjs.org/@openai%2Fcodex/latest",
package_name: "@openai/codex",
platform_targets: &[
"darwin-arm64",
"darwin-x64",
"linux-arm64",
"linux-x64",
"win32-arm64",
"win32-x64",
],
platform_dependency: codex_platform_dependency,
cache_key: "aether:codex:client-profile:v1",
refresh_env: "AETHER_CODEX_CLIENT_PROFILE_REFRESH",
fixed_version_env: "AETHER_CODEX_CLIENT_VERSION",
task_key: TASK_KEY_CODEX_CLIENT_PROFILE,
active_version: codex_client_version,
publish_version: publish_codex_version,
};
/// Claude Code 跟随 npm `latest` 标签，与官方 CLI 默认的自动更新通道一致。
/// 仅 CLI 版本（User-Agent 与 billing cc_version）随发布刷新；Stainless SDK 与运行时
/// 指纹仍由 transport crate 中带版本号的身份模板统一维护。
pub(crate) static CLAUDE_CODE_CLI_PROFILE: CliClientProfileSpec = CliClientProfileSpec {
client: "claude_code",
release_endpoint: "https://registry.npmjs.org/@anthropic-ai%2Fclaude-code/latest",
package_name: "@anthropic-ai/claude-code",
platform_targets: &[
"darwin-arm64",
"darwin-x64",
"linux-arm64",
"linux-x64",
"linux-arm64-musl",
"linux-x64-musl",
"win32-arm64",
"win32-x64",
],
platform_dependency: claude_code_platform_dependency,
cache_key: "aether:claude_code:client-profile:v1",
refresh_env: "AETHER_CLAUDE_CODE_CLIENT_PROFILE_REFRESH",
fixed_version_env: "AETHER_CLAUDE_CODE_CLIENT_VERSION",
task_key: TASK_KEY_CLAUDE_CODE_CLIENT_PROFILE,
active_version: claude_code_client_version,
publish_version: publish_claude_code_version,
};
#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
struct NpmRelease {
name: String,
version: String,
optional_dependencies: BTreeMap<String, String>,
}
#[derive(Debug, Deserialize, Serialize)]
struct CachedProfile {
version: String,
verified_at_unix_secs: u64,
}
#[derive(Debug, thiserror::Error)]
enum ProfileRefreshError {
#[error("CLI release client initialization failed: {0}")]
Client(#[from] reqwest::Error),
#[error("CLI release request returned HTTP {0}")]
HttpStatus(u16),
#[error("CLI release response exceeded {MAX_RELEASE_BYTES} bytes")]
ResponseTooLarge,
#[error("CLI release metadata is invalid")]
InvalidMetadata,
#[error("CLI release version is older than the active profile")]
Rollback,
#[error("CLI profile cache operation failed: {0}")]
Cache(String),
}
fn version_sequence(version: &str) -> Result<u64, ProfileRefreshError> {
let parsed = Version::parse(version).map_err(|_| ProfileRefreshError::InvalidMetadata)?;
if !parsed.pre.is_empty()
|| !parsed.build.is_empty()
|| parsed.major > 999
|| parsed.minor > 999
|| parsed.patch > 999
{
return Err(ProfileRefreshError::InvalidMetadata);
}
Ok(1 + parsed.major * 1_000_000 + parsed.minor * 1_000 + parsed.patch)
}
/// 校验官方 npm 标签及全部平台依赖来自同一版本发布。
fn parse_cli_release(
spec: &CliClientProfileSpec,
bytes: &[u8],
) -> Result<String, ProfileRefreshError> {
if bytes.len() > MAX_RELEASE_BYTES {
return Err(ProfileRefreshError::ResponseTooLarge);
}
let release = serde_json::from_slice::<NpmRelease>(bytes)
.map_err(|_| ProfileRefreshError::InvalidMetadata)?;
let sequence = version_sequence(&release.version)?;
if sequence == 0
|| release.name != spec.package_name
|| spec.platform_targets.iter().any(|target| {
let (name, expected) =
(spec.platform_dependency)(spec.package_name, target, &release.version);
release.optional_dependencies.get(&name) != Some(&expected)
})
{
return Err(ProfileRefreshError::InvalidMetadata);
}
Ok(release.version)
}
fn refresh_enabled_from(value: Option<&str>) -> bool {
!value.is_some_and(|value| {
matches!(
value.trim().to_ascii_lowercase().as_str(),
"0" | "false" | "off"
)
})
}
fn refresh_enabled(spec: &CliClientProfileSpec) -> bool {
refresh_enabled_from(std::env::var(spec.refresh_env).ok().as_deref())
}
fn fixed_version_from(value: Option<&str>) -> Option<String> {
let value = value?.trim();
if value.is_empty() || version_sequence(value).is_err() {
None
} else {
Some(value.to_owned())
}
}
fn fixed_version_override(spec: &CliClientProfileSpec) -> Option<String> {
let value = std::env::var(spec.fixed_version_env).ok()?;
let version = fixed_version_from(Some(&value));
if version.is_none() {
warn!(
event_name = "cli_client_profile_fixed_version_invalid",
client = spec.client,
env = spec.fixed_version_env,
"fixed CLI client version is invalid; using cached or built-in profile"
);
}
version
}
fn build_release_client() -> Result<Client, ProfileRefreshError> {
Client::builder()
.https_only(true)
.no_proxy()
.redirect(Policy::none())
.connect_timeout(RELEASE_CONNECT_TIMEOUT)
.timeout(RELEASE_REQUEST_TIMEOUT)
.build()
.map_err(ProfileRefreshError::Client)
}
async fn fetch_latest_cli_version(
spec: &CliClientProfileSpec,
client: &Client,
) -> Result<String, ProfileRefreshError> {
let response = client
.get(spec.release_endpoint)
.send()
.await
.map_err(ProfileRefreshError::Client)?;
if !response.status().is_success() {
return Err(ProfileRefreshError::HttpStatus(response.status().as_u16()));
}
if response
.content_length()
.is_some_and(|length| length > MAX_RELEASE_BYTES as u64)
{
return Err(ProfileRefreshError::ResponseTooLarge);
}
let mut bytes = Vec::new();
let mut stream = response.bytes_stream();
while let Some(chunk) = stream.next().await {
let chunk = chunk.map_err(ProfileRefreshError::Client)?;
if bytes.len().saturating_add(chunk.len()) > MAX_RELEASE_BYTES {
return Err(ProfileRefreshError::ResponseTooLarge);
}
bytes.extend_from_slice(&chunk);
}
parse_cli_release(spec, &bytes)
}
fn publish(spec: &CliClientProfileSpec, version: &str) -> Result<(), ProfileRefreshError> {
(spec.publish_version)(version).map_err(|_| ProfileRefreshError::InvalidMetadata)
}
async fn restore_cached_profile(
spec: &CliClientProfileSpec,
runtime: &RuntimeState,
) -> Result<(), ProfileRefreshError> {
let Some(raw) = runtime
.kv_get(spec.cache_key)
.await
.map_err(|err| ProfileRefreshError::Cache(err.to_string()))?
else {
return Ok(());
};
let cached = serde_json::from_str::<CachedProfile>(&raw)
.map_err(|_| ProfileRefreshError::InvalidMetadata)?;
if let Some(version) = cached_version_to_restore(&cached, &(spec.active_version)())? {
publish(spec, &version)?;
info!(
event_name = "cli_client_profile_restored",
client = spec.client,
version = %version,
verified_at_unix_secs = cached.verified_at_unix_secs,
"restored cached CLI client profile"
);
}
Ok(())
}
fn cached_version_to_restore(
cached: &CachedProfile,
active_version: &str,
) -> Result<Option<String>, ProfileRefreshError> {
let cached_sequence = version_sequence(&cached.version)?;
let active_sequence = version_sequence(active_version)?;
Ok((cached_sequence >= active_sequence).then(|| cached.version.clone()))
}
async fn refresh_once_with_fetch<F, Fut>(
spec: &CliClientProfileSpec,
runtime: &RuntimeState,
fixed_version: Option<&str>,
refresh_is_enabled: bool,
fetch_latest: F,
) -> Result<String, ProfileRefreshError>
where
F: FnOnce() -> Fut,
Fut: Future<Output = Result<String, ProfileRefreshError>>,
{
if let Some(version) = fixed_version {
publish(spec, version)?;
return Ok(version.to_owned());
}
if let Err(error) = restore_cached_profile(spec, runtime).await {
// 缓存损坏或暂时不可用不应阻断官方版本检查；当前进程继续使用旧画像。
warn!(
event_name = "cli_client_profile_cache_restore_failed",
client = spec.client,
error = %error,
"could not restore cached CLI client profile"
);
}
if !refresh_is_enabled {
return Ok((spec.active_version)());
}
let version = fetch_latest().await?;
let current = (spec.active_version)();
if version_sequence(&version)? < version_sequence(&current)? {
return Err(ProfileRefreshError::Rollback);
}
let cached = CachedProfile {
version: version.clone(),
verified_at_unix_secs: chrono::Utc::now().timestamp().max(0) as u64,
};
let serialized =
serde_json::to_string(&cached).map_err(|_| ProfileRefreshError::InvalidMetadata)?;
publish(spec, &version)?;
if let Err(error) = runtime
.kv_set(spec.cache_key, serialized, Some(PROFILE_CACHE_TTL))
.await
{
// 本地画像已经完成原子替换；缓存写失败只影响下次进程启动的恢复。
warn!(
event_name = "cli_client_profile_cache_write_failed",
client = spec.client,
error = %error,
"published CLI client profile locally but could not persist the cache"
);
}
Ok(version)
}
async fn refresh_once(
spec: &CliClientProfileSpec,
runtime: &RuntimeState,
) -> Result<String, ProfileRefreshError> {
let fixed_version = fixed_version_override(spec);
refresh_once_with_fetch(
spec,
runtime,
fixed_version.as_deref(),
refresh_enabled(spec),
|| async {
let client = build_release_client()?;
fetch_latest_cli_version(spec, &client).await
},
)
.await
}
pub(crate) async fn prewarm(
spec: &CliClientProfileSpec,
runtime: &RuntimeState,
) -> Result<String, String> {
refresh_once(spec, runtime)
.await
.map_err(|err| err.to_string())
}
pub(crate) fn spawn_worker(
spec: &'static CliClientProfileSpec,
app: AppState,
) -> tokio::task::JoinHandle<()> {
crate::task_runtime::spawn_singleton_worker(app, spec.task_key, move |app| async move {
let mut interval = tokio::time::interval(PROFILE_REFRESH_INTERVAL);
interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
// 启动阶段由 prewarm 完成一次检查；后台任务只负责后续每日刷新，避免重复建连。
interval.tick().await;
loop {
interval.tick().await;
match refresh_once(spec, app.runtime_state()).await {
Ok(version) => info!(
event_name = "cli_client_profile_refreshed",
client = spec.client,
version = %version,
"refreshed CLI client profile"
),
Err(error) => warn!(
event_name = "cli_client_profile_refresh_failed",
client = spec.client,
error = %error,
"keeping the previous CLI client profile after refresh failure"
),
}
}
})
}
#[cfg(test)]
mod tests {
use std::sync::{
atomic::{AtomicBool, Ordering},
Mutex,
};
use std::time::Duration;
use aether_runtime_state::{MemoryRuntimeStateConfig, RuntimeState};
use super::{
cached_version_to_restore, fixed_version_from, parse_cli_release, refresh_enabled_from,
refresh_once_with_fetch, CachedProfile, CliClientProfileSpec, ProfileRefreshError,
CLAUDE_CODE_CLI_PROFILE, CODEX_CLI_PROFILE,
};
const TEST_BUILTIN_VERSION: &str = "1.0.0";
/// 测试画像使用独立存储，避免改写进程级 Codex / Claude Code 画像而干扰并行测试。
static TEST_ACTIVE_VERSION: Mutex<String> = Mutex::new(String::new());
/// 异步测试会跨 await 持有该锁，因此使用 tokio 的异步锁串行化共享测试画像。
static TEST_LOCK: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
fn test_active_version() -> String {
TEST_ACTIVE_VERSION
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.clone()
}
fn test_publish_version(version: &str) -> Result<(), &'static str> {
*TEST_ACTIVE_VERSION
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner) = version.to_owned();
Ok(())
}
static TEST_PROFILE: CliClientProfileSpec = CliClientProfileSpec {
client: "test",
release_endpoint: "https://registry.invalid/test/latest",
package_name: "@test/cli",
platform_targets: &["linux-x64"],
platform_dependency: super::claude_code_platform_dependency,
cache_key: "aether:test:client-profile:v1",
refresh_env: "AETHER_TEST_CLIENT_PROFILE_REFRESH",
fixed_version_env: "AETHER_TEST_CLIENT_VERSION",
task_key: "maintenance.test.client.profile",
active_version: test_active_version,
publish_version: test_publish_version,
};
async fn test_profile_guard() -> tokio::sync::MutexGuard<'static, ()> {
let guard = TEST_LOCK.lock().await;
test_publish_version(TEST_BUILTIN_VERSION).unwrap();
guard
}
#[test]
fn accepts_only_one_verified_codex_release_for_all_targets() {
let body = serde_json::json!({
"name": "@openai/codex",
"version": "0.200.1",
"optionalDependencies": {
"@openai/codex-darwin-arm64": "npm:@openai/[email protected]",
"@openai/codex-darwin-x64": "npm:@openai/[email protected]",
"@openai/codex-linux-arm64": "npm:@openai/[email protected]",
"@openai/codex-linux-x64": "npm:@openai/[email protected]",
"@openai/codex-win32-arm64": "npm:@openai/[email protected]",
"@openai/codex-win32-x64": "npm:@openai/[email protected]"
}
});
assert_eq!(
parse_cli_release(&CODEX_CLI_PROFILE, &serde_json::to_vec(&body).unwrap()).unwrap(),
"0.200.1"
);
}
#[test]
fn accepts_only_one_verified_claude_code_release_for_all_targets() {
let mut body = serde_json::json!({
"name": "@anthropic-ai/claude-code",
"version": "2.1.286",
"optionalDependencies": {
"@anthropic-ai/claude-code-darwin-arm64": "2.1.286",
"@anthropic-ai/claude-code-darwin-x64": "2.1.286",
"@anthropic-ai/claude-code-linux-arm64": "2.1.286",
"@anthropic-ai/claude-code-linux-x64": "2.1.286",
"@anthropic-ai/claude-code-linux-arm64-musl": "2.1.286",
"@anthropic-ai/claude-code-linux-x64-musl": "2.1.286",
"@anthropic-ai/claude-code-win32-arm64": "2.1.286",
"@anthropic-ai/claude-code-win32-x64": "2.1.286"
}
});
assert_eq!(
parse_cli_release(
&CLAUDE_CODE_CLI_PROFILE,
&serde_json::to_vec(&body).unwrap()
)
.unwrap(),
"2.1.286"
);
// 任一平台包与主包版本不一致都视为未完成的发布。
body["optionalDependencies"]["@anthropic-ai/claude-code-linux-x64-musl"] =
serde_json::json!("2.1.285");
assert!(parse_cli_release(
&CLAUDE_CODE_CLI_PROFILE,
&serde_json::to_vec(&body).unwrap()
)
.is_err());
}
#[test]
fn rejects_incomplete_or_foreign_release() {
let incomplete = serde_json::json!({
"name": "@openai/codex",
"version": "0.200.1",
"optionalDependencies": {}
});
assert!(parse_cli_release(
&CODEX_CLI_PROFILE,
&serde_json::to_vec(&incomplete).unwrap()
)
.is_err());
let foreign = serde_json::json!({
"name": "@openai/codex",
"version": "2.1.286",
"optionalDependencies": {
"@openai/codex-linux-x64": "2.1.286"
}
});
assert!(parse_cli_release(
&CLAUDE_CODE_CLI_PROFILE,
&serde_json::to_vec(&foreign).unwrap()
)
.is_err());
}
#[test]
fn client_specs_do_not_share_cache_keys_or_env_switches() {
assert_ne!(
CODEX_CLI_PROFILE.cache_key,
CLAUDE_CODE_CLI_PROFILE.cache_key
);
assert_ne!(CODEX_CLI_PROFILE.task_key, CLAUDE_CODE_CLI_PROFILE.task_key);
assert_ne!(
CODEX_CLI_PROFILE.refresh_env,
CLAUDE_CODE_CLI_PROFILE.refresh_env
);
assert_ne!(
CODEX_CLI_PROFILE.fixed_version_env,
CLAUDE_CODE_CLI_PROFILE.fixed_version_env
);
assert_eq!(
CLAUDE_CODE_CLI_PROFILE.fixed_version_env,
"AETHER_CLAUDE_CODE_CLIENT_VERSION"
);
}
#[test]
fn refresh_and_fixed_version_environment_policies_are_strict() {
assert!(!refresh_enabled_from(Some("off")));
assert!(!refresh_enabled_from(Some(" FALSE ")));
assert!(refresh_enabled_from(None));
assert_eq!(
fixed_version_from(Some(" 0.200.1 ")).as_deref(),
Some("0.200.1")
);
assert!(fixed_version_from(Some("0.200.1-beta.1")).is_none());
assert!(fixed_version_from(Some("1.2")).is_none());
}
#[test]
fn cached_profile_never_rewinds_active_profile() {
let cached = CachedProfile {
version: "0.200.1".to_string(),
verified_at_unix_secs: 1,
};
assert_eq!(
cached_version_to_restore(&cached, "0.200.0").unwrap(),
Some("0.200.1".to_string())
);
assert_eq!(cached_version_to_restore(&cached, "0.201.0").unwrap(), None);
}
#[tokio::test]
async fn cache_hit_is_restored_without_network_when_refresh_is_disabled() {
let _guard = test_profile_guard().await;
let runtime = RuntimeState::memory(MemoryRuntimeStateConfig::default());
runtime
.kv_set(
TEST_PROFILE.cache_key,
serde_json::to_string(&CachedProfile {
version: "1.2.0".to_string(),
verified_at_unix_secs: 1,
})
.unwrap(),
Some(Duration::from_secs(60)),
)
.await
.unwrap();
let result = refresh_once_with_fetch(&TEST_PROFILE, &runtime, None, false, || async {
Err(ProfileRefreshError::HttpStatus(599))
})
.await
.unwrap();
assert_eq!(result, "1.2.0");
assert_eq!(test_active_version(), "1.2.0");
}
#[tokio::test]
async fn successful_refresh_publishes_and_caches_profile() {
let _guard = test_profile_guard().await;
let runtime = RuntimeState::memory(MemoryRuntimeStateConfig::default());
let result = refresh_once_with_fetch(&TEST_PROFILE, &runtime, None, true, || async {
Ok("1.3.0".to_string())
})
.await
.unwrap();
assert_eq!(result, "1.3.0");
assert_eq!(test_active_version(), "1.3.0");
let cached = runtime
.kv_get(TEST_PROFILE.cache_key)
.await
.unwrap()
.expect("cached profile");
let cached = serde_json::from_str::<CachedProfile>(&cached).unwrap();
assert_eq!(cached.version, "1.3.0");
}
#[tokio::test]
async fn refresh_failure_keeps_previous_profile() {
let _guard = test_profile_guard().await;
let runtime = RuntimeState::memory(MemoryRuntimeStateConfig::default());
let result = refresh_once_with_fetch(&TEST_PROFILE, &runtime, None, true, || async {
Err(ProfileRefreshError::HttpStatus(503))
})
.await;
assert!(matches!(result, Err(ProfileRefreshError::HttpStatus(503))));
assert_eq!(test_active_version(), TEST_BUILTIN_VERSION);
}
#[tokio::test]
async fn fixed_version_override_skips_network_and_publishes_profile() {
let _guard = test_profile_guard().await;
let runtime = RuntimeState::memory(MemoryRuntimeStateConfig::default());
let fetch_called = AtomicBool::new(false);
let result =
refresh_once_with_fetch(&TEST_PROFILE, &runtime, Some("1.5.0"), true, || async {
fetch_called.store(true, Ordering::SeqCst);
Ok("1.6.0".to_string())
})
.await
.unwrap();
assert_eq!(result, "1.5.0");
assert!(!fetch_called.load(Ordering::SeqCst));
assert_eq!(test_active_version(), "1.5.0");
}
#[tokio::test]
async fn rollback_is_rejected_without_replacing_profile() {
let _guard = test_profile_guard().await;
(TEST_PROFILE.publish_version)("1.5.0").unwrap();
let runtime = RuntimeState::memory(MemoryRuntimeStateConfig::default());
let result = refresh_once_with_fetch(&TEST_PROFILE, &runtime, None, true, || async {
Ok("1.4.9".to_string())
})
.await;
assert!(matches!(result, Err(ProfileRefreshError::Rollback)));
assert_eq!(test_active_version(), "1.5.0");
}
}
apps/aether-gateway/src/codex_profile.rs
-468
View File
@@ -1,468 +0,0 @@
//! Codex 客户端画像的运行时发布与官方 CLI 版本刷新。
use std::collections::BTreeMap;
use std::future::Future;
use std::time::Duration;
use aether_runtime_state::RuntimeState;
use futures_util::StreamExt as _;
use reqwest::{redirect::Policy, Client};
use semver::Version;
use serde::{Deserialize, Serialize};
use tracing::{info, warn};
use crate::ai_serving::api::{codex_client_version, set_codex_cli_version};
use crate::AppState;
const CLI_RELEASE_ENDPOINT: &str = "https://registry.npmjs.org/@openai%2Fcodex/latest";
const PROFILE_CACHE_KEY: &str = "aether:codex:client-profile:v1";
const PROFILE_CACHE_TTL: Duration = Duration::from_secs(30 * 24 * 60 * 60);
const PROFILE_REFRESH_INTERVAL: Duration = Duration::from_secs(24 * 60 * 60);
const RELEASE_CONNECT_TIMEOUT: Duration = Duration::from_secs(10);
const RELEASE_REQUEST_TIMEOUT: Duration = Duration::from_secs(30);
const MAX_RELEASE_BYTES: usize = 256 * 1024;
const CLI_TARGETS: [&str; 6] = [
"darwin-arm64",
"darwin-x64",
"linux-arm64",
"linux-x64",
"win32-arm64",
"win32-x64",
];
#[derive(Debug, Deserialize)]
#[serde(rename_all = "camelCase")]
struct NpmRelease {
name: String,
version: String,
optional_dependencies: BTreeMap<String, String>,
}
#[derive(Debug, Deserialize, Serialize)]
struct CachedProfile {
version: String,
verified_at_unix_secs: u64,
}
#[derive(Debug, thiserror::Error)]
enum ProfileRefreshError {
#[error("Codex CLI release client initialization failed: {0}")]
Client(#[from] reqwest::Error),
#[error("Codex CLI release request returned HTTP {0}")]
HttpStatus(u16),
#[error("Codex CLI release response exceeded {MAX_RELEASE_BYTES} bytes")]
ResponseTooLarge,
#[error("Codex CLI release metadata is invalid")]
InvalidMetadata,
#[error("Codex CLI release version is older than the active profile")]
Rollback,
#[error("Codex CLI profile cache operation failed: {0}")]
Cache(String),
}
fn version_sequence(version: &str) -> Result<u64, ProfileRefreshError> {
let parsed = Version::parse(version).map_err(|_| ProfileRefreshError::InvalidMetadata)?;
if !parsed.pre.is_empty()
|| !parsed.build.is_empty()
|| parsed.major > 999
|| parsed.minor > 999
|| parsed.patch > 999
{
return Err(ProfileRefreshError::InvalidMetadata);
}
Ok(1 + parsed.major * 1_000_000 + parsed.minor * 1_000 + parsed.patch)
}
/// 校验官方 npm stable 标签及六个平台依赖来自同一版本发布。
fn parse_cli_release(bytes: &[u8]) -> Result<String, ProfileRefreshError> {
if bytes.len() > MAX_RELEASE_BYTES {
return Err(ProfileRefreshError::ResponseTooLarge);
}
let release = serde_json::from_slice::<NpmRelease>(bytes)
.map_err(|_| ProfileRefreshError::InvalidMetadata)?;
let sequence = version_sequence(&release.version)?;
if sequence == 0
|| release.name != "@openai/codex"
|| CLI_TARGETS.iter().any(|target| {
release
.optional_dependencies
.get(&format!("@openai/codex-{target}"))
!= Some(&format!("npm:@openai/codex@{}-{target}", release.version))
})
{
return Err(ProfileRefreshError::InvalidMetadata);
}
Ok(release.version)
}
fn refresh_enabled_from(value: Option<&str>) -> bool {
!value.is_some_and(|value| {
matches!(
value.trim().to_ascii_lowercase().as_str(),
"0" | "false" | "off"
)
})
}
fn refresh_enabled() -> bool {
refresh_enabled_from(
std::env::var("AETHER_CODEX_CLIENT_PROFILE_REFRESH")
.ok()
.as_deref(),
)
}
fn fixed_version_from(value: Option<&str>) -> Option<String> {
let value = value?.trim();
if value.is_empty() || version_sequence(value).is_err() {
None
} else {
Some(value.to_owned())
}
}
fn fixed_version_override() -> Option<String> {
let value = std::env::var("AETHER_CODEX_CLIENT_VERSION").ok()?;
let version = fixed_version_from(Some(&value));
if version.is_none() {
warn!(
event_name = "codex_client_profile_fixed_version_invalid",
"AETHER_CODEX_CLIENT_VERSION is invalid; using cached or built-in profile"
);
}
version
}
fn build_release_client() -> Result<Client, ProfileRefreshError> {
Client::builder()
.https_only(true)
.no_proxy()
.redirect(Policy::none())
.connect_timeout(RELEASE_CONNECT_TIMEOUT)
.timeout(RELEASE_REQUEST_TIMEOUT)
.build()
.map_err(ProfileRefreshError::Client)
}
async fn fetch_latest_cli_version(client: &Client) -> Result<String, ProfileRefreshError> {
let response = client
.get(CLI_RELEASE_ENDPOINT)
.send()
.await
.map_err(ProfileRefreshError::Client)?;
if !response.status().is_success() {
return Err(ProfileRefreshError::HttpStatus(response.status().as_u16()));
}
if response
.content_length()
.is_some_and(|length| length > MAX_RELEASE_BYTES as u64)
{
return Err(ProfileRefreshError::ResponseTooLarge);
}
let mut bytes = Vec::new();
let mut stream = response.bytes_stream();
while let Some(chunk) = stream.next().await {
let chunk = chunk.map_err(ProfileRefreshError::Client)?;
if bytes.len().saturating_add(chunk.len()) > MAX_RELEASE_BYTES {
return Err(ProfileRefreshError::ResponseTooLarge);
}
bytes.extend_from_slice(&chunk);
}
parse_cli_release(&bytes)
}
async fn restore_cached_profile(runtime: &RuntimeState) -> Result<(), ProfileRefreshError> {
let Some(raw) = runtime
.kv_get(PROFILE_CACHE_KEY)
.await
.map_err(|err| ProfileRefreshError::Cache(err.to_string()))?
else {
return Ok(());
};
let cached = serde_json::from_str::<CachedProfile>(&raw)
.map_err(|_| ProfileRefreshError::InvalidMetadata)?;
if let Some(version) = cached_version_to_restore(&cached, &codex_client_version())? {
set_codex_cli_version(&version).map_err(|_| ProfileRefreshError::InvalidMetadata)?;
info!(
event_name = "codex_client_profile_restored",
version = %version,
verified_at_unix_secs = cached.verified_at_unix_secs,
"restored cached Codex CLI profile"
);
}
Ok(())
}
fn cached_version_to_restore(
cached: &CachedProfile,
active_version: &str,
) -> Result<Option<String>, ProfileRefreshError> {
let cached_sequence = version_sequence(&cached.version)?;
let active_sequence = version_sequence(active_version)?;
Ok((cached_sequence >= active_sequence).then(|| cached.version.clone()))
}
async fn refresh_once_with_fetch<F, Fut>(
runtime: &RuntimeState,
fixed_version: Option<&str>,
refresh_is_enabled: bool,
fetch_latest: F,
) -> Result<String, ProfileRefreshError>
where
F: FnOnce() -> Fut,
Fut: Future<Output = Result<String, ProfileRefreshError>>,
{
if let Some(version) = fixed_version {
set_codex_cli_version(version).map_err(|_| ProfileRefreshError::InvalidMetadata)?;
return Ok(version.to_owned());
}
if let Err(error) = restore_cached_profile(runtime).await {
// 缓存损坏或暂时不可用不应阻断官方版本检查；当前进程继续使用旧画像。
warn!(
event_name = "codex_client_profile_cache_restore_failed",
error = %error,
"could not restore cached Codex CLI profile"
);
}
if !refresh_is_enabled {
return Ok(codex_client_version());
}
let version = fetch_latest().await?;
let current = codex_client_version();
if version_sequence(&version)? < version_sequence(&current)? {
return Err(ProfileRefreshError::Rollback);
}
let cached = CachedProfile {
version: version.clone(),
verified_at_unix_secs: chrono::Utc::now().timestamp().max(0) as u64,
};
let serialized =
serde_json::to_string(&cached).map_err(|_| ProfileRefreshError::InvalidMetadata)?;
set_codex_cli_version(&version).map_err(|_| ProfileRefreshError::InvalidMetadata)?;
if let Err(error) = runtime
.kv_set(PROFILE_CACHE_KEY, serialized, Some(PROFILE_CACHE_TTL))
.await
{
// 本地画像已经完成原子替换；缓存写失败只影响下次进程启动的恢复。
warn!(
event_name = "codex_client_profile_cache_write_failed",
error = %error,
"published Codex CLI profile locally but could not persist the cache"
);
}
Ok(version)
}
async fn refresh_once(runtime: &RuntimeState) -> Result<String, ProfileRefreshError> {
let fixed_version = fixed_version_override();
refresh_once_with_fetch(
runtime,
fixed_version.as_deref(),
refresh_enabled(),
|| async {
let client = build_release_client()?;
fetch_latest_cli_version(&client).await
},
)
.await
}
pub(crate) async fn prewarm(runtime: &RuntimeState) -> Result<String, String> {
refresh_once(runtime).await.map_err(|err| err.to_string())
}
pub(crate) fn spawn_worker(app: AppState) -> tokio::task::JoinHandle<()> {
crate::task_runtime::spawn_singleton_worker(
app,
crate::task_runtime::TASK_KEY_CODEX_CLIENT_PROFILE,
|app| async move {
let mut interval = tokio::time::interval(PROFILE_REFRESH_INTERVAL);
interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
// 启动阶段由 prewarm 完成一次检查；后台任务只负责后续每日刷新，避免重复建连。
interval.tick().await;
loop {
interval.tick().await;
match refresh_once(app.runtime_state()).await {
Ok(version) => info!(
event_name = "codex_client_profile_refreshed",
version = %version,
"refreshed Codex CLI profile"
),
Err(error) => warn!(
event_name = "codex_client_profile_refresh_failed",
error = %error,
"keeping the previous Codex CLI profile after refresh failure"
),
}
}
},
)
}
#[cfg(test)]
mod tests {
use std::sync::{
atomic::{AtomicBool, Ordering},
Mutex, OnceLock,
};
use std::time::Duration;
use aether_runtime_state::{MemoryRuntimeStateConfig, RuntimeState};
use super::{
cached_version_to_restore, fixed_version_from, parse_cli_release, refresh_enabled_from,
refresh_once_with_fetch, CachedProfile, ProfileRefreshError, PROFILE_CACHE_KEY,
};
use crate::ai_serving::api::{
codex_client_profile, codex_client_version, set_codex_cli_version,
set_codex_client_profile, CodexClientProfile,
};
static PROFILE_TEST_LOCK: OnceLock<Mutex<()>> = OnceLock::new();
struct ProfileRestore(CodexClientProfile);
impl Drop for ProfileRestore {
fn drop(&mut self) {
set_codex_client_profile(self.0.clone());
}
}
fn profile_restore_guard() -> (std::sync::MutexGuard<'static, ()>, ProfileRestore) {
let lock = PROFILE_TEST_LOCK.get_or_init(|| Mutex::new(()));
let guard = lock.lock().expect("profile test lock");
let restore = ProfileRestore(codex_client_profile());
(guard, restore)
}
#[test]
fn accepts_only_one_verified_cli_release_for_all_targets() {
let body = serde_json::json!({
"name": "@openai/codex",
"version": "0.200.1",
"optionalDependencies": {
"@openai/codex-darwin-arm64": "npm:@openai/[email protected]",
"@openai/codex-darwin-x64": "npm:@openai/[email protected]",
"@openai/codex-linux-arm64": "npm:@openai/[email protected]",
"@openai/codex-linux-x64": "npm:@openai/[email protected]",
"@openai/codex-win32-arm64": "npm:@openai/[email protected]",
"@openai/codex-win32-x64": "npm:@openai/[email protected]"
}
});
assert_eq!(
parse_cli_release(&serde_json::to_vec(&body).unwrap()).unwrap(),
"0.200.1"
);
}
#[test]
fn rejects_incomplete_platform_release() {
let body = serde_json::json!({
"name": "@openai/codex",
"version": "0.200.1",
"optionalDependencies": {}
});
assert!(parse_cli_release(&serde_json::to_vec(&body).unwrap()).is_err());
}
#[test]
fn refresh_and_fixed_version_environment_policies_are_strict() {
assert!(!refresh_enabled_from(Some("off")));
assert!(!refresh_enabled_from(Some(" FALSE ")));
assert!(refresh_enabled_from(None));
assert_eq!(
fixed_version_from(Some(" 0.200.1 ")).as_deref(),
Some("0.200.1")
);
assert!(fixed_version_from(Some("0.200.1-beta.1")).is_none());
assert!(fixed_version_from(Some("1.2")).is_none());
}
#[test]
fn cached_profile_never_rewinds_active_profile() {
let cached = CachedProfile {
version: "0.200.1".to_string(),
verified_at_unix_secs: 1,
};
assert_eq!(
cached_version_to_restore(&cached, "0.200.0").unwrap(),
Some("0.200.1".to_string())
);
assert_eq!(cached_version_to_restore(&cached, "0.201.0").unwrap(), None);
}
#[tokio::test]
async fn cache_hit_is_restored_without_network_when_refresh_is_disabled() {
let (_lock, _restore) = profile_restore_guard();
let runtime = RuntimeState::memory(MemoryRuntimeStateConfig::default());
runtime
.kv_set(
PROFILE_CACHE_KEY,
serde_json::to_string(&CachedProfile {
version: "0.200.1".to_string(),
verified_at_unix_secs: 1,
})
.unwrap(),
Some(Duration::from_secs(60)),
)
.await
.unwrap();
let result = refresh_once_with_fetch(&runtime, None, false, || async {
Err(ProfileRefreshError::HttpStatus(599))
})
.await
.unwrap();
assert_eq!(result, "0.200.1");
assert_eq!(codex_client_version(), "0.200.1");
}
#[tokio::test]
async fn refresh_failure_keeps_previous_profile() {
let (_lock, _restore) = profile_restore_guard();
let runtime = RuntimeState::memory(MemoryRuntimeStateConfig::default());
let before = codex_client_profile();
let result = refresh_once_with_fetch(&runtime, None, true, || async {
Err(ProfileRefreshError::HttpStatus(503))
})
.await;
assert!(matches!(result, Err(ProfileRefreshError::HttpStatus(503))));
assert_eq!(codex_client_profile(), before);
}
#[tokio::test]
async fn fixed_version_override_skips_network_and_publishes_profile() {
let (_lock, _restore) = profile_restore_guard();
let runtime = RuntimeState::memory(MemoryRuntimeStateConfig::default());
let fetch_called = AtomicBool::new(false);
let result = refresh_once_with_fetch(&runtime, Some("0.220.0"), true, || async {
fetch_called.store(true, Ordering::SeqCst);
Ok("0.221.0".to_string())
})
.await
.unwrap();
assert_eq!(result, "0.220.0");
assert!(!fetch_called.load(Ordering::SeqCst));
assert_eq!(codex_client_version(), "0.220.0");
}
#[tokio::test]
async fn rollback_is_rejected_without_replacing_profile() {
let (_lock, _restore) = profile_restore_guard();
set_codex_cli_version("0.220.0").unwrap();
let runtime = RuntimeState::memory(MemoryRuntimeStateConfig::default());
let result =
refresh_once_with_fetch(&runtime, None, true, || async { Ok("0.219.9".to_string()) })
.await;
assert!(matches!(result, Err(ProfileRefreshError::Rollback)));
assert_eq!(codex_client_version(), "0.220.0");
}
}
apps/aether-gateway/src/lib.rs
+1 -1
View File
@@ -35,9 +35,9 @@ mod auth;
mod backup;
mod bark_push;
mod cache;
mod cli_client_profile;
mod client_session_affinity;
mod clock;
mod codex_profile;
mod constants;
mod control;
mod data;
apps/aether-gateway/src/main.rs
+20 -1
View File
@@ -2513,7 +2513,12 @@ async fn run() -> Result<(), Box<dyn std::error::Error>> {
);
}
}
match state.prewarm_codex_client_profile().await {
// 两个 CLI 画像的发布检查互不依赖，并发执行以免叠加启动阶段的网络超时。
let (codex_profile, claude_code_profile) = tokio::join!(
state.prewarm_codex_client_profile(),
state.prewarm_claude_code_client_profile(),
);
match codex_profile {
Ok(version) => {
info!(
codex_client_version = %version,
@@ -2527,6 +2532,20 @@ async fn run() -> Result<(), Box<dyn std::error::Error>> {
);
}
}
match claude_code_profile {
Ok(version) => {
info!(
claude_code_client_version = %version,
"prewarmed Claude Code client profile"
);
}
Err(err) => {
warn!(
error = %err,
"failed to refresh Claude Code client profile; built-in or cached profile remains active"
);
}
}
match prewarm_direct_h2c_sender_cache_from_env_for_startup().await {
Ok(Some(report)) => {
if report.failed_targets > 0 {
apps/aether-gateway/src/state/core.rs
+19 -3
View File
@@ -53,7 +53,9 @@ use super::super::router::RequestAdmissionError;
use super::super::{control::GatewayControlDecision, error::GatewayError};
use super::super::{provider_transport, usage};
use crate::codex_profile::spawn_worker as spawn_codex_client_profile_worker;
use crate::cli_client_profile::{
spawn_worker as spawn_cli_client_profile_worker, CLAUDE_CODE_CLI_PROFILE, CODEX_CLI_PROFILE,
};
use crate::maintenance::spawn_account_self_check_worker;
use crate::maintenance::spawn_audit_cleanup_worker;
use crate::maintenance::spawn_db_maintenance_worker;
@@ -150,7 +152,11 @@ fn system_config_key_affects_provider_transport_snapshot(key: &str) -> bool {
impl AppState {
pub async fn prewarm_codex_client_profile(&self) -> Result<String, String> {
crate::codex_profile::prewarm(self.runtime_state()).await
crate::cli_client_profile::prewarm(&CODEX_CLI_PROFILE, self.runtime_state()).await
}
pub async fn prewarm_claude_code_client_profile(&self) -> Result<String, String> {
crate::cli_client_profile::prewarm(&CLAUDE_CODE_CLI_PROFILE, self.runtime_state()).await
}
pub async fn prewarm_chat_pii_redaction_runtime_config(&self) -> Result<bool, String> {
@@ -2349,7 +2355,17 @@ impl AppState {
);
supervise_worker(
crate::task_runtime::TASK_KEY_CODEX_CLIENT_PROFILE,
Some(spawn_codex_client_profile_worker(background_state.clone())),
Some(spawn_cli_client_profile_worker(
&CODEX_CLI_PROFILE,
background_state.clone(),
)),
);
supervise_worker(
crate::task_runtime::TASK_KEY_CLAUDE_CODE_CLIENT_PROFILE,
Some(spawn_cli_client_profile_worker(
&CLAUDE_CODE_CLI_PROFILE,
background_state.clone(),
)),
);
supervise_worker(
crate::task_runtime::TASK_KEY_VIDEO_TASK_POLLER,
apps/aether-gateway/src/task_runtime/mod.rs
+10
View File
@@ -25,6 +25,8 @@ pub(crate) const TASK_KEY_USAGE_COUNTER_FLUSH: &str = "usage.counter.flush.worke
pub(crate) const TASK_KEY_VIDEO_TASK_POLLER: &str = "video.task.poller";
pub(crate) const TASK_KEY_MODEL_FETCH_WORKER: &str = "model.fetch.worker";
pub(crate) const TASK_KEY_CODEX_CLIENT_PROFILE: &str = "maintenance.codex.client.profile";
pub(crate) const TASK_KEY_CLAUDE_CODE_CLIENT_PROFILE: &str =
"maintenance.claude_code.client.profile";
pub(crate) const TASK_KEY_PROVIDER_QUOTA_RESET: &str = "provider.quota.reset.worker";
pub(crate) const TASK_KEY_ACCOUNT_SELF_CHECK: &str = "account.self_check.worker";
pub(crate) const TASK_KEY_POOL_SCORE_REBUILD: &str = "pool.score.rebuild.worker";
@@ -211,6 +213,14 @@ const TASK_DEFINITIONS: &[TaskDefinition] = &[
true,
RETRY_ONCE,
),
TaskDefinition::new(
TASK_KEY_CLAUDE_CODE_CLIENT_PROFILE,
TaskKind::Scheduled,
"daily",
true,
true,
RETRY_ONCE,
),
TaskDefinition::new(
TASK_KEY_PROVIDER_QUOTA_RESET,
TaskKind::Scheduled,
crates/aether-provider/pool/src/providers/claude_code.rs
+1 -2
View File
@@ -11,7 +11,6 @@ use crate::quota_refresh::ProviderPoolQuotaRequestSpec;
pub const CLAUDE_CODE_OAUTH_USAGE_URL: &str =
"https://api.anthropic.com/api/oauth/usage?cedar_ember=1&skip_spend=1";
pub const CLAUDE_CODE_OAUTH_BETA: &str = "oauth-2025-04-20";
pub const CLAUDE_CODE_USAGE_USER_AGENT: &str = "claude-cli/2.1.284 (external, cli)";
#[derive(Debug, Clone, Default)]
pub struct ClaudeCodeProviderPoolAdapter;
@@ -62,7 +61,7 @@ pub fn build_claude_code_pool_quota_request(
("x-app".to_string(), "cli".to_string()),
(
"user-agent".to_string(),
CLAUDE_CODE_USAGE_USER_AGENT.to_string(),
aether_provider_transport::claude_code::claude_code_client_user_agent(),
),
]);
crates/aether-provider/pool/src/providers/mod.rs
-1
View File
@@ -24,7 +24,6 @@ pub use chatgpt_web::{
pub use claude_code::ClaudeCodeProviderPoolAdapter;
pub use claude_code::{
build_claude_code_pool_quota_request, CLAUDE_CODE_OAUTH_BETA, CLAUDE_CODE_OAUTH_USAGE_URL,
CLAUDE_CODE_USAGE_USER_AGENT,
};
pub use codex::CodexProviderPoolAdapter;
pub use codex::{
crates/aether-provider/transport/src/claude_code/fingerprint.rs
+2 -2
View File
@@ -14,7 +14,7 @@ pub fn generate_fingerprint(seed: &str) -> Value {
}
fn generate_header_fingerprint(seed: &str) -> Value {
let profile = *current_claude_code_transport_identity_profile();
let profile = current_claude_code_transport_identity_profile();
let vscode_session_id = Uuid::new_v5(
&Uuid::NAMESPACE_URL,
format!("aether:fingerprint:{seed}").as_bytes(),
@@ -40,7 +40,7 @@ fn generate_header_fingerprint(seed: &str) -> Value {
}
fn wrap_header_fingerprint(header_fingerprint: Value) -> Value {
let profile = *current_claude_code_transport_identity_profile();
let profile = current_claude_code_transport_identity_profile();
serde_json::json!({
"transport_profile": {
"profile_id": profile.transport_profile_id(),
crates/aether-provider/transport/src/claude_code/mimicry.rs
+1 -1
View File
@@ -103,7 +103,7 @@ pub fn apply_claude_code_body_mimicry(
return false;
}
let profile = *current_claude_code_transport_identity_profile();
let profile = current_claude_code_transport_identity_profile();
let model = object
.get("model")
.and_then(Value::as_str)
crates/aether-provider/transport/src/claude_code/mod.rs
+4 -1
View File
@@ -20,8 +20,11 @@ pub use policy::{
supports_local_claude_code_transport_with_network,
};
pub use profile::{
current_claude_code_transport_identity_profile, ClaudeCodeBodyCapabilityGate,
claude_code_client_profile, claude_code_client_user_agent, claude_code_client_version,
current_claude_code_transport_identity_profile, set_claude_code_cli_version,
set_claude_code_client_profile, ClaudeCodeBodyCapabilityGate, ClaudeCodeClientProfile,
ClaudeCodeTransportIdentityProfile, ClaudeCodeTransportIdentityProfileVersion,
ClaudeCodeTransportIdentityTemplate, CLAUDE_CODE_BUILTIN_CLI_VERSION,
CLAUDE_CODE_CONTEXT_MANAGEMENT_BETA, CLAUDE_CODE_TRANSPORT_IDENTITY_2026_04,
};
pub use request::{
crates/aether-provider/transport/src/claude_code/profile.rs
+218 -67
View File
@@ -1,9 +1,14 @@
use std::collections::{BTreeMap, BTreeSet};
use std::sync::{Arc, OnceLock, RwLock};
use aether_ai_formats::ApiOperation;
pub const CLAUDE_CODE_CONTEXT_MANAGEMENT_BETA: &str = "context-management-2025-06-27";
/// Built-in Claude Code CLI version used until the gateway publishes a newer
/// verified release (or when release checks are disabled / unavailable).
pub const CLAUDE_CODE_BUILTIN_CLI_VERSION: &str = "2.1.284";
const MESSAGE_BETAS_2026_04: &[&str] = &[
"claude-code-20250219",
"oauth-2025-04-20",
@@ -53,15 +58,93 @@ pub struct ClaudeCodeBodyCapabilityGate {
pub default_edit_type: Option<&'static str>,
}
/// Versioned upstream identity used when Aether is intentionally acting as a
/// Claude Code transport. Native Anthropic transports never resolve this
/// profile and therefore keep their original headers and body untouched.
/// Dynamic Claude Code CLI identity (version-derived wire values).
///
/// The gateway refreshes this from verified official releases in a background
/// task; request paths only read an immutable snapshot and never touch the
/// network.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ClaudeCodeClientProfile {
pub cli_version: String,
pub user_agent: String,
}
impl ClaudeCodeClientProfile {
/// Builds a CLI profile from a release version. Release verification is owned
/// by the release checker; the constructor only rejects clearly invalid values.
pub fn cli(version: &str) -> Result<Self, &'static str> {
let version = version.trim();
if version.is_empty()
|| version.len() > 64
|| !version.bytes().all(|byte| (33..=126).contains(&byte))
{
return Err("invalid Claude Code CLI version");
}
Ok(Self {
cli_version: version.to_owned(),
user_agent: format!("claude-cli/{version} (external, cli)"),
})
}
}
impl Default for ClaudeCodeClientProfile {
fn default() -> Self {
Self::cli(CLAUDE_CODE_BUILTIN_CLI_VERSION)
.expect("built-in Claude Code CLI profile must be valid")
}
}
static ACTIVE_CLIENT_PROFILE: OnceLock<RwLock<Arc<ClaudeCodeClientProfile>>> = OnceLock::new();
fn active_client_profile() -> &'static RwLock<Arc<ClaudeCodeClientProfile>> {
ACTIVE_CLIENT_PROFILE.get_or_init(|| RwLock::new(Arc::new(ClaudeCodeClientProfile::default())))
}
/// Returns a snapshot of the active CLI profile without holding the global lock.
pub fn claude_code_client_profile() -> Arc<ClaudeCodeClientProfile> {
active_client_profile()
.read()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.clone()
}
/// Atomically replaces the active CLI profile and returns the previous one.
pub fn set_claude_code_client_profile(
profile: ClaudeCodeClientProfile,
) -> Arc<ClaudeCodeClientProfile> {
let mut current = active_client_profile()
.write()
.unwrap_or_else(std::sync::PoisonError::into_inner);
std::mem::replace(&mut *current, Arc::new(profile))
}
/// Publishes a CLI profile for the given release version.
pub fn set_claude_code_cli_version(
version: &str,
) -> Result<Arc<ClaudeCodeClientProfile>, &'static str> {
let profile = ClaudeCodeClientProfile::cli(version)?;
Ok(set_claude_code_client_profile(profile))
}
/// Returns the active Claude Code CLI version.
pub fn claude_code_client_version() -> String {
claude_code_client_profile().cli_version.clone()
}
/// Returns the active Claude Code CLI User-Agent.
pub fn claude_code_client_user_agent() -> String {
claude_code_client_profile().user_agent.clone()
}
/// Versioned, static part of the Claude Code transport identity: Stainless SDK
/// and runtime values, beta policy and body capability gates. These values are
/// calibrated together and change only with a new template version; the CLI
/// version itself is supplied by the dynamic [`ClaudeCodeClientProfile`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ClaudeCodeTransportIdentityProfile {
pub struct ClaudeCodeTransportIdentityTemplate {
version: ClaudeCodeTransportIdentityProfileVersion,
transport_profile_id: &'static str,
anthropic_version: &'static str,
cli_version: &'static str,
stainless_lang: &'static str,
stainless_package_version: &'static str,
stainless_os: &'static str,
@@ -77,12 +160,11 @@ pub struct ClaudeCodeTransportIdentityProfile {
body_capability_gates: &'static [ClaudeCodeBodyCapabilityGate],
}
pub const CLAUDE_CODE_TRANSPORT_IDENTITY_2026_04: ClaudeCodeTransportIdentityProfile =
ClaudeCodeTransportIdentityProfile {
pub const CLAUDE_CODE_TRANSPORT_IDENTITY_2026_04: ClaudeCodeTransportIdentityTemplate =
ClaudeCodeTransportIdentityTemplate {
version: ClaudeCodeTransportIdentityProfileVersion::V2026_04,
transport_profile_id: "claude_code_nodejs",
anthropic_version: "2023-06-01",
cli_version: "2.1.284",
stainless_lang: "js",
stainless_package_version: "0.112.1",
stainless_os: "Linux",
@@ -98,115 +180,139 @@ pub const CLAUDE_CODE_TRANSPORT_IDENTITY_2026_04: ClaudeCodeTransportIdentityPro
body_capability_gates: BODY_CAPABILITY_GATES_2026_04,
};
pub const fn current_claude_code_transport_identity_profile(
) -> &'static ClaudeCodeTransportIdentityProfile {
&CLAUDE_CODE_TRANSPORT_IDENTITY_2026_04
/// Upstream identity used when Aether is intentionally acting as a Claude Code
/// transport. Native Anthropic transports never resolve this profile and
/// therefore keep their original headers and body untouched.
///
/// Each value is one coherent snapshot of the static template plus the active
/// CLI profile, so headers and billing attribution derived from the same
/// snapshot always agree on the CLI version.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ClaudeCodeTransportIdentityProfile {
template: &'static ClaudeCodeTransportIdentityTemplate,
client: Arc<ClaudeCodeClientProfile>,
}
pub fn current_claude_code_transport_identity_profile() -> ClaudeCodeTransportIdentityProfile {
ClaudeCodeTransportIdentityProfile::new(
&CLAUDE_CODE_TRANSPORT_IDENTITY_2026_04,
claude_code_client_profile(),
)
}
impl ClaudeCodeTransportIdentityProfile {
pub const fn version(self) -> ClaudeCodeTransportIdentityProfileVersion {
self.version
pub fn new(
template: &'static ClaudeCodeTransportIdentityTemplate,
client: Arc<ClaudeCodeClientProfile>,
) -> Self {
Self { template, client }
}
pub const fn transport_profile_id(self) -> &'static str {
self.transport_profile_id
pub fn version(&self) -> ClaudeCodeTransportIdentityProfileVersion {
self.template.version
}
pub const fn cli_version(self) -> &'static str {
self.cli_version
pub fn transport_profile_id(&self) -> &'static str {
self.template.transport_profile_id
}
pub const fn billing_cli_version(self) -> &'static str {
self.cli_version
pub fn cli_version(&self) -> &str {
&self.client.cli_version
}
pub fn user_agent(self) -> String {
format!("claude-cli/{} (external, cli)", self.cli_version)
pub fn billing_cli_version(&self) -> &str {
&self.client.cli_version
}
pub const fn stainless_package_version(self) -> &'static str {
self.stainless_package_version
pub fn user_agent(&self) -> &str {
&self.client.user_agent
}
pub const fn stainless_lang(self) -> &'static str {
self.stainless_lang
pub fn stainless_package_version(&self) -> &'static str {
self.template.stainless_package_version
}
pub const fn stainless_os(self) -> &'static str {
self.stainless_os
pub fn stainless_lang(&self) -> &'static str {
self.template.stainless_lang
}
pub const fn stainless_arch(self) -> &'static str {
self.stainless_arch
pub fn stainless_os(&self) -> &'static str {
self.template.stainless_os
}
pub const fn stainless_runtime(self) -> &'static str {
self.stainless_runtime
pub fn stainless_arch(&self) -> &'static str {
self.template.stainless_arch
}
pub const fn stainless_runtime_version(self) -> &'static str {
self.stainless_runtime_version
pub fn stainless_runtime(&self) -> &'static str {
self.template.stainless_runtime
}
pub const fn stainless_retry_count(self) -> &'static str {
self.stainless_retry_count
pub fn stainless_runtime_version(&self) -> &'static str {
self.template.stainless_runtime_version
}
pub const fn stainless_timeout(self) -> &'static str {
self.stainless_timeout
pub fn stainless_retry_count(&self) -> &'static str {
self.template.stainless_retry_count
}
pub fn required_beta_tokens(self, operation: Option<ApiOperation>) -> &'static [&'static str] {
pub fn stainless_timeout(&self) -> &'static str {
self.template.stainless_timeout
}
pub fn required_beta_tokens(&self, operation: Option<ApiOperation>) -> &'static [&'static str] {
if operation == Some(ApiOperation::ClaudeCountTokens) {
self.count_tokens_required_betas
self.template.count_tokens_required_betas
} else {
self.message_required_betas
self.template.message_required_betas
}
}
pub const fn preserves_incoming_betas(self) -> bool {
self.preserve_incoming_betas
pub fn preserves_incoming_betas(&self) -> bool {
self.template.preserve_incoming_betas
}
pub const fn dropped_beta_tokens(self) -> &'static [&'static str] {
self.dropped_betas
pub fn dropped_beta_tokens(&self) -> &'static [&'static str] {
self.template.dropped_betas
}
pub const fn body_capability_gates(self) -> &'static [ClaudeCodeBodyCapabilityGate] {
self.body_capability_gates
pub fn body_capability_gates(&self) -> &'static [ClaudeCodeBodyCapabilityGate] {
self.template.body_capability_gates
}
pub fn body_capability_gate(self, field: &str) -> Option<ClaudeCodeBodyCapabilityGate> {
self.body_capability_gates
pub fn body_capability_gate(&self, field: &str) -> Option<ClaudeCodeBodyCapabilityGate> {
self.template
.body_capability_gates
.iter()
.copied()
.find(|gate| gate.body_field == field)
}
pub fn apply_fixed_headers(self, headers: &mut BTreeMap<String, String>, stream: bool) {
pub fn apply_fixed_headers(&self, headers: &mut BTreeMap<String, String>, stream: bool) {
let template = self.template;
for (name, value) in [
("accept", "application/json"),
("anthropic-version", self.anthropic_version),
("anthropic-version", template.anthropic_version),
("anthropic-dangerous-direct-browser-access", "true"),
("x-app", "cli"),
("x-stainless-lang", self.stainless_lang),
("x-stainless-lang", template.stainless_lang),
(
"x-stainless-package-version",
self.stainless_package_version,
template.stainless_package_version,
),
("x-stainless-os", self.stainless_os),
("x-stainless-arch", self.stainless_arch),
("x-stainless-runtime", self.stainless_runtime),
("x-stainless-os", template.stainless_os),
("x-stainless-arch", template.stainless_arch),
("x-stainless-runtime", template.stainless_runtime),
(
"x-stainless-runtime-version",
self.stainless_runtime_version,
template.stainless_runtime_version,
),
("x-stainless-retry-count", self.stainless_retry_count),
("x-stainless-timeout", self.stainless_timeout),
("x-stainless-retry-count", template.stainless_retry_count),
("x-stainless-timeout", template.stainless_timeout),
] {
headers.insert(name.to_string(), value.to_string());
}
headers.insert("user-agent".to_string(), self.user_agent());
headers.insert("user-agent".to_string(), self.user_agent().to_string());
if stream {
headers.insert(
"x-stainless-helper-method".to_string(),
@@ -218,7 +324,7 @@ impl ClaudeCodeTransportIdentityProfile {
}
pub fn apply_beta_policy(
self,
&self,
headers: &mut BTreeMap<String, String>,
operation: Option<ApiOperation>,
) {
@@ -232,7 +338,7 @@ impl ClaudeCodeTransportIdentityProfile {
}
pub fn merge_beta_tokens(
self,
&self,
incoming: Option<&str>,
operation: Option<ApiOperation>,
) -> String {
@@ -242,7 +348,7 @@ impl ClaudeCodeTransportIdentityProfile {
for token in self.required_beta_tokens(operation) {
self.append_beta_token(&mut seen, &mut merged, token);
}
if self.preserve_incoming_betas {
if self.template.preserve_incoming_betas {
for token in incoming.unwrap_or_default().split(',') {
self.append_beta_token(&mut seen, &mut merged, token);
}
@@ -250,7 +356,7 @@ impl ClaudeCodeTransportIdentityProfile {
merged.join(",")
}
pub fn beta_header_enables_body_field(self, beta_header: &str, field: &str) -> bool {
pub fn beta_header_enables_body_field(&self, beta_header: &str, field: &str) -> bool {
let Some(gate) = self.body_capability_gate(field) else {
return true;
};
@@ -260,10 +366,16 @@ impl ClaudeCodeTransportIdentityProfile {
.any(|token| token.eq_ignore_ascii_case(gate.beta_token))
}
fn append_beta_token(self, seen: &mut BTreeSet<String>, merged: &mut Vec<String>, token: &str) {
fn append_beta_token(
&self,
seen: &mut BTreeSet<String>,
merged: &mut Vec<String>,
token: &str,
) {
let token = token.trim();
if token.is_empty()
|| self
.template
.dropped_betas
.iter()
.any(|dropped| token.eq_ignore_ascii_case(dropped))
@@ -278,12 +390,17 @@ impl ClaudeCodeTransportIdentityProfile {
#[cfg(test)]
mod tests {
use super::current_claude_code_transport_identity_profile;
use std::sync::Arc;
use super::{
current_claude_code_transport_identity_profile, ClaudeCodeClientProfile,
ClaudeCodeTransportIdentityProfile, CLAUDE_CODE_TRANSPORT_IDENTITY_2026_04,
};
use aether_ai_formats::ApiOperation;
#[test]
fn profile_versions_cli_user_agent_stainless_and_billing_together() {
let profile = *current_claude_code_transport_identity_profile();
let profile = current_claude_code_transport_identity_profile();
assert_eq!(profile.version().as_str(), "2026-04");
assert_eq!(profile.cli_version(), "2.1.284");
@@ -296,9 +413,43 @@ mod tests {
assert_eq!(profile.stainless_runtime_version(), "v26.3.0");
}
#[test]
fn cli_profile_derives_wire_identity_from_version() {
let client = ClaudeCodeClientProfile::cli(" 2.1.300 ").expect("valid version");
assert_eq!(client.cli_version, "2.1.300");
assert_eq!(client.user_agent, "claude-cli/2.1.300 (external, cli)");
// A snapshot keeps headers and billing attribution on the same CLI version
// without mutating the process-wide active profile.
let profile = ClaudeCodeTransportIdentityProfile::new(
&CLAUDE_CODE_TRANSPORT_IDENTITY_2026_04,
Arc::new(client),
);
let mut headers = std::collections::BTreeMap::new();
profile.apply_fixed_headers(&mut headers, false);
assert_eq!(
headers.get("user-agent").map(String::as_str),
Some("claude-cli/2.1.300 (external, cli)")
);
assert_eq!(profile.billing_cli_version(), "2.1.300");
assert_eq!(
headers
.get("x-stainless-package-version")
.map(String::as_str),
Some("0.112.1")
);
}
#[test]
fn cli_profile_rejects_empty_or_control_values() {
assert!(ClaudeCodeClientProfile::cli("").is_err());
assert!(ClaudeCodeClientProfile::cli("2.1.0\nspoof").is_err());
assert!(ClaudeCodeClientProfile::cli("2.1.0 spoof").is_err());
}
#[test]
fn profile_preserves_context_1m_and_adds_operation_specific_betas() {
let profile = *current_claude_code_transport_identity_profile();
let profile = current_claude_code_transport_identity_profile();
let messages = profile.merge_beta_tokens(Some("context-1m-2025-08-07,custom"), None);
assert!(messages
crates/aether-provider/transport/src/claude_code/request.rs
+7 -7
View File
@@ -49,7 +49,7 @@ pub fn build_claude_code_passthrough_headers(
out.insert("anthropic-beta".to_string(), incoming_beta_values.join(","));
}
let profile = *current_claude_code_transport_identity_profile();
let profile = current_claude_code_transport_identity_profile();
profile.apply_fixed_headers(&mut out, stream);
profile.apply_beta_policy(&mut out, None);
@@ -57,15 +57,15 @@ pub fn build_claude_code_passthrough_headers(
}
pub fn sanitize_claude_code_request_body(body: &mut Value) {
let profile = *current_claude_code_transport_identity_profile();
let profile = current_claude_code_transport_identity_profile();
let beta_header = profile.merge_beta_tokens(None, None);
sanitize_claude_code_request_body_for_beta_header(body, &beta_header, profile);
sanitize_claude_code_request_body_for_beta_header(body, &beta_header, &profile);
}
pub fn sanitize_claude_code_request_body_for_beta_header(
body: &mut Value,
beta_header: &str,
profile: ClaudeCodeTransportIdentityProfile,
profile: &ClaudeCodeTransportIdentityProfile,
) {
let Some(body_object) = body.as_object_mut() else {
return;
@@ -303,7 +303,7 @@ mod tests {
#[test]
fn context_management_body_is_gated_by_the_matching_beta_token() {
let profile = *current_claude_code_transport_identity_profile();
let profile = current_claude_code_transport_identity_profile();
let original = json!({
"context_management": {
"edits": [{"type":"clear_thinking_20251015", "keep":"all"}]
@@ -315,7 +315,7 @@ mod tests {
sanitize_claude_code_request_body_for_beta_header(
&mut without_beta,
"oauth-2025-04-20",
profile,
&profile,
);
assert!(without_beta.get("context_management").is_none());
@@ -323,7 +323,7 @@ mod tests {
sanitize_claude_code_request_body_for_beta_header(
&mut with_beta,
"oauth-2025-04-20, context-management-2025-06-27",
profile,
&profile,
);
assert_eq!(with_beta, original);
}
crates/aether-provider/transport/src/network.rs
+1 -1
View File
@@ -177,7 +177,7 @@ fn resolve_claude_code_transport_profile(
return None;
}
let identity_profile = *current_claude_code_transport_identity_profile();
let identity_profile = current_claude_code_transport_identity_profile();
Some(ResolvedTransportProfile {
profile_id: identity_profile.transport_profile_id().to_string(),
backend: TRANSPORT_BACKEND_REQWEST_RUSTLS.to_string(),
crates/aether-provider/transport/src/same_format_provider/mod.rs
+1 -1
View File
@@ -812,7 +812,7 @@ pub fn build_same_format_provider_headers(
} else {
replace_upstream_auth_headers(&mut provider_request_headers, "", "");
}
let claude_code_profile = *current_claude_code_transport_identity_profile();
let claude_code_profile = current_claude_code_transport_identity_profile();
if input.behavior.is_claude_code_transport {
claude_code_profile.apply_fixed_headers(
&mut provider_request_headers,