fix(openai): preserve Claude Messages session affinity (#712)

Resolve explicit Claude session identities before account selection and
revalidate them after attempt middleware using the existing affinity policy.

Co-authored-by: Zyy <zyycn@users.noreply.github.com>
Co-authored-by: Codex <noreply@openai.com>
This commit is contained in:
Zyy
2026-11-14 17:22:03 +08:00
committed by GitHub
co-authored by Zyy Codex
parent 41f97ac836
commit a0e7f38f7f
13 changed files with 483 additions and 23 deletions
@@ -4,6 +4,7 @@ use axum::{
body::{Body, to_bytes},
http::{Request, StatusCode},
};
use base64::{Engine as _, engine::general_purpose::STANDARD};
use bytes::Bytes;
use futures::{StreamExt as _, future::BoxFuture};
use gateway_core::{
@@ -122,10 +123,12 @@ async fn native_json_preserves_extensions_and_uses_client_key_authentication() {
)]);
let trace = session.trace.clone();
let (router, execution) = fixture(session).await;
let response = router
.oneshot(request("/v1/messages", false))
.await
.unwrap();
let mut incoming = request("/v1/messages", false);
incoming.headers_mut().insert(
"x-claude-code-session-id",
"claude-session".parse().unwrap(),
);
let response = router.oneshot(incoming).await.unwrap();
assert_eq!(response.status(), StatusCode::OK);
let bytes = to_bytes(response.into_body(), usize::MAX).await.unwrap();
assert_eq!(bytes, raw);
@@ -136,6 +139,15 @@ async fn native_json_preserves_extensions_and_uses_client_key_authentication() {
panic!("generate")
};
assert_eq!(generation.protocol_payload().protocol(), "anthropic");
assert!(
generation.protocol_payload().context()["opaque_request_headers"]
.as_array()
.unwrap()
.contains(&json!([
"x-claude-code-session-id",
STANDARD.encode("claude-session")
]))
);
assert_eq!(
generation.protocol_payload().body()["future_extension"]["preserved"],
true
@@ -5,6 +5,7 @@ mod content;
mod error;
mod request;
mod response;
mod session;
mod stream;
mod thinking;
mod tools;
@@ -20,6 +21,7 @@ pub use request::{
pub use response::{
messages_to_responses_event, messages_to_responses_response, responses_to_messages_response,
};
pub use session::claude_session_id;
pub use stream::{
MessagesAccumulator, MessagesToResponsesStream, ResponsesToMessagesStream,
message_to_stream_events,
@@ -0,0 +1,36 @@
//! Claude Code 明确会话身份的请求头与 metadata 解析
use serde_json::{Map, Value};
/// 优先使用 Claude Code 会话头,再读取新旧 metadata.user_id 中的会话标识
///
/// 普通用户标识与对话内容不作为会话身份
#[must_use]
pub fn claude_session_id(body: &Map<String, Value>, header: Option<&str>) -> Option<String> {
if let Some(session) = header.and_then(valid_session_id) {
return Some(session.to_owned());
}
let user_id = body.get("metadata")?.get("user_id")?.as_str()?.trim();
if user_id.starts_with('{') {
let metadata: Value = serde_json::from_str(user_id).ok()?;
return metadata
.get("session_id")?
.as_str()
.and_then(valid_session_id)
.map(str::to_owned);
}
let (_, session) = user_id.rsplit_once("_session_")?;
let session = valid_session_id(session)?;
session
.bytes()
.all(|byte| byte.is_ascii_hexdigit() || byte == b'-')
.then(|| session.to_owned())
}
fn valid_session_id(value: &str) -> Option<&str> {
if value.chars().any(char::is_control) {
return None;
}
let value = value.trim();
(!value.is_empty() && value.len() <= 256).then_some(value)
}
@@ -3,5 +3,6 @@
mod capabilities;
mod request;
mod response;
mod session;
mod stream;
mod usage;
@@ -0,0 +1,69 @@
//! Claude Code 会话来源优先级、格式兼容与无效身份边界
use gateway_protocol::anthropic::claude_session_id;
use serde_json::json;
#[test]
fn explicit_claude_sessions_follow_header_then_metadata() {
let session = "12345678-1234-1234-1234-123456789abc";
for (header, user_id, expected) in [
(
Some(" header-session "),
json!("{\"session_id\":\"body-session\"}"),
Some("header-session"),
),
(
None,
json!("{\"device_id\":\"device\",\"session_id\":\"body-session\"}"),
Some("body-session"),
),
(
None,
json!(format!("user_device_account__session_{session}")),
Some(session),
),
(
Some(""),
json!(format!("user_{}_session_{session}", "x".repeat(300))),
Some(session),
),
(None, json!("ordinary-user-id"), None),
(None, json!("{\"device_id\":\"device\"}"), None),
(None, json!("{invalid}"), None),
(None, json!({"session_id":"not-a-string"}), None),
(None, json!("user_device_session_"), None),
(None, json!("user_device_session_not-a-uuid"), None),
] {
let body =
json!({"metadata":{"user_id":user_id},"messages":[{"role":"user","content":"hello"}]});
assert_eq!(
claude_session_id(body.as_object().unwrap(), header).as_deref(),
expected
);
}
}
#[test]
fn invalid_session_signals_do_not_bind_users_or_message_content() {
for invalid in [String::new(), "x".repeat(257), "bad\nidentity".to_owned()] {
let body = json!({"metadata":{"user_id":json!({"session_id":invalid}).to_string()}});
assert_eq!(
claude_session_id(body.as_object().unwrap(), Some(&invalid)),
None
);
let fallback = json!({"metadata":{"user_id":"{\"session_id\":\"valid-fallback\"}"}});
assert_eq!(
claude_session_id(fallback.as_object().unwrap(), Some(&invalid)).as_deref(),
Some("valid-fallback")
);
}
assert_eq!(
claude_session_id(
json!({"messages":[{"role":"user","content":"same opening"}]})
.as_object()
.unwrap(),
None
),
None
);
}
@@ -1,6 +1,6 @@
//! 逻辑会话账号绑定与线程传输隔离键的单向派生
use gateway_core::operation::RawJsonPayload;
use gateway_core::operation::{ProtocolPayload, RawJsonPayload};
use gateway_core::policy::ClientApiKeyId;
use gateway_core::provider_ports::{ProviderSessionAffinityKey, ProviderSessionAlias};
use serde_json::{Map, Value};
@@ -148,6 +148,38 @@ pub(crate) fn derive_codex_session_affinity(
.map(|affinity| affinity.with_follow_only(request.client_account_follow_only))
}
/// Messages 的会话只参与账号绑定,不解释为 OpenAI 轮次或原生续接身份
pub(crate) fn derive_messages_session_affinity(
payload: &ProtocolPayload,
headers: &[gateway_core::engine::middleware::MiddlewareHeader],
client_api_key_id: &ClientApiKeyId,
) -> Option<CodexSessionAffinity> {
if payload.protocol() != gateway_protocol::anthropic::ANTHROPIC_PROTOCOL {
return None;
}
let passthrough = crate::transport::request::decode_passthrough_headers(payload.context());
let header = headers
.iter()
.find(|header| {
header
.name()
.eq_ignore_ascii_case("x-claude-code-session-id")
})
.map(|header| std::str::from_utf8(header.value()).ok())
.unwrap_or_else(|| {
passthrough
.get("x-claude-code-session-id")
.and_then(|value| value.to_str().ok())
});
let session = gateway_protocol::anthropic::claude_session_id(payload.body(), header)?;
session_affinity(
"claude-session",
&session,
Some(&session),
client_api_key_id,
)
}
/// 仅供选号使用。缓存键与输入正文均不作为会话、轮次或传输身份。
pub(crate) fn derive_cache_preference(
request: &CodexResponsesRequest,
@@ -22,7 +22,8 @@ pub(crate) use affinity::{
CodexSessionAffinity, derive_cache_preference, derive_codex_cyber_policy_session_key,
derive_codex_endpoint_session_affinity, derive_codex_session_affinity,
derive_codex_transport_key, derive_endpoint_affinity_with_headers,
derive_live_session_affinity, derive_previous_response_id_hash, derive_turn_alias,
derive_live_session_affinity, derive_messages_session_affinity,
derive_previous_response_id_hash, derive_turn_alias,
};
pub(crate) use eligibility::CodexSelectionModel;
pub(crate) use oauth::oauth_owner_ref;
@@ -30,6 +30,26 @@ impl CodexProvider {
if !matches!(source, OPENAI_PROTOCOL | ANTHROPIC_PROTOCOL) {
return Err(invalid_request());
}
if !context.is_diagnostic_required_account()
&& (source == ANTHROPIC_PROTOCOL
|| selected.lease.authentication().api_protocol() == ApiKeyProtocol::Messages)
{
// attempt 改写后的身份必须在跨协议转换前复验,避免绕过已有账号绑定
let affinity = crate::credential::derive_messages_session_affinity(
generate.protocol_payload(),
&headers,
context.client_api_key_ref(),
);
self.selector
.validate_translated_selection(
&mut selected.lease,
affinity.as_ref(),
None,
context.account_selection_policy(),
)
.await
.map_err(map_selection_error)?;
}
if selected.lease.authentication().api_protocol() == ApiKeyProtocol::Messages {
if context.continuation_attempt() == ContinuationAttempt::Native
|| generate.provider_session_state(PROVIDER_NAME).is_some()
@@ -124,21 +144,10 @@ impl CodexProvider {
selected: SelectedGenerate,
) -> Result<ProviderStream, ProviderError> {
let SelectedGenerate {
mut lease,
lease,
account_selection_wait_ms,
..
} = selected;
if !context.is_diagnostic_required_account() {
self.selector
.validate_translated_selection(
&mut lease,
None,
None,
context.account_selection_policy(),
)
.await
.map_err(map_selection_error)?;
}
self.messages_stream(
body,
source_context,
@@ -673,8 +673,7 @@ impl Provider for CodexProvider {
{
return Err(continuation_replay_required_error("scope_unavailable"));
}
// 其他协议必须先取得真实账号,再按固定 attempt 阶段调用转换器;选号前不能
// 把未知正文当成 OpenAI wire 解释会话、亲和或传输字段
// 跨协议转换必须在选号后执行;选号前只按各自协议读取明确会话身份
let upstream = (generate.protocol_payload().protocol() == OPENAI_PROTOCOL)
.then(|| encode_generate_request(generate, upstream_model.as_str(), None))
.transpose()
@@ -726,10 +725,16 @@ impl Provider for CodexProvider {
requires_websocket,
)
});
// 内容亲和只交给选号器;中间件复验、轮次关联和原生续接仍只认真实会话
let messages_affinity = crate::credential::derive_messages_session_affinity(
generate.protocol_payload(),
&[],
context.client_api_key_ref(),
);
// Messages 身份与内容亲和仅交给选号器,不建立 OpenAI 轮次或原生续接关联
let account_affinity = selection_session_affinity
.as_ref()
.or(cache_preference.as_ref());
.or(cache_preference.as_ref())
.or(messages_affinity.as_ref());
let selection_started_at = Instant::now();
let selection = async {
self.selector
@@ -0,0 +1,284 @@
//! Messages 会话在原生与 Responses 上游的选号、隔离和最终身份复验
use super::*;
use gateway_core::account::AccountAffinity;
const SESSION: &str = "12345678-1234-1234-1234-123456789abc";
fn operation(header: Option<&str>, user_id: Value) -> Operation {
let body = json!({"model":"gpt-5.4", "max_tokens":128, "stream":true,
"metadata":{"user_id":user_id}, "messages":[{"role":"user","content":"hello"}]});
let mut context = Map::new();
if let Some(header) = header {
context.insert(
"opaque_request_headers".to_owned(),
json!([["x-claude-code-session-id", STANDARD.encode(header)]]),
);
}
Operation::Generate(GenerateRequest::from_protocol_payload(
ProtocolPayload::json_object("anthropic", body.as_object().unwrap().clone())
.unwrap()
.with_context(context),
))
}
fn attempt(client: &str) -> AttemptContext {
AttemptContext::new(
RequestAttemptContext::new(
ModelRequestId::new("req_messages_affinity").unwrap(),
ClientApiKeyId::new(client).unwrap(),
),
NonZeroU32::MIN,
SystemTime::now() + Duration::from_secs(5),
account_policy()
.with_openai_account_affinity(AccountAffinity::Strict)
.with_queue(gateway_core::concurrency::ConcurrencyQueuePolicy {
max_waiting: 1,
timeout: Duration::from_secs(2),
}),
AccountAttemptContext::new(BTreeSet::new(), None, None)
.with_account_scope(contract_account_scope()),
None,
CancellationToken::new(),
)
}
async fn fixture(
native_messages: bool,
) -> (
MockServer,
Arc<CodexProvider>,
Arc<MemorySessionAffinity>,
Arc<TestLeaseCoordinator>,
) {
let server = MockServer::start().await;
Mock::given(method("POST"))
.and(path(if native_messages {
"/messages"
} else {
"/codex/responses"
}))
.respond_with(ResponseTemplate::new(200).set_body_raw(
if native_messages {
MESSAGES_SSE
} else {
CAPTURE_COMPLETED_SSE
},
"text/event-stream",
))
.mount(&server)
.await;
let store = Arc::new(MemoryAccountStore::default());
for id in ["acct_affinity_switch_a", "acct_affinity_switch_b"] {
if native_messages {
store
.seed_api_key_for_protocol(
id,
server.uri(),
ResponsesTransport::Http,
ApiKeyProtocol::Messages,
)
.await;
} else {
create_account(&store, id).await;
store.set_oauth_transport(id, ResponsesTransport::Http);
}
}
let affinity = Arc::new(MemorySessionAffinity::default());
let leases = Arc::new(TestLeaseCoordinator::default());
let provider = provider_with_affinity_and_base_url_and_leases(
&store,
affinity.clone(),
server.uri(),
leases.clone(),
);
(server, provider, affinity, leases)
}
#[tokio::test]
async fn claude_sessions_keep_accounts_across_identity_formats_and_isolate_client_keys() {
for native_messages in [false, true] {
let (server, provider, affinity, _) = fixture(native_messages).await;
let mut selected = Vec::new();
let mut keys = Vec::new();
for (client, header, user_id) in [
(
"key_openai_contract",
Some(SESSION),
json!("{\"session_id\":\"ignored-body-session\"}"),
),
(
"key_openai_contract",
None,
json!(json!({"session_id":SESSION}).to_string()),
),
(
"key_openai_contract",
None,
json!(format!("user_device_account__session_{SESSION}")),
),
("different-client", Some(SESSION), json!("ordinary-user")),
(
"key_openai_contract",
Some("different-session"),
json!("ordinary-user"),
),
] {
let before = affinity.lookup_keys().len();
let mut stream = provider
.clone()
.execute(
planned_request("openai", operation(header, user_id)),
attempt(client),
)
.await
.unwrap();
selected.push(stream.metadata().provider_account_id().clone());
keys.push(affinity.lookup_keys()[before].clone());
while let Some(event) = stream.next().await {
event.unwrap();
}
}
assert!(selected[..3].iter().all(|account| account == &selected[0]));
assert!(keys[..3].iter().all(|key| key == &keys[0]));
assert_ne!(keys[3], keys[0]);
assert_ne!(keys[4], keys[0]);
assert_eq!(affinity.binding_count(), 3);
assert!(
affinity.alias_ttls().is_empty(),
"Claude sessions must not create OpenAI turn aliases"
);
let before = affinity.lookup_keys().len();
drop(
provider
.clone()
.execute(
planned_request("openai", operation(None, json!("ordinary-user"))),
attempt("key_openai_contract"),
)
.await
.unwrap(),
);
assert_eq!(
affinity.lookup_keys().len(),
before,
"ordinary users and message text do not identify sessions"
);
assert_eq!(server.received_requests().await.unwrap().len(), 5);
}
}
#[tokio::test]
async fn messages_strict_affinity_does_not_send_to_an_idle_alternate_when_bound_account_is_busy() {
let (server, provider, affinity, leases) = fixture(false).await;
let request = || planned_request("openai", operation(Some(SESSION), json!("user")));
let first = provider
.clone()
.execute(request(), attempt("key_openai_contract"))
.await
.unwrap();
let bound = first.metadata().provider_account_id().clone();
drop(first);
leases.busy_accounts.lock().unwrap().insert(bound.clone());
let context = attempt("key_openai_contract");
let cancellation = context.cancellation().clone();
let pending = tokio::spawn(provider.execute(request(), context));
tokio::time::timeout(Duration::from_secs(1), async {
while leases.requests.lock().unwrap().len() < 2 {
tokio::task::yield_now().await;
}
})
.await
.unwrap();
cancellation.cancel();
assert!(pending.await.unwrap().is_err());
assert!(
leases
.requests
.lock()
.unwrap()
.iter()
.all(|request| request.account_id() == &bound)
);
assert_eq!(affinity.binding_count(), 1);
assert!(server.received_requests().await.unwrap().is_empty());
}
#[derive(Debug)]
struct ChangeClaudeSession;
impl MiddlewarePlan for ChangeClaudeSession {
fn handle(
&self,
_: MiddlewareContext,
request: MiddlewareRequest,
next: MiddlewareNext,
) -> BoxFuture<'static, Result<MiddlewareResponse, MiddlewareError>> {
Box::pin(async move {
let protocol = request.protocol().to_owned();
let body = request.body().clone();
let mut headers = request.headers().to_vec();
headers.push(MiddlewareHeader::new(
"x-claude-code-session-id",
Bytes::from_static(b"other-session"),
));
next.run(request.replace_parts(protocol, headers, body, None)?)
.await
})
}
}
#[tokio::test]
async fn rewritten_claude_session_cannot_bypass_another_accounts_binding() {
for native_messages in [false, true] {
let (server, provider, affinity, _) = fixture(native_messages).await;
drop(
provider
.clone()
.execute(
planned_request("openai", operation(Some(SESSION), json!("user"))),
attempt("key_openai_contract"),
)
.await
.unwrap(),
);
let key = affinity.lookup_keys()[0].clone();
affinity.seed_binding(
&ProviderKind::new("openai").unwrap(),
&key,
ProviderAccountId::new("acct_affinity_switch_a").unwrap(),
);
drop(
provider
.clone()
.execute(
planned_request("openai", operation(Some("other-session"), json!("user"))),
attempt("key_openai_contract"),
)
.await
.unwrap(),
);
let other = affinity.lookup_keys().last().unwrap().clone();
affinity.seed_binding(
&ProviderKind::new("openai").unwrap(),
&other,
ProviderAccountId::new("acct_affinity_switch_b").unwrap(),
);
let result = provider
.execute(
planned_request("openai", operation(Some(SESSION), json!("user"))),
context_with_middleware(
"req_rewritten_claude_session",
Arc::new(ChangeClaudeSession),
FastMode::Default,
),
)
.await;
let error = result
.err()
.expect("conflicting final identity must fail before sending");
assert_eq!(error.send_state(), UpstreamSendState::NotSent);
assert!(server.received_requests().await.unwrap().is_empty());
}
}
@@ -1,5 +1,7 @@
//! Messages 原生 wire、跨协议头隔离和本地计数合同
mod affinity;
use super::*;
use gateway_core::event::ProviderResponseTimings;
use gateway_core::operation::TokenCountRequest;
+6 -1
View File
@@ -354,6 +354,11 @@ Responses 上游使用 `$.input`,Messages 上游使用 `$.messages`
`stream` 缺省或 `false` 返回 JSON,`true` 返回 SSE。每轮由客户端携带所需的完整上下文。Claude Code 用 `--resume` 恢复本地会话后,仍通过 `messages` 发送上下文;网关不缓存对话正文用于下一轮。
Messages 没有服务端历史续接或 WebSocket 入口
Messages 生成请求通过 OpenAI Provider 选号时,优先使用 `x-claude-code-session-id` 识别 Claude Code 会话,
缺少有效头部时读取 `metadata.user_id` JSON 字符串中的 `session_id` 或旧格式 `_session_<id>` 后缀。
会话标识最长 256 字节,不接受控制字符;普通用户标识和对话内容不用于绑定账号。
同一 Client Key 下的会话沿用[账号亲和与换号](#账号亲和与换号)设置,转向 Responses 上游时也适用
```bash
curl https://gateway.example.com/v1/messages \
-H "x-api-key: ${CPR_CLIENT_KEY}" \
@@ -2299,7 +2304,7 @@ Guardian 以 `subagent_kind` 或 `client_metadata.x-openai-subagent` 值 `guardi
### 账号亲和与换号
`openaiAccountAffinity` 控制 Codex 账号亲和,默认 `strict`(严格):
`openaiAccountAffinity` 控制 OpenAI Provider 的账号亲和,包括带明确 Claude Code 会话身份的 [Messages 请求](#messages-请求),默认 `strict`(严格):
- `relaxed`(宽松):会话内请求直接按 `rotationStrategy` 选号,不优先主账号
- `preferred`(优先)优先使用会话主账号,短时满载、限流或模型不匹配时临时分流,后备按同一会话的稳定顺序参与既有调度
+2
View File
@@ -733,6 +733,8 @@ OpenAI 固定归属请求直接读取目标账号,其余请求按冻结的账
Store 只保存带版本的绑定事实,Provider 在取得租约后、发送前原子认领、续期或按模式迁移;快照冲突释放租约并重新选择。
首次认领不依赖根线程先发请求,独立后台任务也使用自身会话绑定。
Messages 的 Claude Code 明确会话身份由 `gateway-protocol::anthropic` 解析,OpenAI Provider 在选号前按 Client Key 派生独立命名空间的亲和键,
沿用现有绑定与调度策略;原生执行在 attempt 改写后、协议转换前复验身份,不建立 OpenAI 轮次关联或原生续接归属。
OpenAI Provider 对无显式会话的 Responses 和 Chat Completions 入站请求,可按客户端缓存键或对话开头形成账号亲和。Messages 入站请求不按对话内容绑定账号。
亲和键按 Client Key 隔离,与会话键使用不同命名空间,不建立轮次关联或原生续接归属。
内容亲和存储不可用时,优先模式按普通调度继续选号,严格模式停止发送。