xmtp 0.9.3

Safe, ergonomic Rust client SDK for the XMTP messaging protocol
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

#![allow(
    unsafe_code,
    reason = "FFI error retrieval requires unsafe calls to xmtp_sys"
)]
//! Unified error types for the XMTP SDK.

use std::ffi::CStr;

/// Convenience alias used throughout the crate.
pub type Result<T> = std::result::Result<T, XmtpError>;

/// Top-level error type for the XMTP SDK.
#[derive(Debug, thiserror::Error)]
pub enum XmtpError {
    /// An error originating from the underlying FFI / native library.
    #[error("xmtp ffi: {0}")]
    Ffi(String),

    /// A returned pointer was unexpectedly null.
    #[error("unexpected null pointer from FFI")]
    NullPointer,

    /// A string received from FFI contained invalid UTF-8.
    #[error("invalid UTF-8 in FFI string")]
    InvalidUtf8,

    /// An argument passed to the SDK was invalid.
    #[error("{0}")]
    InvalidArgument(String),

    /// A signing operation failed.
    #[error("signing: {0}")]
    Signing(String),

    /// No identity resolver configured (needed for ENS names, etc.).
    #[error("no resolver configured — use ClientBuilder::resolver()")]
    NoResolver,

    /// Identity resolution failed (ENS, Lens, etc.).
    #[error("resolution: {0}")]
    Resolution(String),

    /// An I/O or filesystem operation failed.
    #[error("io: {0}")]
    Io(String),
}

/// Read the last FFI error message from thread-local storage.
pub(crate) fn last_ffi_error() -> XmtpError {
    // SAFETY: `xmtp_last_error_length` reads from thread-local storage with no preconditions.
    let len = unsafe { xmtp_sys::xmtp_last_error_length() };
    if len <= 0 {
        return XmtpError::Ffi("unknown FFI error".into());
    }
    let mut buf = vec![0u8; len.unsigned_abs() as usize];
    // SAFETY: `buf` is a valid mutable buffer of `len` bytes allocated above.
    let written = unsafe { xmtp_sys::xmtp_last_error_message(buf.as_mut_ptr().cast(), len) };
    if written <= 0 {
        return XmtpError::Ffi("failed to read FFI error".into());
    }
    let written_len = written.unsigned_abs() as usize;
    CStr::from_bytes_until_nul(&buf).map_or_else(
        |_| {
            XmtpError::Ffi(
                String::from_utf8_lossy(buf.get(..written_len).unwrap_or(&buf)).into_owned(),
            )
        },
        |cstr| XmtpError::Ffi(cstr.to_string_lossy().into_owned()),
    )
}

/// Check an FFI return code. `0` = success.
#[inline]
pub(crate) fn check(rc: i32) -> Result<()> {
    if rc == 0 {
        Ok(())
    } else {
        Err(last_ffi_error())
    }
}