Skip to main content

uqa_client/
http_engine_error.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7use std::fmt;
8use std::io;
9
10use crate::{HttpLimit, SQLDiagnostic};
11use reqwest::StatusCode;
12use thiserror::Error;
13
14/// Redacted failure returned by [`crate::HttpEngine`].
15#[derive(Error)]
16pub enum HttpEngineError {
17    #[error("UQA data-plane URL is invalid")]
18    InvalidBaseURL,
19    #[error("plain HTTP UQA URLs must resolve to loopback")]
20    InsecureRemoteURL,
21    #[error("UQA project token must not be empty")]
22    InvalidCredential,
23    #[error("required UQA connection environment variable {0} is missing")]
24    MissingEnvironmentVariable(&'static str),
25    #[error("UQA project name must not be empty")]
26    EmptyProjectName,
27    #[error("UQA organization name must not be empty")]
28    EmptyOrganizationName,
29    #[error("uqa CLI could not be started; install it or provide its executable path")]
30    CLIUnavailable(#[source] io::Error),
31    #[error("uqa CLI connection lookup failed")]
32    CLIExecution(#[source] io::Error),
33    #[error("uqa CLI connection lookup timed out")]
34    CLITimedOut,
35    #[error("uqa CLI connection output exceeded the client safety limit")]
36    CLIOutputTooLarge,
37    #[error("uqa CLI could not resolve the requested project; run the matching connection command for details")]
38    CLIConnectionFailed,
39    #[error("uqa CLI returned an invalid connection response")]
40    InvalidCLIResponse(#[source] serde_json::Error),
41    #[error("SQL text must not be empty")]
42    EmptySQL,
43    #[error("SQL parameter cannot be represented by the HTTP protocol")]
44    InvalidParameter,
45    #[error("UQA HTTP client could not be initialized")]
46    BuildClient(#[source] reqwest::Error),
47    #[error("UQA HTTP transport failed")]
48    Transport(#[source] reqwest::Error),
49    #[error("UQA returned {status} with code {code}{detail}", detail = diagnostic_message(.diagnostic.as_deref(), .limit.as_deref()))]
50    Server {
51        status: StatusCode,
52        code: String,
53        message: String,
54        request_id: Option<String>,
55        diagnostic: Option<Box<SQLDiagnostic>>,
56        limit: Option<Box<HttpLimit>>,
57    },
58    #[error("UQA response exceeded the client safety limit")]
59    ResponseTooLarge,
60    #[error("UQA response content type is invalid")]
61    UnexpectedContentType,
62    #[error("UQA response is missing its request ID")]
63    MissingRequestId,
64    #[error("UQA response request IDs do not match")]
65    ResponseRequestIdMismatch,
66    #[error("UQA response body is not valid JSON")]
67    InvalidResponse(#[source] serde_json::Error),
68    #[error("UQA NDJSON stream frame exceeded the client safety limit")]
69    StreamFrameTooLarge,
70    #[error("UQA NDJSON stream frame order is invalid")]
71    InvalidStreamSequence,
72    #[error("UQA NDJSON stream ended before a terminal frame")]
73    TruncatedStream,
74    #[error("UQA NDJSON stream request ID does not match its HTTP response")]
75    StreamRequestIdMismatch,
76}
77
78impl HttpEngineError {
79    pub(crate) fn build_client(error: reqwest::Error) -> Self {
80        Self::BuildClient(error.without_url())
81    }
82
83    pub(crate) fn transport(error: reqwest::Error) -> Self {
84        Self::Transport(error.without_url())
85    }
86}
87
88impl fmt::Debug for HttpEngineError {
89    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
90        match self {
91            Self::Server {
92                status,
93                code,
94                request_id,
95                diagnostic,
96                limit,
97                ..
98            } => formatter
99                .debug_struct("HttpEngineError::Server")
100                .field("status", status)
101                .field("code", code)
102                .field("request_id", request_id)
103                .field("diagnostic", diagnostic)
104                .field("limit", limit)
105                .finish(),
106            Self::InvalidBaseURL => formatter.write_str("HttpEngineError::InvalidBaseURL"),
107            Self::InsecureRemoteURL => formatter.write_str("HttpEngineError::InsecureRemoteURL"),
108            Self::InvalidCredential => formatter.write_str("HttpEngineError::InvalidCredential"),
109            Self::MissingEnvironmentVariable(name) => formatter
110                .debug_tuple("HttpEngineError::MissingEnvironmentVariable")
111                .field(name)
112                .finish(),
113            Self::EmptyProjectName => formatter.write_str("HttpEngineError::EmptyProjectName"),
114            Self::EmptyOrganizationName => {
115                formatter.write_str("HttpEngineError::EmptyOrganizationName")
116            }
117            Self::CLIUnavailable(_) => {
118                formatter.write_str("HttpEngineError::CLIUnavailable([REDACTED])")
119            }
120            Self::CLIExecution(_) => {
121                formatter.write_str("HttpEngineError::CLIExecution([REDACTED])")
122            }
123            Self::CLITimedOut => formatter.write_str("HttpEngineError::CLITimedOut"),
124            Self::CLIOutputTooLarge => formatter.write_str("HttpEngineError::CLIOutputTooLarge"),
125            Self::CLIConnectionFailed => {
126                formatter.write_str("HttpEngineError::CLIConnectionFailed")
127            }
128            Self::InvalidCLIResponse(_) => {
129                formatter.write_str("HttpEngineError::InvalidCLIResponse([REDACTED])")
130            }
131            Self::EmptySQL => formatter.write_str("HttpEngineError::EmptySQL"),
132            Self::InvalidParameter => formatter.write_str("HttpEngineError::InvalidParameter"),
133            Self::BuildClient(_) => formatter.write_str("HttpEngineError::BuildClient([REDACTED])"),
134            Self::Transport(_) => formatter.write_str("HttpEngineError::Transport([REDACTED])"),
135            Self::ResponseTooLarge => formatter.write_str("HttpEngineError::ResponseTooLarge"),
136            Self::UnexpectedContentType => {
137                formatter.write_str("HttpEngineError::UnexpectedContentType")
138            }
139            Self::MissingRequestId => formatter.write_str("HttpEngineError::MissingRequestId"),
140            Self::ResponseRequestIdMismatch => {
141                formatter.write_str("HttpEngineError::ResponseRequestIdMismatch")
142            }
143            Self::InvalidResponse(_) => {
144                formatter.write_str("HttpEngineError::InvalidResponse([REDACTED])")
145            }
146            Self::StreamFrameTooLarge => {
147                formatter.write_str("HttpEngineError::StreamFrameTooLarge")
148            }
149            Self::InvalidStreamSequence => {
150                formatter.write_str("HttpEngineError::InvalidStreamSequence")
151            }
152            Self::TruncatedStream => formatter.write_str("HttpEngineError::TruncatedStream"),
153            Self::StreamRequestIdMismatch => {
154                formatter.write_str("HttpEngineError::StreamRequestIdMismatch")
155            }
156        }
157    }
158}
159
160fn diagnostic_message(diagnostic: Option<&SQLDiagnostic>, limit: Option<&HttpLimit>) -> String {
161    match (diagnostic, limit) {
162        (Some(diagnostic), Some(limit)) => format!(" ({diagnostic}) ({limit})"),
163        (Some(diagnostic), None) => format!(" ({diagnostic})"),
164        (None, Some(limit)) => format!(" ({limit})"),
165        (None, None) => String::new(),
166    }
167}
168
169#[cfg(test)]
170mod tests {
171    use super::*;
172
173    #[test]
174    fn server_debug_output_omits_customer_message() {
175        let secret = "customer SQL and result";
176        let error = HttpEngineError::Server {
177            status: StatusCode::BAD_REQUEST,
178            code: "SQL_EXECUTION_FAILED".to_owned(),
179            message: secret.to_owned(),
180            request_id: Some("qry_test".to_owned()),
181            diagnostic: None,
182            limit: None,
183        };
184
185        let debug = format!("{error:?}");
186        assert!(!debug.contains(secret));
187        assert!(debug.contains("SQL_EXECUTION_FAILED"));
188    }
189}