diff --git a/backend/crates/gateway-api/src/openai/router.rs b/backend/crates/gateway-api/src/openai/router.rs index 2e7ce6f81..dd78faad0 100644 --- a/backend/crates/gateway-api/src/openai/router.rs +++ b/backend/crates/gateway-api/src/openai/router.rs @@ -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"; diff --git a/backend/crates/gateway-api/tests/openai/responses/http.rs b/backend/crates/gateway-api/tests/openai/responses/http.rs index a0ead7144..689264729 100644 --- a/backend/crates/gateway-api/tests/openai/responses/http.rs +++ b/backend/crates/gateway-api/tests/openai/responses/http.rs @@ -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::(&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")); } diff --git a/backend/crates/gateway-core/src/engine/coordinator.rs b/backend/crates/gateway-core/src/engine/coordinator.rs index 26e05fd17..2a6d413a2 100644 --- a/backend/crates/gateway-core/src/engine/coordinator.rs +++ b/backend/crates/gateway-core/src/engine/coordinator.rs @@ -2057,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?, )); diff --git a/backend/crates/gateway-core/src/engine/execution/delivery.rs b/backend/crates/gateway-core/src/engine/execution/delivery.rs index dfb6c7851..d7564b6b7 100644 --- a/backend/crates/gateway-core/src/engine/execution/delivery.rs +++ b/backend/crates/gateway-core/src/engine/execution/delivery.rs @@ -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] diff --git a/backend/crates/gateway-core/src/engine/mod.rs b/backend/crates/gateway-core/src/engine/mod.rs index 430a041af..55ee67f38 100644 --- a/backend/crates/gateway-core/src/engine/mod.rs +++ b/backend/crates/gateway-core/src/engine/mod.rs @@ -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 { diff --git a/backend/crates/gateway-core/src/error/mod.rs b/backend/crates/gateway-core/src/error/mod.rs index 45beb14d1..70c546a65 100644 --- a/backend/crates/gateway-core/src/error/mod.rs +++ b/backend/crates/gateway-core/src/error/mod.rs @@ -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() diff --git a/backend/crates/gateway-core/tests/engine/coordinator.rs b/backend/crates/gateway-core/tests/engine/coordinator.rs index ffe265484..82de66541 100644 --- a/backend/crates/gateway-core/tests/engine/coordinator.rs +++ b/backend/crates/gateway-core/tests/engine/coordinator.rs @@ -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(); diff --git a/backend/crates/gateway-protocol/src/openai/mod.rs b/backend/crates/gateway-protocol/src/openai/mod.rs index 9835ca96e..f9bd520d3 100644 --- a/backend/crates/gateway-protocol/src/openai/mod.rs +++ b/backend/crates/gateway-protocol/src/openai/mod.rs @@ -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"; diff --git a/backend/crates/providers/openai/src/provider/execution.rs b/backend/crates/providers/openai/src/provider/execution.rs index 0ae472996..17b455a68 100644 --- a/backend/crates/providers/openai/src/provider/execution.rs +++ b/backend/crates/providers/openai/src/provider/execution.rs @@ -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, diff --git a/backend/crates/providers/openai/src/provider/failure.rs b/backend/crates/providers/openai/src/provider/failure.rs index 0c8e86613..b096b6000 100644 --- a/backend/crates/providers/openai/src/provider/failure.rs +++ b/backend/crates/providers/openai/src/provider/failure.rs @@ -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, + 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, diff --git a/backend/crates/providers/openai/tests/provider/contract/precommit.rs b/backend/crates/providers/openai/tests/provider/contract/precommit.rs index 629092173..4a6aff3db 100644 --- a/backend/crates/providers/openai/tests/provider/contract/precommit.rs +++ b/backend/crates/providers/openai/tests/provider/contract/precommit.rs @@ -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::(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] { diff --git a/docs/api.md b/docs/api.md index 876f55e07..7b80d0fac 100644 --- a/docs/api.md +++ b/docs/api.md @@ -780,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`,供客户端读取;错误对象已有有效重试头时优先保留