Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

chore(ai-gateway): enforce panic-free and suppression lints (#18880)

Tobias Wochingeree7f4624f93b
diff --git a/ai-gateway/AGENTS.md b/ai-gateway/AGENTS.md
index ce3c804d86..90297443f8 100644
--- a/ai-gateway/AGENTS.md
+++ b/ai-gateway/AGENTS.md
@@ -1,5 +1,16 @@
# Agent Guidelines for `ai-gateway`
+## Lints
+
+- Lint policy lives in `Cargo.toml` (`[lints]`) and `clippy.toml`; verify with
+ `pnpm --filter ai-gateway run lint`.
+- Suppress a lint only with `#[expect(lint, reason = "...")]` on the narrowest
+ item. `#[allow]` is denied.
+- Production code must not panic: no `unwrap`, `expect`, `panic!`, `todo!`, or
+ `print!`/`eprintln!`. Recover poisoned locks with
+ `PoisonError::into_inner`; tests are exempt.
+- Default to `pub(crate)` inside private modules; `unreachable_pub` warns.
+
## Method naming
- Getters stay nouns or `is_` / `has_`: `id()`, `attribution()`, `is_ready()`.
diff --git a/ai-gateway/Cargo.toml b/ai-gateway/Cargo.toml
index 8d16d2ff39..c48fa1fc3f 100644
--- a/ai-gateway/Cargo.toml
+++ b/ai-gateway/Cargo.toml
@@ -38,11 +38,34 @@ prost = "0.14"
tokio = { version = "1.53.1", features = ["io-util", "test-util"] }
tower = { version = "0.5", features = ["util"] }
+[lints.rust]
+unsafe_code = "forbid"
+unreachable_pub = "warn"
+unused_qualifications = "warn"
+
[lints.clippy]
pedantic = { level = "warn", priority = -1 }
# Avoid requiring annotations on every side-effect-free getter.
must_use_candidate = "allow"
+# Suppressions must use `#[expect(lint, reason = "...")]` so stale ones fail.
+allow_attributes = "deny"
+allow_attributes_without_reason = "deny"
+
+# Request paths must not panic; tests are exempted in clippy.toml.
+unwrap_used = "deny"
+expect_used = "deny"
+panic = "deny"
+todo = "deny"
+unimplemented = "deny"
+dbg_macro = "deny"
+print_stdout = "deny"
+print_stderr = "deny"
+
+await_holding_lock = "deny"
+rc_buffer = "deny"
+rc_mutex = "deny"
+
[profile.release]
lto = "thin"
strip = true
diff --git a/ai-gateway/clippy.toml b/ai-gateway/clippy.toml
new file mode 100644
index 0000000000..82a664d8a1
--- /dev/null
+++ b/ai-gateway/clippy.toml
@@ -0,0 +1,5 @@
+allow-unwrap-in-tests = true
+allow-expect-in-tests = true
+allow-panic-in-tests = true
+allow-dbg-in-tests = true
+allow-print-in-tests = true
diff --git a/ai-gateway/src/capture/anthropic_messages.rs b/ai-gateway/src/capture/anthropic_messages.rs
index 7a7f44f450..3de2db0539 100644
--- a/ai-gateway/src/capture/anthropic_messages.rs
+++ b/ai-gateway/src/capture/anthropic_messages.rs
@@ -205,7 +205,7 @@ fn block_index(event: &Map<String, Value>) -> Option<u64> {
}
impl AnthropicMessagesCapture {
- pub fn new(headers: &HeaderMap, body: &[u8], mode: IngestionMode) -> Self {
+ pub(super) fn new(headers: &HeaderMap, body: &[u8], mode: IngestionMode) -> Self {
let mut capture = Self {
facts: ProviderFacts::default(),
mode,
@@ -229,7 +229,7 @@ impl AnthropicMessagesCapture {
capture
}
- pub fn record_response(&mut self, headers: &HeaderMap) {
+ pub(super) fn record_response(&mut self, headers: &HeaderMap) {
self.facts.provider_request_id = headers
.get("request-id")
.and_then(|v| v.to_str().ok())
@@ -240,7 +240,7 @@ impl AnthropicMessagesCapture {
}
}
- pub fn push_bytes(&mut self, bytes: &[u8]) -> bool {
+ pub(super) fn push_bytes(&mut self, bytes: &[u8]) -> bool {
let mut body = std::mem::replace(&mut self.body, ResponseBody::Unavailable);
let mut completion_started = false;
if !body.push(bytes, |event| {
@@ -252,7 +252,7 @@ impl AnthropicMessagesCapture {
completion_started
}
- pub fn end_body(&mut self) {
+ pub(super) fn end_body(&mut self) {
match std::mem::replace(&mut self.body, ResponseBody::Unavailable) {
ResponseBody::Json(bytes) => match serde_json::from_slice::<Value>(&bytes) {
Ok(Value::Object(response)) => {
@@ -280,7 +280,7 @@ impl AnthropicMessagesCapture {
self.facts.capture_complete = self.request_complete && self.facts.output_complete;
}
- pub fn into_facts(mut self) -> ProviderFacts {
+ pub(super) fn into_facts(mut self) -> ProviderFacts {
if matches!(self.body, ResponseBody::Sse(_)) {
self.end_body();
}
diff --git a/ai-gateway/src/capture/mod.rs b/ai-gateway/src/capture/mod.rs
index ca95bc8349..c05a039ada 100644
--- a/ai-gateway/src/capture/mod.rs
+++ b/ai-gateway/src/capture/mod.rs
@@ -106,7 +106,7 @@ pub(crate) struct ExecutionCapture {
}
impl ExecutionCapture {
- pub fn unobserved() -> Self {
+ pub(crate) fn unobserved() -> Self {
Self {
span: tracing::Span::current(),
protocol: None,
@@ -124,7 +124,7 @@ impl ExecutionCapture {
}
}
- pub fn for_request(
+ pub(crate) fn for_request(
api_format: ApiFormat,
context: &ResolvedRequestContext,
headers: &HeaderMap,
@@ -180,7 +180,7 @@ impl ExecutionCapture {
}
}
- pub fn deliver_to(
+ pub(crate) fn deliver_to(
&mut self,
telemetry: telemetry::Telemetry,
context: &ResolvedRequestContext,
@@ -200,18 +200,18 @@ impl ExecutionCapture {
self.delivery = Some((telemetry, delivery));
}
- pub fn set_provider_model(&mut self, model: &str) {
+ pub(crate) fn set_provider_model(&mut self, model: &str) {
self.provider_model = bounded_string(model);
}
- pub fn record_response(&mut self, status: u16, headers: &HeaderMap) {
+ pub(crate) fn record_response(&mut self, status: u16, headers: &HeaderMap) {
if let Some(protocol) = &mut self.protocol {
self.http_status = Some(status);
protocol.record_response(headers);
}
}
- pub fn push_bytes(&mut self, bytes: &[u8]) {
+ pub(crate) fn push_bytes(&mut self, bytes: &[u8]) {
if let Some(protocol) = &mut self.protocol {
if !bytes.is_empty() {
self.first_byte_ms
@@ -224,13 +224,13 @@ impl ExecutionCapture {
}
}
- pub fn end_body(&mut self) {
+ pub(crate) fn end_body(&mut self) {
if let Some(protocol) = &mut self.protocol {
protocol.end_body();
}
}
- pub fn finish(&mut self, outcome: RelayOutcome) {
+ pub(crate) fn finish(&mut self, outcome: RelayOutcome) {
let span = self.span.clone();
let _entered = span.enter();
let Some(protocol) = self.protocol.take() else {
diff --git a/ai-gateway/src/capture/openai_chat_completions.rs b/ai-gateway/src/capture/openai_chat_completions.rs
index bb29946883..84fc8c2f56 100644
--- a/ai-gateway/src/capture/openai_chat_completions.rs
+++ b/ai-gateway/src/capture/openai_chat_completions.rs
@@ -272,7 +272,7 @@ fn has_generated_content(delta: &Map<String, Value>) -> bool {
}
impl OpenAiChatCompletionsCapture {
- pub fn new(headers: &HeaderMap, body: &[u8], mode: IngestionMode) -> Self {
+ pub(super) fn new(headers: &HeaderMap, body: &[u8], mode: IngestionMode) -> Self {
let mut capture = Self {
facts: ProviderFacts::default(),
mode,
@@ -295,7 +295,7 @@ impl OpenAiChatCompletionsCapture {
capture
}
- pub fn record_response(&mut self, headers: &HeaderMap) {
+ pub(super) fn record_response(&mut self, headers: &HeaderMap) {
self.facts.provider_request_id = headers
.get("x-request-id")
.and_then(|v| v.to_str().ok())
@@ -306,7 +306,7 @@ impl OpenAiChatCompletionsCapture {
}
}
- pub fn push_bytes(&mut self, bytes: &[u8]) -> bool {
+ pub(super) fn push_bytes(&mut self, bytes: &[u8]) -> bool {
let mut body = std::mem::replace(&mut self.body, ResponseBody::Unavailable);
let mut completion_started = false;
if !body.push(bytes, |event| {
@@ -318,7 +318,7 @@ impl OpenAiChatCompletionsCapture {
completion_started
}
- pub fn end_body(&mut self) {
+ pub(super) fn end_body(&mut self) {
match std::mem::replace(&mut self.body, ResponseBody::Unavailable) {
ResponseBody::Json(bytes) => match serde_json::from_slice::<Value>(&bytes) {
Ok(Value::Object(response)) => {
@@ -341,7 +341,7 @@ impl OpenAiChatCompletionsCapture {
self.facts.capture_complete = self.request_complete && self.facts.output_complete;
}
- pub fn into_facts(mut self) -> ProviderFacts {
+ pub(super) fn into_facts(mut self) -> ProviderFacts {
if matches!(self.body, ResponseBody::Sse(_)) {
self.end_body();
}
diff --git a/ai-gateway/src/capture/openai_responses.rs b/ai-gateway/src/capture/openai_responses.rs
index 5270cf489e..4259918673 100644
--- a/ai-gateway/src/capture/openai_responses.rs
+++ b/ai-gateway/src/capture/openai_responses.rs
@@ -22,7 +22,7 @@ pub(super) struct OpenAiResponsesCapture {
}
impl OpenAiResponsesCapture {
- pub fn new(headers: &HeaderMap, body: &[u8], mode: IngestionMode) -> Self {
+ pub(super) fn new(headers: &HeaderMap, body: &[u8], mode: IngestionMode) -> Self {
let mut capture = Self {
facts: ProviderFacts::default(),
mode,
@@ -48,7 +48,7 @@ impl OpenAiResponsesCapture {
capture
}
- pub fn record_response(&mut self, headers: &HeaderMap) {
+ pub(super) fn record_response(&mut self, headers: &HeaderMap) {
self.facts.provider_request_id = headers
.get("x-request-id")
.and_then(|v| v.to_str().ok())
@@ -59,7 +59,7 @@ impl OpenAiResponsesCapture {
}
}
- pub fn push_bytes(&mut self, bytes: &[u8]) -> bool {
+ pub(super) fn push_bytes(&mut self, bytes: &[u8]) -> bool {
let mut body = std::mem::replace(&mut self.body, ResponseBody::Unavailable);
let mut completion_started = false;
if !body.push(bytes, |event| {
@@ -71,7 +71,7 @@ impl OpenAiResponsesCapture {
completion_started
}
- pub fn end_body(&mut self) {
+ pub(super) fn end_body(&mut self) {
match std::mem::replace(&mut self.body, ResponseBody::Unavailable) {
ResponseBody::Json(bytes) => match serde_json::from_slice::<Value>(&bytes) {
Ok(Value::Object(response)) => {
@@ -100,7 +100,7 @@ impl OpenAiResponsesCapture {
self.facts.capture_complete = self.request_complete && self.facts.output_complete;
}
- pub fn into_facts(mut self) -> ProviderFacts {
+ pub(super) fn into_facts(mut self) -> ProviderFacts {
if matches!(self.body, ResponseBody::Sse(_)) {
self.end_body();
}
@@ -111,7 +111,7 @@ impl OpenAiResponsesCapture {
}
/// The coding agent's `client_metadata` object removed from the request, if any.
- pub fn client_metadata(&self) -> Option<&Map<String, Value>> {
+ pub(super) fn client_metadata(&self) -> Option<&Map<String, Value>> {
self.client_metadata.as_ref()
}
diff --git a/ai-gateway/src/capture/openai_responses/tests.rs b/ai-gateway/src/capture/openai_responses/tests.rs
index 173fd4dc6e..dcc45fc962 100644
--- a/ai-gateway/src/capture/openai_responses/tests.rs
+++ b/ai-gateway/src/capture/openai_responses/tests.rs
@@ -725,10 +725,10 @@ async fn client_compression_preferences_do_not_disable_capture() {
}
})
.await;
- let telemetry = crate::telemetry::Telemetry::new(
+ let telemetry = telemetry::Telemetry::new(
&crate::resolution::ControlPlaneConfig::new(&collector.url, "test-service-key")
.unwrap(),
- crate::telemetry::DEFAULT_RETAINED_BYTES,
+ telemetry::DEFAULT_RETAINED_BYTES,
)
.unwrap();
let context = resolved_request_context_with_mode("provider-secret", "full").await;
@@ -799,9 +799,9 @@ async fn codex_body_metadata_reaches_the_generation_without_agent_headers() {
}
})
.await;
- let telemetry = crate::telemetry::Telemetry::new(
+ let telemetry = telemetry::Telemetry::new(
&crate::resolution::ControlPlaneConfig::new(&collector.url, "test-service-key").unwrap(),
- crate::telemetry::DEFAULT_RETAINED_BYTES,
+ telemetry::DEFAULT_RETAINED_BYTES,
)
.unwrap();
let context = resolved_request_context_with_mode("provider-secret", "full").await;
diff --git a/ai-gateway/src/capture/sse.rs b/ai-gateway/src/capture/sse.rs
index e749b25639..341a68edcd 100644
--- a/ai-gateway/src/capture/sse.rs
+++ b/ai-gateway/src/capture/sse.rs
@@ -17,7 +17,7 @@ enum EventState {
}
impl SseDecoder {
- pub fn push(&mut self, bytes: &[u8], limit: usize, mut event: impl FnMut(&[u8])) {
+ pub(super) fn push(&mut self, bytes: &[u8], limit: usize, mut event: impl FnMut(&[u8])) {
for &byte in bytes {
if self.skip_lf {
self.skip_lf = false;
@@ -67,7 +67,7 @@ impl SseDecoder {
self.line_nonempty = false;
}
- pub fn finish(&self) -> bool {
+ pub(super) fn finish(&self) -> bool {
!self.incomplete
&& !self.line_nonempty
&& self.data.is_empty()
diff --git a/ai-gateway/src/correlation.rs b/ai-gateway/src/correlation.rs
index 6416e7583f..681bb1cbf3 100644
--- a/ai-gateway/src/correlation.rs
+++ b/ai-gateway/src/correlation.rs
@@ -48,7 +48,7 @@ pub(crate) struct UpstreamTarget {
}
impl UpstreamTarget {
- pub fn for_connection(connection: &ProviderConnection, model: Option<String>) -> Self {
+ pub(crate) fn for_connection(connection: &ProviderConnection, model: Option<String>) -> Self {
Self {
provider: connection.provider().as_str(),
connection_id: connection.id().to_owned(),
@@ -84,7 +84,7 @@ impl Default for RequestCorrelation {
impl RequestCorrelation {
/// Always a fresh ID; a caller's `x-request-id` is kept only as a separate value.
- pub fn from_headers(headers: &HeaderMap) -> Self {
+ pub(crate) fn from_headers(headers: &HeaderMap) -> Self {
let mut values = headers.get_all(CLIENT_REQUEST_ID_HEADER).iter();
let client_id = match (values.next(), values.next()) {
(Some(value), None) => value
@@ -107,19 +107,19 @@ impl RequestCorrelation {
}
}
- pub fn id(&self) -> &str {
+ pub(crate) fn id(&self) -> &str {
&self.id
}
- pub fn client_id(&self) -> Option<&str> {
+ pub(crate) fn client_id(&self) -> Option<&str> {
self.client_id.as_deref()
}
- pub fn record_generation(&mut self, ids: GenerationIds) {
+ pub(crate) fn record_generation(&mut self, ids: GenerationIds) {
self.generation = Some(ids);
}
- pub fn record_resolution(&mut self, context: &ResolvedRequestContext) {
+ pub(crate) fn record_resolution(&mut self, context: &ResolvedRequestContext) {
let attribution = context.attribution();
self.server_span
.record("langfuse.organization.id", attribution.organization_id());
@@ -131,7 +131,7 @@ impl RequestCorrelation {
});
}
- pub fn record_upstream(&mut self, target: UpstreamTarget) {
+ pub(crate) fn record_upstream(&mut self, target: UpstreamTarget) {
let span = &self.server_span;
span.record("gateway.provider", target.provider);
span.record(
@@ -149,7 +149,7 @@ impl RequestCorrelation {
/// Only a resolved request advertises its tenant, and only a request sent
/// upstream its provider. The connection name and model stay out of responses.
- pub fn apply_resolution_headers(&self, headers: &mut HeaderMap) {
+ pub(crate) fn apply_resolution_headers(&self, headers: &mut HeaderMap) {
let Some(tenant) = &self.tenant else {
return;
};
@@ -169,7 +169,7 @@ impl RequestCorrelation {
}
/// Only a request that will produce a Langfuse generation advertises its IDs.
- pub fn apply_generation_headers(&self, headers: &mut HeaderMap) {
+ pub(crate) fn apply_generation_headers(&self, headers: &mut HeaderMap) {
let Some(generation) = &self.generation else {
return;
};
@@ -194,6 +194,7 @@ pub(crate) async fn assign_request_id(mut request: Request, next: Next) -> Respo
span.record("gateway.client.request.id", client_id);
}
correlation.server_span = span;
+ #[expect(clippy::expect_used, reason = "the gateway-generated UUID is ASCII")]
let value = HeaderValue::from_str(correlation.id()).expect("a UUID is a valid header value");
request.extensions_mut().insert(correlation);
let mut response = next.run(request).await;
diff --git a/ai-gateway/src/http/tests.rs b/ai-gateway/src/http/tests.rs
index 2af78d842e..1c25ce91e5 100644
--- a/ai-gateway/src/http/tests.rs
+++ b/ai-gateway/src/http/tests.rs
@@ -387,7 +387,7 @@ fn request_id(response: &reqwest::Response) -> String {
/// A request that never reaches the provider has no generation, and names only
/// its tenant, and only if it was resolved.
-fn assert_pre_upstream_headers(headers: &reqwest::header::HeaderMap, resolved: bool) {
+fn assert_pre_upstream_headers(headers: &HeaderMap, resolved: bool) {
assert!(!headers.contains_key("langfuse-trace-id"));
assert!(!headers.contains_key("langfuse-observation-id"));
for name in ["langfuse-organization-id", "langfuse-project-id"] {
diff --git a/ai-gateway/src/main.rs b/ai-gateway/src/main.rs
index 8fdacd8e27..bc52e0e640 100644
--- a/ai-gateway/src/main.rs
+++ b/ai-gateway/src/main.rs
@@ -10,6 +10,10 @@ use ai_gateway::{
use tokio::net::TcpListener;
#[tokio::main]
+#[expect(
+ clippy::print_stderr,
+ reason = "the tracing subscriber may not exist or may already be shut down"
+)]
async fn main() -> ExitCode {
match run().await {
Ok(()) => ExitCode::SUCCESS,
@@ -110,7 +114,7 @@ async fn bind_listener(
}
#[cfg(unix)]
-fn shutdown_signal() -> std::io::Result<impl Future<Output = ()> + Send> {
+fn shutdown_signal() -> io::Result<impl Future<Output = ()> + Send> {
use tokio::signal::unix::{SignalKind, signal};
let mut terminate = signal(SignalKind::terminate())?;
let mut interrupt = signal(SignalKind::interrupt())?;
diff --git a/ai-gateway/src/observability/client.rs b/ai-gateway/src/observability/client.rs
index 94150c5676..a37f27a248 100644
--- a/ai-gateway/src/observability/client.rs
+++ b/ai-gateway/src/observability/client.rs
@@ -88,7 +88,7 @@ mod tests {
#[tokio::test]
async fn middleware_preserves_safe_context_and_sanitizes_transport_errors() {
- opentelemetry::global::set_text_map_propagator(TraceContextPropagator::new());
+ global::set_text_map_propagator(TraceContextPropagator::new());
let exporter = InMemorySpanExporter::default();
let provider = SdkTracerProvider::builder()
.with_simple_exporter(exporter.clone())
diff --git a/ai-gateway/src/providers/tests.rs b/ai-gateway/src/providers/tests.rs
index 5699269b16..cce2497bd7 100644
--- a/ai-gateway/src/providers/tests.rs
+++ b/ai-gateway/src/providers/tests.rs
@@ -72,7 +72,7 @@ async fn invalid_model_rewrite_never_reaches_the_provider() {
Bytes::from_static(br#"{"model":"requested"}"#),
100..110,
Route::OpenAiResponses,
- &mut crate::correlation::RequestCorrelation::default(),
+ &mut RequestCorrelation::default(),
)
.await;
@@ -701,7 +701,7 @@ async fn compact_posts_compact_path_and_captures_ingestion() {
Bytes::from_static(COMPACT),
model_range(COMPACT).unwrap(),
Route::OpenAiResponsesCompact,
- &mut crate::correlation::RequestCorrelation::default(),
+ &mut RequestCorrelation::default(),
)
.await
.unwrap();
@@ -906,7 +906,7 @@ async fn sends_the_x_api_key_credential_and_forwards_the_open_anthropic_header_f
Bytes::from_static(REQUEST),
model_range(REQUEST).unwrap(),
Route::AnthropicMessages,
- &mut crate::correlation::RequestCorrelation::default(),
+ &mut RequestCorrelation::default(),
)
.await
.unwrap();
@@ -960,7 +960,7 @@ async fn count_tokens_relays_the_body() {
Bytes::from_static(br#"{"model":"claude-sonnet-4-5","messages":[]}"#),
model_range(br#"{"model":"claude-sonnet-4-5","messages":[]}"#).unwrap(),
Route::AnthropicCountTokens,
- &mut crate::correlation::RequestCorrelation::default(),
+ &mut RequestCorrelation::default(),
)
.await
.unwrap();
@@ -1078,7 +1078,7 @@ async fn chat_completions_streams_request_usage_and_relay_the_usage_chunk() {
Bytes::from_static(request.as_bytes()),
model_range(request.as_bytes()).unwrap(),
Route::OpenAiChatCompletions,
- &mut crate::correlation::RequestCorrelation::default(),
+ &mut RequestCorrelation::default(),
)
.await
.unwrap();
@@ -1126,7 +1126,7 @@ async fn chat_completions_rewrite_non_streamed_models() {
Bytes::from_static(JSON_REQUEST.as_bytes()),
model_range(JSON_REQUEST.as_bytes()).unwrap(),
Route::OpenAiChatCompletions,
- &mut crate::correlation::RequestCorrelation::default(),
+ &mut RequestCorrelation::default(),
)
.await
.unwrap();
diff --git a/ai-gateway/src/resolution/signing.rs b/ai-gateway/src/resolution/signing.rs
index 776314d920..24eb3eb847 100644
--- a/ai-gateway/src/resolution/signing.rs
+++ b/ai-gateway/src/resolution/signing.rs
@@ -5,7 +5,7 @@ use std::fmt::Write;
pub(crate) fn authorization(service_key: &str, credential: &str, timestamp: u64) -> String {
let key_hash = lowercase_hex(&Sha256::digest(credential.as_bytes()));
let payload = format!("gateway-web-v1\n{timestamp}\n{key_hash}");
- // HMAC accepts keys of any length.
+ #[expect(clippy::expect_used, reason = "HMAC accepts keys of any length")]
let mut mac = Hmac::<Sha256>::new_from_slice(service_key.as_bytes()).expect("valid HMAC key");
mac.update(payload.as_bytes());
let signature = lowercase_hex(&mac.finalize().into_bytes());
@@ -15,6 +15,7 @@ pub(crate) fn authorization(service_key: &str, credential: &str, timestamp: u64)
fn lowercase_hex(bytes: &[u8]) -> String {
let mut encoded = String::with_capacity(bytes.len() * 2);
for byte in bytes {
+ #[expect(clippy::expect_used, reason = "writing to a String cannot fail")]
write!(encoded, "{byte:02x}").expect("writing to String cannot fail");
}
encoded
diff --git a/ai-gateway/src/resolution/tests.rs b/ai-gateway/src/resolution/tests.rs
index f457b504d0..e4ff61615f 100644
--- a/ai-gateway/src/resolution/tests.rs
+++ b/ai-gateway/src/resolution/tests.rs
@@ -85,7 +85,7 @@ impl FakeWeb {
)]
fn response(value: Value) -> Response<Body> {
Response::builder()
- .header(header::CONTENT_TYPE, "application/json")
+ .header(CONTENT_TYPE, "application/json")
.body(Body::from(value.to_string()))
.unwrap()
}
@@ -119,8 +119,8 @@ async fn signs_the_exact_key_and_sends_api_format_and_model() {
let web = FakeWeb::start(|request| async move {
assert_eq!(request.method(), "POST");
assert_eq!(request.uri(), "/api/internal/ai-gateway/v1/resolve");
- assert_eq!(request.headers()[header::AUTHORIZATION], "Bearer gw_test_alice");
- assert_eq!(request.headers()[header::CONTENT_TYPE], "application/json");
+ assert_eq!(request.headers()[AUTHORIZATION], "Bearer gw_test_alice");
+ assert_eq!(request.headers()[CONTENT_TYPE], "application/json");
assert_eq!(request.headers()["langfuse-gateway-request-id"], REQUEST_ID);
assert_eq!(request.headers()["langfuse-gateway-authorization"],
"HMAC timestamp=1800000000,signature=e104b6baa50d9b766b036e27876683aa1f4bff7f31bb6af66dce6b636a53b2bd");
@@ -182,10 +182,7 @@ async fn fetches_models_from_the_control_plane() {
request.uri(),
"/api/internal/ai-gateway/v1/models?api_format=openai.responses"
);
- assert_eq!(
- request.headers()[header::AUTHORIZATION],
- "Bearer gw_test_alice"
- );
+ assert_eq!(request.headers()[AUTHORIZATION], "Bearer gw_test_alice");
assert!(
request
.headers()
@@ -448,7 +445,7 @@ async fn rejects_a_grant_that_expires_while_resolving_across_a_second_boundary()
#[tokio::test]
async fn concurrent_resolutions_keep_credentials_and_contexts_isolated() {
let web = FakeWeb::start(|request| async move {
- let key = request.headers()[header::AUTHORIZATION].to_str().unwrap();
+ let key = request.headers()[AUTHORIZATION].to_str().unwrap();
match key {
"Bearer gw_test_alice" => {
tokio::time::sleep(Duration::from_millis(20)).await;
diff --git a/ai-gateway/src/server.rs b/ai-gateway/src/server.rs
index 70e82dcdf8..616f59cc8e 100644
--- a/ai-gateway/src/server.rs
+++ b/ai-gateway/src/server.rs
@@ -2,7 +2,7 @@ use std::{
future::{Future, IntoFuture},
io,
sync::{
- Arc, Mutex,
+ Arc, Mutex, PoisonError,
atomic::{AtomicBool, Ordering},
},
time::Duration,
@@ -21,14 +21,11 @@ pub struct GatewayLifecycleState {
impl GatewayLifecycleState {
/// Deadline shared by connection draining and telemetry delivery.
- ///
- /// # Panics
- /// Panics if the lifecycle lock was poisoned.
pub fn drain_deadline(&self) -> Option<tokio::time::Instant> {
*self
.drain_deadline
.lock()
- .expect("gateway drain lock poisoned")
+ .unwrap_or_else(PoisonError::into_inner)
}
pub fn is_ready(&self) -> bool {
@@ -79,9 +76,6 @@ async fn readiness(State(state): State<GatewayLifecycleState>) -> (StatusCode, J
/// # Errors
/// Returns the server's I/O error, or [`io::ErrorKind::TimedOut`] if connections
/// do not finish draining within `shutdown_timeout`.
-///
-/// # Panics
-/// Panics if the lifecycle lock was poisoned.
pub async fn serve(
listener: TcpListener,
app: Router,
@@ -98,7 +92,7 @@ pub async fn serve(
*shutdown_state
.drain_deadline
.lock()
- .expect("gateway drain lock poisoned") =
+ .unwrap_or_else(PoisonError::into_inner) =
Some(tokio::time::Instant::now() + shutdown_timeout);
tracing::info!("gateway draining");
let _ = draining_tx.send(());
diff --git a/ai-gateway/src/telemetry/batch.rs b/ai-gateway/src/telemetry/batch.rs
index 42ba72faf3..f90bccd676 100644
--- a/ai-gateway/src/telemetry/batch.rs
+++ b/ai-gateway/src/telemetry/batch.rs
@@ -38,7 +38,7 @@ pub(super) struct Pending {
}
impl Pending {
- pub fn new(
+ pub(super) fn new(
span: Value,
bytes: usize,
link: SpanContext,
@@ -104,14 +104,14 @@ pub(super) struct Batches {
}
impl Batches {
- pub fn new(policy: BatchPolicy) -> Self {
+ pub(super) fn new(policy: BatchPolicy) -> Self {
Self {
policy,
open: HashMap::new(),
}
}
- pub fn push_record(&mut self, grant: Grant, item: Pending, now: Instant) -> Vec<Flush> {
+ pub(super) fn push_record(&mut self, grant: Grant, item: Pending, now: Instant) -> Vec<Flush> {
let mut ready = Vec::new();
let project = grant.project_id.clone();
if self
@@ -148,21 +148,21 @@ impl Batches {
ready
}
- pub fn take_due(&mut self, now: Instant) -> Vec<Flush> {
+ pub(super) fn take_due(&mut self, now: Instant) -> Vec<Flush> {
self.open
.extract_if(|_, batch| batch.due <= now)
.map(|(_, batch)| batch.into_flush())
.collect()
}
- pub fn take_all(&mut self) -> Vec<Flush> {
+ pub(super) fn take_all(&mut self) -> Vec<Flush> {
self.open
.drain()
.map(|(_, batch)| batch.into_flush())
.collect()
}
- pub fn next_due(&self) -> Option<Instant> {
+ pub(super) fn next_due(&self) -> Option<Instant> {
self.open.values().map(|batch| batch.due).min()
}
diff --git a/ai-gateway/src/telemetry/context.rs b/ai-gateway/src/telemetry/context.rs
index bcf2fc195a..1e67b58625 100644
--- a/ai-gateway/src/telemetry/context.rs
+++ b/ai-gateway/src/telemetry/context.rs
@@ -120,13 +120,16 @@ pub(super) struct GenerationContext {
impl GenerationContext {
#[cfg(test)]
- pub fn from_headers(headers: &HeaderMap) -> Self {
+ pub(super) fn from_headers(headers: &HeaderMap) -> Self {
Self::from_request(headers, None)
}
/// `client_metadata` is the request body's agent metadata object, already
/// removed from the captured input by [`take_agent_client_metadata`].
- pub fn from_request(headers: &HeaderMap, client_metadata: Option<&Map<String, Value>>) -> Self {
+ pub(super) fn from_request(
+ headers: &HeaderMap,
+ client_metadata: Option<&Map<String, Value>>,
+ ) -> Self {
let ids = RandomIdGenerator::default();
let mut result = Self {
trace_id: ids.new_trace_id().to_string(),
@@ -145,8 +148,8 @@ impl GenerationContext {
return result;
}
let mut trace_headers = HeaderMap::new();
- if let Some(value) = single_header(headers, "traceparent") {
- trace_headers.insert("traceparent", value.parse().expect("existing header value"));
+ if let Some(Ok(value)) = single_header(headers, "traceparent").map(str::parse) {
+ trace_headers.insert("traceparent", value);
}
// W3C tracestate is a list and may span multiple HTTP header fields.
let trace_state = headers
@@ -155,10 +158,9 @@ impl GenerationContext {
.filter_map(|value| value.to_str().ok())
.collect::<Vec<_>>()
.join(",");
- trace_headers.insert(
- "tracestate",
- trace_state.parse().expect("existing header values"),
- );
+ if let Ok(value) = trace_state.parse() {
+ trace_headers.insert("tracestate", value);
+ }
let context = TraceContextPropagator::new()
.extract_with_context(&Context::new(), &HeaderExtractor(&trace_headers));
let parent = context.span();
diff --git a/ai-gateway/src/telemetry/mod.rs b/ai-gateway/src/telemetry/mod.rs
index e0442de8c8..b6d0f8d5c2 100644
--- a/ai-gateway/src/telemetry/mod.rs
+++ b/ai-gateway/src/telemetry/mod.rs
@@ -9,7 +9,7 @@ mod worker;
use std::{
io::{self, Write},
sync::{
- Arc, Mutex,
+ Arc, Mutex, PoisonError,
atomic::{AtomicU64, Ordering},
},
time::{Duration, SystemTime, UNIX_EPOCH},
@@ -67,7 +67,7 @@ pub(crate) struct DeliveryContext {
}
impl DeliveryContext {
- pub fn from_resolved(
+ pub(crate) fn from_resolved(
context: &ResolvedRequestContext,
headers: &HeaderMap,
client_metadata: Option<&Map<String, Value>>,
@@ -82,7 +82,7 @@ impl DeliveryContext {
}
}
- pub fn generation_ids(&self) -> crate::correlation::GenerationIds {
+ pub(crate) fn generation_ids(&self) -> crate::correlation::GenerationIds {
crate::correlation::GenerationIds {
trace_id: self.generation.trace_id.clone(),
observation_id: self.generation.observation_id.clone(),
@@ -198,9 +198,8 @@ impl Telemetry {
let credentials = context.grant.access_token.len() + context.grant.project_id.len();
let limit = self.0.record_limit.saturating_sub(credentials);
let acquire = |bytes: usize| {
- self.0.retained.clone().try_acquire_many_owned(
- u32::try_from(bytes + credentials).expect("bounded record bytes"),
- )
+ let permits = u32::try_from(bytes + credentials).ok()?;
+ self.0.retained.clone().try_acquire_many_owned(permits).ok()
};
let mut size = serialized_size(&span, limit);
if size.is_none() && mapping::omit_input(&mut span, InputOmissionReason::RecordLimit) {
@@ -210,13 +209,13 @@ impl Telemetry {
self.0.stats.record_dropped(1, "size");
return;
};
- let mut retained = acquire(bytes).ok();
+ let mut retained = acquire(bytes);
if retained.is_none()
&& mapping::omit_input(&mut span, InputOmissionReason::TelemetryBuffer)
&& let Some(reduced) = serialized_size(&span, limit)
{
bytes = reduced;
- retained = acquire(bytes).ok();
+ retained = acquire(bytes);
}
let Some(retained) = retained else {
self.0.stats.record_dropped(1, "bytes");
@@ -232,15 +231,12 @@ impl Telemetry {
/// Stop accepting work, flush open batches, and finish uploads within the existing
/// process drain deadline.
- ///
- /// # Panics
- /// Panics if the worker handle lock was poisoned.
pub async fn shutdown(&self, deadline: Instant) {
let worker = self
.0
.worker
.lock()
- .expect("telemetry worker lock poisoned")
+ .unwrap_or_else(PoisonError::into_inner)
.take();
let Some(worker) = worker else {
return;
diff --git a/ai-gateway/src/telemetry/otlp.rs b/ai-gateway/src/telemetry/otlp.rs
index 0d7667e8e3..06af3b430e 100644
--- a/ai-gateway/src/telemetry/otlp.rs
+++ b/ai-gateway/src/telemetry/otlp.rs
@@ -41,7 +41,7 @@ pub(super) enum ExportError {
}
impl ExportError {
- pub fn reason(&self) -> &'static str {
+ pub(super) fn reason(&self) -> &'static str {
match self {
Self::Expired => "expired_grant",
Self::Payload => "payload",
@@ -52,7 +52,7 @@ impl ExportError {
}
}
- pub fn is_transient(&self) -> bool {
+ pub(super) fn is_transient(&self) -> bool {
match self {
Self::Transport => true,
Self::Rejected { status, .. } => matches!(status, 408 | 429 | 500 | 502 | 503 | 504),
@@ -60,7 +60,7 @@ impl ExportError {
}
}
- pub fn retry_after(&self) -> Option<Duration> {
+ pub(super) fn retry_after(&self) -> Option<Duration> {
match self {
Self::Rejected { retry_after, .. } => *retry_after,
_ => None,
@@ -69,7 +69,7 @@ impl ExportError {
}
impl Uploader {
- pub fn new(config: &ControlPlaneConfig) -> Result<Self, ResolutionError> {
+ pub(super) fn new(config: &ControlPlaneConfig) -> Result<Self, ResolutionError> {
let client = Client::builder()
.redirect(reqwest::redirect::Policy::none())
.retry(reqwest::retry::never())
@@ -90,7 +90,7 @@ impl Uploader {
})
}
- pub async fn export(&self, grant: &Grant, payload: &Payload) -> Result<(), ExportError> {
+ pub(super) async fn export(&self, grant: &Grant, payload: &Payload) -> Result<(), ExportError> {
let now = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map_err(|_| ExportError::Expired)?;
@@ -176,7 +176,7 @@ impl Uploader {
pub(super) struct Payload(Bytes);
impl Payload {
- pub fn encode(spans: &[impl Serialize]) -> Result<Self, ExportError> {
+ pub(super) fn encode(spans: &[impl Serialize]) -> Result<Self, ExportError> {
let payload = json!({"resourceSpans": [{
"resource": {"attributes": [{"key": "service.name", "value": {"stringValue": "langfuse-ai-gateway"}}]},
"scopeSpans": [{"scope": {"name": "langfuse-ai-gateway", "version": env!("CARGO_PKG_VERSION")}, "spans": spans}]
diff --git a/ai-gateway/src/telemetry/retry.rs b/ai-gateway/src/telemetry/retry.rs
index b338e0a921..2ce95c25e1 100644
--- a/ai-gateway/src/telemetry/retry.rs
+++ b/ai-gateway/src/telemetry/retry.rs
@@ -20,7 +20,7 @@ impl Default for RetryPolicy {
}
impl RetryPolicy {
- pub fn backoff(
+ pub(super) fn backoff(
&self,
attempt: u32,
error: &ExportError,
diff --git a/ai-gateway/src/telemetry/tests.rs b/ai-gateway/src/telemetry/tests.rs
index 0247943d2a..f8979d3e52 100644
--- a/ai-gateway/src/telemetry/tests.rs
+++ b/ai-gateway/src/telemetry/tests.rs
@@ -224,7 +224,7 @@ async fn upload_response_failures_are_classified_per_attempt() {
}
// Streaming without Content-Length must obey the response bound too.
let web = FakeServer::start(|_| async move {
- let chunks = futures_util::stream::iter([Ok::<_, std::io::Error>(vec![b' '; 65 * 1024])]);
+ let chunks = futures_util::stream::iter([Ok::<_, io::Error>(vec![b' '; 65 * 1024])]);
response(200, Body::from_stream(chunks))
})
.await;
diff --git a/ai-gateway/src/telemetry/worker.rs b/ai-gateway/src/telemetry/worker.rs
index 321380608c..753bf6465b 100644
--- a/ai-gateway/src/telemetry/worker.rs
+++ b/ai-gateway/src/telemetry/worker.rs
@@ -65,7 +65,12 @@ pub(super) struct Uploads {
}
impl Uploads {
- pub fn new(uploader: Uploader, slots: usize, retry: RetryPolicy, stats: Arc<Stats>) -> Self {
+ pub(super) fn new(
+ uploader: Uploader,
+ slots: usize,
+ retry: RetryPolicy,
+ stats: Arc<Stats>,
+ ) -> Self {
Self {
uploader: Arc::new(uploader),
slots: Arc::new(Semaphore::new(slots)),
diff --git a/ai-gateway/src/test_support.rs b/ai-gateway/src/test_support.rs
index 6cefe779b7..c210f8ca65 100644
--- a/ai-gateway/src/test_support.rs
+++ b/ai-gateway/src/test_support.rs
@@ -27,7 +27,7 @@ pub(crate) struct FakeServer {
}
impl FakeServer {
- pub async fn start<F, Fut>(handler: F) -> Self
+ pub(crate) async fn start<F, Fut>(handler: F) -> Self
where
F: Fn(Request<Body>) -> Fut + Clone + Send + Sync + 'static,
Fut: Future<Output = Response<Body>> + Send + 'static,
@@ -46,11 +46,11 @@ impl FakeServer {
Self { url, calls, task }
}
- pub fn calls(&self) -> usize {
+ pub(crate) fn calls(&self) -> usize {
self.calls.load(Ordering::SeqCst)
}
- pub fn control_plane(&self) -> ControlPlaneClient {
+ pub(crate) fn control_plane(&self) -> ControlPlaneClient {
ControlPlaneClient::new(ControlPlaneConfig::new(&self.url, "test-service-key").unwrap())
.unwrap()
}
diff --git a/ai-gateway/src/transport/mod.rs b/ai-gateway/src/transport/mod.rs
index 54de712f93..373ac3a0f4 100644
--- a/ai-gateway/src/transport/mod.rs
+++ b/ai-gateway/src/transport/mod.rs
@@ -270,8 +270,13 @@ struct StreamResources<T> {
impl<T> StreamResources<T> {
fn release(&self, outcome: RelayOutcome) {
- let relay = {
- let mut relay = self.relay.lock().expect("relay owner lock poisoned");
+ let (relay, outcome) = {
+ // A poisoned lock means capture code panicked mid-update: the body
+ // is truncated and the capture is partial, so the relay failed.
+ let (mut relay, outcome) = match self.relay.lock() {
+ Ok(relay) => (relay, outcome),
+ Err(poisoned) => (poisoned.into_inner(), RelayOutcome::TransportError),
+ };
let taken = relay.take();
// Only the winning finalizer publishes the body failure. In
// particular, a deadline racing downstream EOF cannot change it later.
@@ -283,7 +288,7 @@ impl<T> StreamResources<T> {
{
self.failed.store(true, Ordering::Release);
}
- taken
+ (taken, outcome)
};
if let Some(Relay {
owner,
@@ -318,13 +323,11 @@ impl<T> StreamResources<T> {
}
fn observe(&self, update: impl FnOnce(&mut ExecutionCapture)) {
- if let Some(capture) = self
- .relay
- .lock()
- .expect("relay owner lock poisoned")
- .as_mut()
- .and_then(|relay| relay.capture.as_mut())
- {
+ // `release` fails a poisoned relay; never update its partial capture.
+ let Ok(mut relay) = self.relay.lock() else {
+ return;
+ };
+ if let Some(capture) = relay.as_mut().and_then(|relay| relay.capture.as_mut()) {
update(capture);
}
}
@@ -409,6 +412,37 @@ mod tests {
}
}
+ #[test]
+ fn a_panic_while_updating_the_capture_fails_the_relay() {
+ let resources = StreamResources {
+ relay: Mutex::new(Some(Relay {
+ owner: (),
+ capture: None,
+ span: tracing::Span::none(),
+ })),
+ failed: AtomicBool::new(false),
+ released: Notify::new(),
+ bytes: AtomicUsize::new(0),
+ chunks: AtomicUsize::new(0),
+ };
+ let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
+ let _relay = resources.relay.lock();
+ panic!("capture update panicked");
+ }));
+ assert!(resources.relay.is_poisoned());
+
+ resources.release(RelayOutcome::Eof);
+
+ assert!(resources.failed.load(Ordering::Acquire));
+ assert!(
+ resources
+ .relay
+ .lock()
+ .unwrap_or_else(std::sync::PoisonError::into_inner)
+ .is_none()
+ );
+ }
+
#[tokio::test]
async fn stream_span_ends_with_the_relay_and_records_the_failed_outcome() {
use opentelemetry::trace::TracerProvider;
diff --git a/ai-gateway/tests/observability.rs b/ai-gateway/tests/observability.rs
index 5ad2723f76..eb35182887 100644
--- a/ai-gateway/tests/observability.rs
+++ b/ai-gateway/tests/observability.rs
@@ -27,6 +27,11 @@ struct Gateway {
}
impl Gateway {
+ #[expect(
+ clippy::unwrap_used,
+ clippy::expect_used,
+ reason = "test helper outside #[test]; a panic fails the test"
+ )]
fn start(endpoint: &str, shutdown_seconds: &str, level: &str) -> Self {
let mut child = Command::new(env!("CARGO_BIN_EXE_ai-gateway"))
.env_clear()
@@ -69,6 +74,10 @@ impl Gateway {
}
}
+ #[expect(
+ clippy::unwrap_used,
+ reason = "test helper outside #[test]; a panic fails the test"
+ )]
async fn request(&self, sampled: bool) -> String {
let response = reqwest::Client::new()
.post(format!(
@@ -103,6 +112,11 @@ impl Gateway {
id
}
+ #[expect(
+ clippy::unwrap_used,
+ clippy::expect_used,
+ reason = "test helper outside #[test]; a panic fails the test"
+ )]
async fn stop(&mut self) {
assert!(
Command::new("/bin/kill")
@@ -208,6 +222,10 @@ async fn exports_otlp_traces_metrics_and_correlated_content_free_logs() {
assert_http_metrics(&metrics);
}
+#[expect(
+ clippy::unwrap_used,
+ reason = "test helper outside #[test]; a panic fails the test"
+)]
fn assert_operational_traces(traces: &[ResourceSpans], logs: &[Value]) {
let spans: Vec<_> = traces
.iter()
@@ -253,6 +271,10 @@ fn assert_operational_traces(traces: &[ResourceSpans], logs: &[Value]) {
/// Every log line emitted while serving a request repeats its gateway request ID at
/// the top level, and the operational server span carries it as an attribute.
+#[expect(
+ clippy::panic,
+ reason = "test helper outside #[test]; a panic fails the test"
+)]
fn assert_request_correlation(traces: &[ResourceSpans], logs: &[Value], request_ids: &[String]) {
let spans: Vec<_> = traces
.iter()
@@ -300,6 +322,12 @@ fn assert_request_correlation(traces: &[ResourceSpans], logs: &[Value], request_
}
}
+#[expect(
+ clippy::unwrap_used,
+ clippy::expect_used,
+ clippy::panic,
+ reason = "test helper outside #[test]; a panic fails the test"
+)]
fn assert_http_metrics(metrics: &[ResourceMetrics]) {
let http_duration = metrics
.iter()
diff --git a/ai-gateway/tests/support/mod.rs b/ai-gateway/tests/support/mod.rs
index 8180ebf130..308a65c4e3 100644
--- a/ai-gateway/tests/support/mod.rs
+++ b/ai-gateway/tests/support/mod.rs
@@ -9,7 +9,7 @@ use tokio::{
task::JoinHandle,
};
-pub struct TestServer {
+pub(crate) struct TestServer {
pub address: SocketAddr,
pub state: GatewayLifecycleState,
shutdown: Option<oneshot::Sender<()>>,
@@ -17,7 +17,11 @@ pub struct TestServer {
}
impl TestServer {
- pub async fn start(app: Router, state: GatewayLifecycleState, budget: Duration) -> Self {
+ #[expect(
+ clippy::unwrap_used,
+ reason = "test helper outside #[test]; a panic fails the test"
+ )]
+ pub(crate) async fn start(app: Router, state: GatewayLifecycleState, budget: Duration) -> Self {
let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
let address = listener.local_addr().unwrap();
let (shutdown, receiver) = oneshot::channel();
@@ -38,11 +42,20 @@ impl TestServer {
}
}
- pub fn begin_shutdown(&mut self) {
+ #[expect(
+ clippy::unwrap_used,
+ reason = "test helper outside #[test]; a panic fails the test"
+ )]
+ pub(crate) fn begin_shutdown(&mut self) {
self.shutdown.take().unwrap().send(()).unwrap();
}
- pub async fn finish(mut self) -> io::Result<()> {
+ #[expect(
+ clippy::unwrap_used,
+ clippy::expect_used,
+ reason = "test helper outside #[test]; a panic fails the test"
+ )]
+ pub(crate) async fn finish(mut self) -> io::Result<()> {
tokio::time::timeout(Duration::from_secs(5), self.task.take().unwrap())
.await
.expect("server did not stop")
@@ -57,7 +70,12 @@ impl Drop for TestServer {
}
}
-pub async fn get(address: SocketAddr, path: &str) -> String {
+#[expect(
+ clippy::unwrap_used,
+ clippy::expect_used,
+ reason = "test helper outside #[test]; a panic fails the test"
+)]
+pub(crate) async fn get(address: SocketAddr, path: &str) -> String {
tokio::time::timeout(Duration::from_secs(5), async {
let mut socket = TcpStream::connect(address).await.unwrap();
socket