fix(errors): unify backend error protocol and preserve db detail

This commit is contained in:
miracle authored and GitHub committed 2026-08-05 17:25:21 +08:00
1 parent f1617bbd87
commit c8c40ba839
24 files changed
+1197 -182

No files matched your search

+68 -9
View File
@@ -36,7 +36,7 @@ pub const QUERY_CANCELED: &str = "Query canceled";
/// (desktop/CLI diagnose first; this is only the Rust SQL-executor backstop).
const MONGO_SHELL_COMMAND_HINT: &str = "Use MongoDB shell-style commands, for example: db.collection.find({}).limit(100), db.collection.aggregate([]), db.collection.aggregate([], { explain: true }), db.version(), db.collection.countDocuments({}), db.collection.distinct(\"field\"), db.collection.getIndexes(), db.collection.createIndex({...}), or db.collection.insertOne({...}).";
const SQL_OMITTED_ERROR_CONTEXT: &str =
"SQL text omitted from user-facing error; enable debug SQL diagnostics for a redacted statement.";
"SQL text omitted from user-facing error; enable debug SQL diagnostics to inspect the original statement.";
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PoolErrorAction {
@@ -48,6 +48,7 @@ pub enum PoolErrorAction {
#[derive(Debug, Clone)]
pub enum QueryExecutionError {
Agent(AgentCallError),
DuckDb { code: String, message: String },
Canceled { stage: AgentErrorStage, operation_outcome: AgentOperationOutcome },
Timeout(String),
Sql(String),
@@ -58,6 +59,7 @@ impl QueryExecutionError {
pub fn into_legacy_string(self) -> String {
match self {
Self::Agent(error) => error.into_legacy_string(),
Self::DuckDb { message, .. } => message,
Self::Canceled { .. } => canceled_error(),
Self::Timeout(error) => error,
Self::Sql(error) => error,
@@ -68,6 +70,9 @@ impl QueryExecutionError {
pub fn into_backend_error(self) -> crate::backend_error::BackendError {
match self {
Self::Agent(error) => crate::backend_error::BackendError::from_agent_call_error(&error),
Self::DuckDb { code, message } => {
crate::backend_error::BackendError::from_duckdb_worker_error(&code, &message)
}
Self::Canceled { stage, operation_outcome } => {
crate::backend_error::BackendError::from_canceled(stage, operation_outcome)
}
@@ -80,9 +85,12 @@ impl QueryExecutionError {
fn with_omitted_sql_context(self, sql: &str) -> Self {
match self {
Self::Agent(error) => Self::Agent(error),
Self::DuckDb { code, message } => {
Self::DuckDb { code, message: query_error_with_omitted_sql_context(&message, sql) }
}
canceled @ Self::Canceled { .. } => canceled,
Self::Timeout(error) => Self::Timeout(query_error_with_omitted_sql_context(&error, sql)),
Self::Sql(error) => Self::Sql(query_error_with_omitted_sql_context(&error, sql)),
Self::Sql(error) => Self::Sql(append_typed_sql_error_context(&error, sql)),
Self::Legacy(error) => Self::Legacy(query_error_with_omitted_sql_context(&error, sql)),
}
}
@@ -90,6 +98,7 @@ impl QueryExecutionError {
fn with_context(self, context: &str) -> Self {
match self {
Self::Agent(error) => Self::Agent(error),
Self::DuckDb { code, message } => Self::DuckDb { code, message: format!("{message}; {context}") },
canceled @ Self::Canceled { .. } => canceled,
Self::Timeout(error) => Self::Timeout(format!("{error}; {context}")),
Self::Sql(error) => Self::Sql(format!("{error}; {context}")),
@@ -100,7 +109,7 @@ impl QueryExecutionError {
fn as_agent_error(&self) -> Option<&AgentCallError> {
match self {
Self::Agent(error) => Some(error),
Self::Canceled { .. } | Self::Timeout(_) | Self::Sql(_) | Self::Legacy(_) => None,
Self::DuckDb { .. } | Self::Canceled { .. } | Self::Timeout(_) | Self::Sql(_) | Self::Legacy(_) => None,
}
}
}
@@ -109,6 +118,7 @@ impl std::fmt::Display for QueryExecutionError {
fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Agent(error) => error.fmt(formatter),
Self::DuckDb { message, .. } => formatter.write_str(message),
Self::Canceled { .. } => formatter.write_str(QUERY_CANCELED),
Self::Timeout(error) => formatter.write_str(error),
Self::Sql(error) => formatter.write_str(error),
@@ -139,6 +149,14 @@ fn query_error_with_omitted_sql_context(error: &str, _sql: &str) -> String {
crate::db::agent_driver::append_legacy_error_context(error, SQL_OMITTED_ERROR_CONTEXT)
}
fn append_typed_sql_error_context(error: &str, _sql: &str) -> String {
if error.contains(SQL_OMITTED_ERROR_CONTEXT) {
return error.to_string();
}
let separator = if error.trim_start().starts_with("Server error:") { " " } else { "\n" };
format!("{error}{separator}{SQL_OMITTED_ERROR_CONTEXT}")
}
/// A multi-statement result with metadata intended for query clients.
///
/// `execution_error` is emitted for synthesized per-statement errors so clients
@@ -900,6 +918,7 @@ fn query_execution_error_action(
}
match error {
QueryExecutionError::Canceled { .. } => PoolErrorAction::Keep,
QueryExecutionError::DuckDb { message, .. } => query_pool_error_action(db_type, sql, message),
QueryExecutionError::Timeout(message)
| QueryExecutionError::Sql(message)
| QueryExecutionError::Legacy(message) => query_pool_error_action(db_type, sql, message),
@@ -1252,6 +1271,8 @@ async fn do_execute_typed(
let pool = connections.get(pool_key).ok_or("Connection not found")?;
let mut typed_agent_error = None;
#[cfg(feature = "duckdb-sidecar")]
let mut typed_duckdb_error = None;
let result: Result<db::QueryResult, String> = match pool {
#[cfg(feature = "duckdb-sidecar")]
PoolKind::DuckDbWorker(client) => {
@@ -1271,7 +1292,17 @@ async fn do_execute_typed(
let database = database.map(str::to_string);
let max_rows = options.max_rows;
drop(connections);
client.execute(database, sql, max_rows, cancel_token, query_timeout).await
match client.execute_typed(database, sql, max_rows, cancel_token, query_timeout).await {
Ok(result) => Ok(result),
Err(error) => {
let is_control_error = error.message == QUERY_CANCELED
|| is_dbx_query_timeout_error(&error.message.to_ascii_lowercase());
if !is_control_error {
typed_duckdb_error = Some(error.clone());
}
Err(error.message)
}
}
}
#[cfg(not(feature = "duckdb-sidecar"))]
PoolKind::DuckDbWorker(_) => {
@@ -1625,6 +1656,10 @@ async fn do_execute_typed(
result
.map(normalize_query_result_for_js)
.map_err(|error| {
#[cfg(feature = "duckdb-sidecar")]
if let Some(duckdb_error) = typed_duckdb_error {
return QueryExecutionError::DuckDb { code: duckdb_error.code, message: duckdb_error.message };
}
typed_agent_error.map_or_else(|| QueryExecutionError::Legacy(error), QueryExecutionError::Agent)
})
.map_err(|error| classify_query_error(pool_db_type, error))
@@ -5044,6 +5079,18 @@ for line in sys.stdin:
assert_eq!(error.into_backend_error().code(), "DBX-JDBC-1002");
}
#[test]
fn duckdb_worker_error_preserves_catalog_identity_and_detail() {
let error = QueryExecutionError::DuckDb {
code: "duckdb_execute_failed".to_string(),
message: "Catalog Error: Table missing_table does not exist".to_string(),
};
let backend_error = error.into_backend_error();
assert_eq!(backend_error.code(), "DBX-JDBC-4001");
assert_eq!(backend_error.detail(), Some("Catalog Error: Table missing_table does not exist"));
}
#[test]
fn query_timeout_preserves_timeout_catalog_identity_and_detail() {
let error = classify_query_error(
@@ -5060,7 +5107,7 @@ for line in sys.stdin:
);
assert_eq!(
backend_error.detail(),
Some("Query timed out after 1 seconds SQL text omitted from user-facing error; enable debug SQL diagnostics for a redacted statement.")
Some("Query timed out after 1 seconds\nSQL text omitted from user-facing error; enable debug SQL diagnostics to inspect the original statement.")
);
}
@@ -5081,7 +5128,7 @@ for line in sys.stdin:
assert_eq!(
backend_error.detail(),
Some(
"ERROR: relation \"dbx_table_that_does_not_exist\" does not exist SQL text omitted from user-facing error; enable debug SQL diagnostics for a redacted statement."
"ERROR: relation \"dbx_table_that_does_not_exist\" does not exist\nSQL text omitted from user-facing error; enable debug SQL diagnostics to inspect the original statement."
)
);
}
@@ -5106,7 +5153,7 @@ for line in sys.stdin:
assert_eq!(
backend_error.detail(),
Some(
"Server error: `ERROR 1064 (42000): You have an error in your SQL syntax` SQL text omitted from user-facing error; enable debug SQL diagnostics for a redacted statement."
"Server error: `ERROR 1064 (42000): You have an error in your SQL syntax` SQL text omitted from user-facing error; enable debug SQL diagnostics to inspect the original statement."
)
);
}
@@ -5127,7 +5174,7 @@ for line in sys.stdin:
assert_eq!(
backend_error.detail(),
Some(
"ERROR: relation \"dbx_table_that_does_not_exist\" does not exist SQL text omitted from user-facing error; enable debug SQL diagnostics for a redacted statement."
"ERROR: relation \"dbx_table_that_does_not_exist\" does not exist\nSQL text omitted from user-facing error; enable debug SQL diagnostics to inspect the original statement."
)
);
}
@@ -5147,7 +5194,7 @@ for line in sys.stdin:
assert_eq!(
backend_error.detail(),
Some(
"Statement 1 failed: ERROR: relation \"dbx_table_that_does_not_exist\" does not exist SQL text omitted from user-facing error; enable debug SQL diagnostics for a redacted statement."
"Statement 1 failed: ERROR: relation \"dbx_table_that_does_not_exist\" does not exist\nSQL text omitted from user-facing error; enable debug SQL diagnostics to inspect the original statement."
)
);
}
@@ -5511,6 +5558,18 @@ for line in sys.stdin:
assert_eq!(repeated.matches(SQL_OMITTED_ERROR_CONTEXT).count(), 1);
}
#[test]
fn typed_sql_error_context_keeps_driver_text_on_one_line() {
let error = QueryExecutionError::Sql("Server error: `ERROR 1064 (42000): syntax error`".to_string())
.with_omitted_sql_context("SELECT * FROM users")
.into_backend_error();
assert_eq!(
error.detail(),
Some("Server error: `ERROR 1064 (42000): syntax error` SQL text omitted from user-facing error; enable debug SQL diagnostics to inspect the original statement.")
);
}
#[test]
fn reconnect_retry_error_context_omits_raw_sql() {
let sql = "select 'secret-123' as token";