Idiom - Error Handling in FFI - with structured enums in Rust

[dmitri-mamrukov]

Hello.

I have trouble binding C structs/unions with this structured enum in https://rust-unofficial.github.io/patterns/idioms/ffi/errors.html#structured-enums That is, my question is how to implement them in C.

pub mod errors {
    pub enum DatabaseError {
        IsReadOnly,
        IOError(std::io::Error),
        FileCorrupted(String),
    }
}

I've written a simplified version (with a flat enum):

lib.rs

pub mod errors {
    #[derive(Clone, Copy)]
    #[repr(C)]
    pub enum DatabaseError {
        IsReadOnly = 1,
        IOError = 2,
        FileCorrupted = 3,
    }
}

impl From<errors::DatabaseError> for libc::c_int {
    fn from(error: errors::DatabaseError) -> libc::c_int {
        (error as i8).into()
    }
}

pub mod c_api {
    use super::errors::DatabaseError;

    #[no_mangle]
    pub unsafe extern "C" fn db_error_code(error: *const DatabaseError) -> libc::c_int {
        let db_error: &DatabaseError = unsafe {
            // SAFETY: the pointer's lifetime is greater than the current stack frame.
            &*error
        };

        let res: libc::c_int = libc::c_int::from(*db_error);

        res
    }
}

#[cfg(test)]
mod tests {
    use super::{c_api, errors::DatabaseError};

    fn assert_db_error_code(error: DatabaseError, expected_result: i32) {
        let result = unsafe { c_api::db_error_code(&error) };

        assert_eq!(expected_result, result);
    }

    #[test]
    fn db_error_as_is_read_only() {
        assert_db_error_code(DatabaseError::IsReadOnly, 1);
    }

    #[test]
    fn db_error_as_io_error() {
        assert_db_error_code(DatabaseError::IOError, 2);
    }

    #[test]
    fn db_error_as_file_corrupted() {
        assert_db_error_code(DatabaseError::FileCorrupted, 3);
    }
}

client.c

#include <assert.h>
#include <inttypes.h>
#include <stdio.h>

enum DatabaseError {
    IsReadOnly = 1,
    IOError = 2,
    FileCorrupted = 3,
};

extern int32_t
    db_error_code(enum DatabaseError *);

void assert_db_error_code(enum DatabaseError arg, int32_t expected_result)
{
    int32_t result = db_error_code(&arg);

    assert(expected_result == result);
}

void test_api()
{
    {
        enum DatabaseError arg = IsReadOnly;
        int32_t expected_result = 1;
        assert_db_error_code(arg, expected_result);
    }
    {
        enum DatabaseError arg = IOError;
        int32_t expected_result = 2;
        assert_db_error_code(arg, expected_result);
    }
    {
        enum DatabaseError arg = FileCorrupted;
        int32_t expected_result = 3;
        assert_db_error_code(arg, expected_result);
    }
}

int main(void)
{
    enum DatabaseError arg = IsReadOnly;
    int32_t result = db_error_code(&arg);
    printf("(result: %" PRIu32 ")\n",
           result);

    test_api();

    return 0;
}

[dmitri-mamrukov]

I used cbindgen. It helped with initial code, which I manually adjusted to be close to the article's Rust code (Idiomatic Errors - Rust Design Patterns).

api.h

#include <inttypes.h>

typedef struct FileCorruptedInfo {
  uint32_t code;
} FileCorruptedInfo;

typedef struct IoErrorInfoDetails {
  uint32_t code;
} IoErrorInfoDetails;

typedef struct IoErrorInfo {
  struct IoErrorInfoDetails details;
} IoErrorInfo;

typedef enum DatabaseError_Tag {
  IsReadOnly,
  IoError,
  FileCorrupted,
} DatabaseError_Tag;

typedef struct DatabaseError {
  DatabaseError_Tag tag;
  union {
    struct IoErrorInfo io_error;
    struct FileCorruptedInfo file_corrupted;
  };
} DatabaseError;

char* db_error_description(const struct DatabaseError* error);

client.c

#include <assert.h>
#include <stdio.h>
#include <string.h>

#include "api.h"

void assert_db_error_description(struct DatabaseError error, const char* expected_result)
{
    char* result = db_error_description(&error);

    assert(strcmp(expected_result, result) == 0);
}

void test_api()
{
    {
        struct DatabaseError error;
        error.tag = IsReadOnly;
        const char* expected_result = "Cannot write to read-only database";
        assert_db_error_description(error, expected_result);
    }
    {
        struct DatabaseError error;
        error.tag = IoError;
        struct IoErrorInfoDetails io_error_info_details;
        io_error_info_details.code = 1;
        struct IoErrorInfo io_error_info;
        io_error_info.details = io_error_info_details;
        error.io_error = io_error_info;
        const char* expected_result = "I/O Error, error code: 1";
        assert_db_error_description(error, expected_result);
    }
    {
        struct DatabaseError error;
        error.tag = FileCorrupted;
        struct FileCorruptedInfo file_corrupted;
        file_corrupted.code = 1;
        error.file_corrupted = file_corrupted;
        const char* expected_result = "File corrupted, run repair, error code: 1";
        assert_db_error_description(error, expected_result);
    }
}

int main(void)
{
    struct DatabaseError error;
    error.tag = IoError;
    struct IoErrorInfoDetails io_error_info_details;
    io_error_info_details.code = 1;
    struct IoErrorInfo io_error_info;
    io_error_info.details = io_error_info_details;
    error.io_error = io_error_info;
    char* result = db_error_description(&error);
    printf("(result: %s)\n",
           result);

    test_api();

    return 0;
}

lib.rs

pub mod errors {
    pub struct IoErrorInfo {
        pub code: u32,
    }

    #[repr(C)]
    pub enum DatabaseError {
        IsReadOnly,
        IoError(IoErrorInfo),
        FileCorrupted(u32),
    }

    impl From<DatabaseError> for libc::c_int {
        fn from(err: DatabaseError) -> libc::c_int {
            match err {
                DatabaseError::IsReadOnly => 1,
                DatabaseError::IoError(_) => 2,
                DatabaseError::FileCorrupted(_) => 3,
            }
        }
    }
}

pub mod c_api {
    use super::errors::DatabaseError;

    #[no_mangle]
    pub unsafe extern "C" fn db_error_description(
        error: *const DatabaseError,
    ) -> *mut libc::c_char {
        let db_error: &DatabaseError = unsafe {
            // SAFETY: the pointer's lifetime is greater than the current stack frame.
            &*error
        };

        let error_str: String = match db_error {
            DatabaseError::IsReadOnly => "Cannot write to read-only database".to_string(),
            DatabaseError::IoError(error) => {
                format!("I/O Error, error code: {}", error.code)
            }
            DatabaseError::FileCorrupted(code) => {
                dbg!(code);
                format!("File corrupted, run repair, error code: {}", &code)
            }
        };

        let c_error = unsafe {
            // SAFETY: copying error_str to an allocated buffer with a NUL
            // character at the end.
            let malloc: *mut u8 = libc::malloc(error_str.len() + 1) as *mut _;
            if malloc.is_null() {
                return std::ptr::null_mut();
            }

            let source = error_str.as_bytes().as_ptr();
            std::ptr::copy_nonoverlapping(source, malloc, error_str.len());
            std::ptr::write(malloc.add(error_str.len()), 0);

            malloc as *mut libc::c_char
        };

        c_error
    }
}

#[cfg(test)]
mod tests {
    use std::ffi::CStr;

    use super::{c_api, errors::DatabaseError, errors::IoErrorInfo};

    fn assert_db_error_description(error: DatabaseError, expected_result: &str) {
        let result = unsafe { c_api::db_error_description(&error) };
        let c_str = unsafe { CStr::from_ptr(result) };
        let result = c_str.to_str();

        assert!(result.is_ok());
        assert_eq!(expected_result, result.unwrap());
    }

    #[test]
    fn db_error_as_is_read_only() {
        assert_db_error_description(
            DatabaseError::IsReadOnly,
            "Cannot write to read-only database",
        );
    }

    #[test]
    fn db_error_as_io_error() {
        assert_db_error_description(
            DatabaseError::IoError(IoErrorInfo { code: 1 }),
            "I/O Error, error code: 1",
        );
    }

    #[test]
    fn db_error_as_file_corrupted() {
        assert_db_error_description(
            DatabaseError::FileCorrupted(1),
            "File corrupted, run repair, error code: 1",
        );
    }
}