feat: expose typed native error codes for V3 (#18)

* feat: expose typed native error codes for V3

* test: make async native error code test platform-stable

---------

Co-authored-by: STARGAZER <stargazer@XingdeMacBook-Air.local>

Author: Cappu7ino

docs/architecture/native-interop.md

@@ -86,3 +86,5 @@ Multiple V3 clients share the same process-wide Tokio runtime. This reduces thre
 ## Error Handling
 
 Native failures are surfaced as managed exceptions that include operation context and the native last-error message when available. Agents should preserve these messages in diagnostics and not replace them with generic errors.
+
+The native ABI also exposes stable integer error codes for engine-level last errors and async operation failures. `0` means success/no error; non-zero values distinguish invalid requests, missing tables, Delta/DataFusion/Arrow/JSON failures, internal failures, and cancellation. Managed code still includes the native message in exceptions, but cancellation detection should prefer the typed async error code and use message matching only as a compatibility fallback.

src/DeltaLakeSharp.Client/Internal/Native/NativeMethods.net472.cs

@@ -28,6 +28,9 @@ static NativeMethods()
         [DllImport(LibraryName, EntryPoint = "dts_get_last_error", CallingConvention = CallingConvention.Cdecl)]
         internal static extern IntPtr GetLastError(IntPtr engine);
 
+        [DllImport(LibraryName, EntryPoint = "dts_get_last_error_code", CallingConvention = CallingConvention.Cdecl)]
+        internal static extern int GetLastErrorCode(IntPtr engine);
+
         [DllImport(LibraryName, EntryPoint = "dts_get_schema_async_with_callback", CallingConvention = CallingConvention.Cdecl)]
         private static extern IntPtr GetSchemaAsyncWithCallbackNative(
             IntPtr engine,
@@ -122,6 +125,9 @@ private static extern IntPtr MergeStreamAsyncWithCallbackNative(
         [DllImport(LibraryName, EntryPoint = "dts_async_operation_get_error", CallingConvention = CallingConvention.Cdecl)]
         internal static extern IntPtr AsyncOperationGetError(IntPtr operation);
 
+        [DllImport(LibraryName, EntryPoint = "dts_async_operation_get_error_code", CallingConvention = CallingConvention.Cdecl)]
+        internal static extern int AsyncOperationGetErrorCode(IntPtr operation);
+
         [DllImport(LibraryName, EntryPoint = "dts_async_operation_cancel", CallingConvention = CallingConvention.Cdecl)]
         internal static extern void AsyncOperationCancel(IntPtr operation);
 

src/DeltaLakeSharp.Client/Internal/Native/NativeMethods.net8.cs

@@ -32,6 +32,10 @@ static NativeMethods()
         [LibraryImport(LibraryName, EntryPoint = "dts_get_last_error")]
         internal static partial IntPtr GetLastError(IntPtr engine);
 
+        [LibraryImport(LibraryName, EntryPoint = "dts_get_last_error_code")]
+        [return: MarshalAs(UnmanagedType.I4)]
+        internal static partial int GetLastErrorCode(IntPtr engine);
+
         [DllImport(LibraryName, EntryPoint = "dts_get_schema_async_with_callback", CallingConvention = CallingConvention.Cdecl)]
         private static extern IntPtr GetSchemaAsyncWithCallbackNative(
             IntPtr engine,
@@ -230,6 +234,10 @@ internal static IntPtr MergeStreamAsyncWithCallback(
         [LibraryImport(LibraryName, EntryPoint = "dts_async_operation_get_error")]
         internal static partial IntPtr AsyncOperationGetError(IntPtr operation);
 
+        [LibraryImport(LibraryName, EntryPoint = "dts_async_operation_get_error_code")]
+        [return: MarshalAs(UnmanagedType.I4)]
+        internal static partial int AsyncOperationGetErrorCode(IntPtr operation);
+
         [LibraryImport(LibraryName, EntryPoint = "dts_async_operation_cancel")]
         internal static partial void AsyncOperationCancel(IntPtr operation);
 

src/DeltaLakeSharp.Client/Internal/NativeRustBackend.cs

@@ -30,6 +30,8 @@ internal sealed class NativeRustBackend : IDeltaLakeBackend
         private const int NativeAsyncOperationSucceeded = 1;
         private const int NativeAsyncOperationFailed = 2;
         private const int NativeAsyncOperationCancelled = 3;
+        private const int NativeServiceErrorOk = 0;
+        private const int NativeServiceErrorCancelled = 8;
 
         private static readonly NativeMethods.NativeAsyncOperationCompletedCallback NativeAsyncOperationCompleted = OnNativeAsyncOperationCompleted;
 
@@ -610,9 +612,15 @@ public void Dispose()
 
         private InvalidOperationException CreateNativeOperationFailedException(string operation)
         {
+            int lastErrorCode = NativeMethods.GetLastErrorCode(_engine.DangerousGetHandle());
             string? lastError = GetLastErrorMessage();
             string message = $"Native V3 backend operation '{operation}' failed.";
 
+            if (lastErrorCode != NativeServiceErrorOk)
+            {
+                message += $" Native error code: {lastErrorCode}.";
+            }
+
             if (!string.IsNullOrWhiteSpace(lastError))
             {
                 message += $" Native error: {lastError}";
@@ -625,10 +633,16 @@ private static InvalidOperationException CreateNativeAsyncOperationFailedExcepti
             IntPtr operation,
             string operationName)
         {
+            int errorCode = NativeMethods.AsyncOperationGetErrorCode(operation);
             IntPtr errorPtr = NativeMethods.AsyncOperationGetError(operation);
             string? error = NativeMethods.PtrToStringUtf8(errorPtr);
             string message = $"Native V3 backend operation '{operationName}' failed.";
 
+            if (errorCode != NativeServiceErrorOk)
+            {
+                message += $" Native error code: {errorCode}.";
+            }
+
             if (!string.IsNullOrWhiteSpace(error))
             {
                 message += $" Native error: {error}";
@@ -1410,6 +1424,12 @@ private void Cancel()
 
             private static bool IsNativeCancellationFailure(IntPtr operation)
             {
+                int errorCode = NativeMethods.AsyncOperationGetErrorCode(operation);
+                if (errorCode == NativeServiceErrorCancelled)
+                {
+                    return true;
+                }
+
                 string? error = NativeMethods.PtrToStringUtf8(NativeMethods.AsyncOperationGetError(operation));
                 return error != null
                     && error.IndexOf("cancel", StringComparison.OrdinalIgnoreCase) >= 0;

src/DeltaLakeSharp.Server/v3/src/error.rs

@@ -8,6 +8,21 @@
 
 use std::fmt;
 
+/// Stable service error codes exposed through the native ABI.
+#[repr(i32)]
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ServiceErrorCode {
+    Ok = 0,
+    InvalidRequest = 1,
+    TableNotFound = 2,
+    Delta = 3,
+    DataFusion = 4,
+    Arrow = 5,
+    Json = 6,
+    Internal = 7,
+    Cancelled = 8,
+}
+
 /// Enumerates all error kinds that can occur in the service.
 #[derive(Debug)]
 pub enum ServiceError {
@@ -33,6 +48,21 @@ pub enum ServiceError {
     Internal(String),
 }
 
+impl ServiceError {
+    /// Returns the stable native ABI code for this error.
+    pub fn code(&self) -> ServiceErrorCode {
+        match self {
+            Self::InvalidRequest(_) => ServiceErrorCode::InvalidRequest,
+            Self::TableNotFound(_) => ServiceErrorCode::TableNotFound,
+            Self::Delta(_) => ServiceErrorCode::Delta,
+            Self::DataFusion(_) => ServiceErrorCode::DataFusion,
+            Self::Arrow(_) => ServiceErrorCode::Arrow,
+            Self::Json(_) => ServiceErrorCode::Json,
+            Self::Internal(_) => ServiceErrorCode::Internal,
+        }
+    }
+}
+
 impl fmt::Display for ServiceError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
@@ -84,3 +114,60 @@ impl From<serde_json::Error> for ServiceError {
         Self::Json(e)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn service_error_code_numeric_values_are_stable() {
+        assert_eq!(0, ServiceErrorCode::Ok as i32);
+        assert_eq!(1, ServiceErrorCode::InvalidRequest as i32);
+        assert_eq!(2, ServiceErrorCode::TableNotFound as i32);
+        assert_eq!(3, ServiceErrorCode::Delta as i32);
+        assert_eq!(4, ServiceErrorCode::DataFusion as i32);
+        assert_eq!(5, ServiceErrorCode::Arrow as i32);
+        assert_eq!(6, ServiceErrorCode::Json as i32);
+        assert_eq!(7, ServiceErrorCode::Internal as i32);
+        assert_eq!(8, ServiceErrorCode::Cancelled as i32);
+    }
+
+    #[test]
+    fn service_error_maps_to_stable_codes() {
+        assert_eq!(
+            ServiceErrorCode::InvalidRequest,
+            ServiceError::InvalidRequest("missing path".to_string()).code()
+        );
+        assert_eq!(
+            ServiceErrorCode::TableNotFound,
+            ServiceError::TableNotFound("/tmp/table".to_string()).code()
+        );
+        assert_eq!(
+            ServiceErrorCode::Delta,
+            ServiceError::Delta(deltalake::DeltaTableError::Generic("delta failure".to_string()))
+                .code()
+        );
+        assert_eq!(
+            ServiceErrorCode::DataFusion,
+            ServiceError::DataFusion(datafusion::error::DataFusionError::Execution(
+                "datafusion failure".to_string()
+            ))
+            .code()
+        );
+        assert_eq!(
+            ServiceErrorCode::Arrow,
+            ServiceError::Arrow(arrow::error::ArrowError::ExternalError(Box::new(
+                std::io::Error::other("arrow failure")
+            )))
+            .code()
+        );
+        assert_eq!(
+            ServiceErrorCode::Json,
+            ServiceError::Json(serde_json::from_str::<serde_json::Value>("{").unwrap_err()).code()
+        );
+        assert_eq!(
+            ServiceErrorCode::Internal,
+            ServiceError::Internal("unexpected".to_string()).code()
+        );
+    }
+}