feat: expose typed V3 native error codes (#19)

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

Author: Cappu7ino

docs/architecture/native-interop.md

@@ -85,6 +85,6 @@ 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.
+Native failures are surfaced as managed exceptions that include operation context, the native last-error message, and the native error code 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.
+The native ABI 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 maps these values to an internal `NativeServiceErrorCode` enum for diagnostics and control flow. Cancellation detection uses the typed async error code first and message matching only as a compatibility fallback.

src/DeltaLakeSharp.Client/Internal/Native/NativeErrorInfo.cs

@@ -0,0 +1,29 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+using System;
+
+namespace DeltaLakeSharp.Client.Internal.Native
+{
+    internal readonly struct NativeErrorInfo
+    {
+        public NativeErrorInfo(int rawCode, string? message)
+        {
+            RawCode = rawCode;
+            Code = Enum.IsDefined(typeof(NativeServiceErrorCode), rawCode)
+                ? (NativeServiceErrorCode)rawCode
+                : NativeServiceErrorCode.Internal;
+            Message = message;
+        }
+
+        public int RawCode { get; }
+
+        public NativeServiceErrorCode Code { get; }
+
+        public string? Message { get; }
+
+        public bool HasError => RawCode != (int)NativeServiceErrorCode.Ok || !string.IsNullOrWhiteSpace(Message);
+
+        public bool HasKnownCode => Enum.IsDefined(typeof(NativeServiceErrorCode), RawCode);
+    }
+}

src/DeltaLakeSharp.Client/Internal/Native/NativeServiceErrorCode.cs

@@ -0,0 +1,24 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+namespace DeltaLakeSharp.Client.Internal.Native
+{
+    /// <summary>
+    /// Stable native service error codes exposed by the Rust V3 ABI.
+    /// </summary>
+    /// <remarks>
+    /// Numeric values must match ServiceErrorCode in src/DeltaLakeSharp.Server/v3/src/error.rs.
+    /// </remarks>
+    internal enum NativeServiceErrorCode
+    {
+        Ok = 0,
+        InvalidRequest = 1,
+        TableNotFound = 2,
+        Delta = 3,
+        DataFusion = 4,
+        Arrow = 5,
+        Json = 6,
+        Internal = 7,
+        Cancelled = 8,
+    }
+}

src/DeltaLakeSharp.Client/Internal/NativeRustBackend.cs

@@ -30,8 +30,6 @@ 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;
 
@@ -612,18 +610,17 @@ public void Dispose()
 
         private InvalidOperationException CreateNativeOperationFailedException(string operation)
         {
-            int lastErrorCode = NativeMethods.GetLastErrorCode(_engine.DangerousGetHandle());
-            string? lastError = GetLastErrorMessage();
+            NativeErrorInfo error = GetLastError();
             string message = $"Native V3 backend operation '{operation}' failed.";
 
-            if (lastErrorCode != NativeServiceErrorOk)
+            if (error.RawCode != (int)NativeServiceErrorCode.Ok)
             {
-                message += $" Native error code: {lastErrorCode}.";
+                message += $" Native error code: {FormatNativeErrorCode(error)}.";
             }
 
-            if (!string.IsNullOrWhiteSpace(lastError))
+            if (!string.IsNullOrWhiteSpace(error.Message))
             {
-                message += $" Native error: {lastError}";
+                message += $" Native error: {error.Message}";
             }
 
             return new InvalidOperationException(message);
@@ -633,24 +630,44 @@ private static InvalidOperationException CreateNativeAsyncOperationFailedExcepti
             IntPtr operation,
             string operationName)
         {
-            int errorCode = NativeMethods.AsyncOperationGetErrorCode(operation);
-            IntPtr errorPtr = NativeMethods.AsyncOperationGetError(operation);
-            string? error = NativeMethods.PtrToStringUtf8(errorPtr);
+            NativeErrorInfo error = GetAsyncOperationError(operation);
             string message = $"Native V3 backend operation '{operationName}' failed.";
 
-            if (errorCode != NativeServiceErrorOk)
+            if (error.RawCode != (int)NativeServiceErrorCode.Ok)
             {
-                message += $" Native error code: {errorCode}.";
+                message += $" Native error code: {FormatNativeErrorCode(error)}.";
             }
 
-            if (!string.IsNullOrWhiteSpace(error))
+            if (!string.IsNullOrWhiteSpace(error.Message))
             {
-                message += $" Native error: {error}";
+                message += $" Native error: {error.Message}";
             }
 
             return new InvalidOperationException(message);
         }
 
+        private NativeErrorInfo GetLastError()
+        {
+            IntPtr engine = _engine.DangerousGetHandle();
+            return new NativeErrorInfo(
+                NativeMethods.GetLastErrorCode(engine),
+                NativeMethods.PtrToStringUtf8(NativeMethods.GetLastError(engine)));
+        }
+
+        private static NativeErrorInfo GetAsyncOperationError(IntPtr operation)
+        {
+            return new NativeErrorInfo(
+                NativeMethods.AsyncOperationGetErrorCode(operation),
+                NativeMethods.PtrToStringUtf8(NativeMethods.AsyncOperationGetError(operation)));
+        }
+
+        private static string FormatNativeErrorCode(NativeErrorInfo error)
+        {
+            return error.HasKnownCode
+                ? $"{error.RawCode} ({error.Code})"
+                : $"{error.RawCode} (Unknown)";
+        }
+
         private static void OnNativeAsyncOperationCompleted(IntPtr operation, IntPtr userData)
         {
             if (userData == IntPtr.Zero)
@@ -849,12 +866,6 @@ private static unsafe Schema TakeNativeAsyncSchemaResult(
             }
         }
 
-        private string? GetLastErrorMessage()
-        {
-            return NativeMethods.PtrToStringUtf8(
-                NativeMethods.GetLastError(_engine.DangerousGetHandle()));
-        }
-
         /// <summary>
         /// Exports a managed Arrow stream to the native Rust backend using the
         /// Arrow C Stream interface.
@@ -1424,15 +1435,14 @@ private void Cancel()
 
             private static bool IsNativeCancellationFailure(IntPtr operation)
             {
-                int errorCode = NativeMethods.AsyncOperationGetErrorCode(operation);
-                if (errorCode == NativeServiceErrorCancelled)
+                NativeErrorInfo errorInfo = GetAsyncOperationError(operation);
+                if (errorInfo.Code == NativeServiceErrorCode.Cancelled)
                 {
                     return true;
                 }
 
-                string? error = NativeMethods.PtrToStringUtf8(NativeMethods.AsyncOperationGetError(operation));
-                return error != null
-                    && error.IndexOf("cancel", StringComparison.OrdinalIgnoreCase) >= 0;
+                return errorInfo.Message != null
+                    && errorInfo.Message.IndexOf("cancel", StringComparison.OrdinalIgnoreCase) >= 0;
             }
         }
 

tests/DeltaLakeSharp.Tests/NativeRustBackendTests.cs

@@ -14,6 +14,7 @@
 using Apache.Arrow.Types;
 using DeltaLakeSharp.Client;
 using DeltaLakeSharp.Client.Internal;
+using DeltaLakeSharp.Client.Internal.Native;
 using DeltaLakeSharp.Client.Models;
 using Microsoft.VisualStudio.TestTools.UnitTesting;
 
@@ -29,6 +30,12 @@ namespace DeltaLakeSharp.Tests
     [TestClass]
     public class NativeRustBackendTests
     {
+        private const int NativeAsyncOperationPending = 0;
+        private const int NativeAsyncOperationFailed = 2;
+
+        private static readonly NativeMethods.NativeAsyncOperationCompletedCallback NoOpNativeAsyncOperationCompleted =
+            static (_, _) => { };
+
         /// <summary>
         /// Creates a unique local directory for a native Delta table test.
         /// Each test gets its own isolated folder so cleanup can safely remove
@@ -49,6 +56,99 @@ private static void CleanupTablePath(string tablePath)
             }
         }
 
+        private static int WaitForNativeAsyncOperation(IntPtr operation)
+        {
+            for (int i = 0; i < 200; i++)
+            {
+                int status = NativeMethods.AsyncOperationStatus(operation);
+                if (status != NativeAsyncOperationPending)
+                {
+                    return status;
+                }
+
+                Thread.Sleep(TimeSpan.FromMilliseconds(10));
+            }
+
+            return NativeMethods.AsyncOperationStatus(operation);
+        }
+
+        [TestMethod]
+        public void NativeServiceErrorCode_NumericValuesMatchNativeAbi()
+        {
+            Assert.AreEqual(0, (int)NativeServiceErrorCode.Ok);
+            Assert.AreEqual(1, (int)NativeServiceErrorCode.InvalidRequest);
+            Assert.AreEqual(2, (int)NativeServiceErrorCode.TableNotFound);
+            Assert.AreEqual(3, (int)NativeServiceErrorCode.Delta);
+            Assert.AreEqual(4, (int)NativeServiceErrorCode.DataFusion);
+            Assert.AreEqual(5, (int)NativeServiceErrorCode.Arrow);
+            Assert.AreEqual(6, (int)NativeServiceErrorCode.Json);
+            Assert.AreEqual(7, (int)NativeServiceErrorCode.Internal);
+            Assert.AreEqual(8, (int)NativeServiceErrorCode.Cancelled);
+        }
+
+        [TestMethod]
+        public void NativeErrorInfo_KnownCodesPreserveTypedClassification()
+        {
+            foreach (NativeServiceErrorCode code in Enum.GetValues(typeof(NativeServiceErrorCode)))
+            {
+                var error = new NativeErrorInfo(
+                    (int)code,
+                    code == NativeServiceErrorCode.Ok ? null : code.ToString());
+
+                Assert.AreEqual(code, error.Code);
+                Assert.AreEqual((int)code, error.RawCode);
+                Assert.IsTrue(error.HasKnownCode);
+                Assert.AreEqual(code != NativeServiceErrorCode.Ok, error.HasError);
+            }
+        }
+
+        [TestMethod]
+        public void NativeErrorInfo_UnknownCodePreservesRawValueAndMapsToInternal()
+        {
+            var error = new NativeErrorInfo(999, "future native code");
+
+            Assert.AreEqual(999, error.RawCode);
+            Assert.AreEqual(NativeServiceErrorCode.Internal, error.Code);
+            Assert.IsFalse(error.HasKnownCode);
+            Assert.IsTrue(error.HasError);
+        }
+
+        [TestMethod]
+        public void NativeAsyncOperation_MalformedCommandReturnsJsonErrorCode()
+        {
+            NativeMethods.EnsureLoaded();
+            IntPtr engine = NativeMethods.CreateEngine();
+            Assert.AreNotEqual(IntPtr.Zero, engine);
+
+            IntPtr operation = IntPtr.Zero;
+            try
+            {
+                operation = NativeMethods.GetSchemaAsyncWithCallback(
+                    engine,
+                    "{",
+                    NoOpNativeAsyncOperationCompleted,
+                    IntPtr.Zero);
+                Assert.AreNotEqual(IntPtr.Zero, operation);
+
+                Assert.AreEqual(NativeAsyncOperationFailed, WaitForNativeAsyncOperation(operation));
+                Assert.AreEqual(
+                    (int)NativeServiceErrorCode.Json,
+                    NativeMethods.AsyncOperationGetErrorCode(operation));
+
+                string? error = NativeMethods.PtrToStringUtf8(NativeMethods.AsyncOperationGetError(operation));
+                StringAssert.Contains(error ?? string.Empty, "json");
+            }
+            finally
+            {
+                if (operation != IntPtr.Zero)
+                {
+                    NativeMethods.AsyncOperationDestroy(operation);
+                }
+
+                NativeMethods.DestroyEngine(engine);
+            }
+        }
+
         [TestMethod]
         public async Task NativeBackend_HealthCheck_ReturnsTrue()
         {
@@ -460,6 +560,10 @@ public async Task NativeBackend_GetArrowSchemaAsync_MissingTableThrowsNativeErro
 
             StringAssert.Contains(ex.Message, "GetArrowSchemaAsync");
             StringAssert.Contains(ex.Message, "Native error code:");
+            Assert.IsTrue(
+                ex.Message.Contains("(Delta)", StringComparison.Ordinal)
+                    || ex.Message.Contains("(InvalidRequest)", StringComparison.Ordinal),
+                ex.Message);
             StringAssert.Contains(ex.Message, "Native error");
         }