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 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
//! # Runtime support code for uniffi
//!
//! This crate provides the small amount of runtime code that is required by the generated uniffi
//! component scaffolding in order to transfer data back and forth across the C-style FFI layer,
//! as well as some utilities for testing the generated bindings.
//!
//! The key concept here is the [`FfiConverter`] trait, which is responsible for converting between
//! a Rust type and a low-level C-style type that can be passed across the FFI:
//!
//! * How to [represent](FfiConverter::FfiType) values of the Rust type in the low-level C-style type
//! system of the FFI layer.
//! * How to ["lower"](FfiConverter::lower) values of the Rust type into an appropriate low-level
//! FFI value.
//! * How to ["lift"](FfiConverter::try_lift) low-level FFI values back into values of the Rust
//! type.
//! * How to [write](FfiConverter::write) values of the Rust type into a buffer, for cases
//! where they are part of a compound data structure that is serialized for transfer.
//! * How to [read](FfiConverter::try_read) values of the Rust type from buffer, for cases
//! where they are received as part of a compound data structure that was serialized for transfer.
//! * How to [return](FfiConverter::lower_return) values of the Rust type from scaffolding
//! functions.
//!
//! This logic encapsulates the Rust-side handling of data transfer. Each foreign-language binding
//! must also implement a matching set of data-handling rules for each data type.
//!
//! In addition to the core `FfiConverter` trait, we provide a handful of struct definitions useful
//! for passing core rust types over the FFI, such as [`RustBuffer`].
#![warn(rust_2018_idioms, unused_qualifications)]
use anyhow::bail;
use bytes::buf::Buf;
// Make Result<> public to support external impls of FfiConverter
pub use anyhow::Result;
pub mod ffi;
mod ffi_converter_impls;
mod ffi_converter_traits;
pub mod metadata;
pub use ffi::*;
pub use ffi_converter_traits::{
ConvertError, FfiConverter, FfiConverterArc, HandleAlloc, Lift, LiftRef, LiftReturn, Lower,
LowerReturn,
};
pub use metadata::*;
// Re-export the libs that we use in the generated code,
// so the consumer doesn't have to depend on them directly.
pub mod deps {
pub use anyhow;
#[cfg(feature = "tokio")]
pub use async_compat;
pub use bytes;
pub use log;
pub use oneshot;
pub use static_assertions;
}
mod panichook;
const PACKAGE_VERSION: &str = env!("CARGO_PKG_VERSION");
// For the significance of this magic number 10 here, and the reason that
// it can't be a named constant, see the `check_compatible_version` function.
static_assertions::const_assert!(PACKAGE_VERSION.as_bytes().len() < 10);
/// Check whether the uniffi runtime version is compatible a given uniffi_bindgen version.
///
/// The result of this check may be used to ensure that generated Rust scaffolding is
/// using a compatible version of the uniffi runtime crate. It's a `const fn` so that it
/// can be used to perform such a check at compile time.
#[allow(clippy::len_zero)]
pub const fn check_compatible_version(bindgen_version: &'static str) -> bool {
// While UniFFI is still under heavy development, we require that
// the runtime support crate be precisely the same version as the
// build-time bindgen crate.
//
// What we want to achieve here is checking two strings for equality.
// Unfortunately Rust doesn't yet support calling the `&str` equals method
// in a const context. We can hack around that by doing a byte-by-byte
// comparison of the underlying bytes.
let package_version = PACKAGE_VERSION.as_bytes();
let bindgen_version = bindgen_version.as_bytes();
// What we want to achieve here is a loop over the underlying bytes,
// something like:
// ```
// if package_version.len() != bindgen_version.len() {
// return false
// }
// for i in 0..package_version.len() {
// if package_version[i] != bindgen_version[i] {
// return false
// }
// }
// return true
// ```
// Unfortunately stable Rust doesn't allow `if` or `for` in const contexts,
// so code like the above would only work in nightly. We can hack around it by
// statically asserting that the string is shorter than a certain length
// (currently 10 bytes) and then manually unrolling that many iterations of the loop.
//
// Yes, I am aware that this is horrific, but the externally-visible
// behaviour is quite nice for consumers!
package_version.len() == bindgen_version.len()
&& (package_version.len() == 0 || package_version[0] == bindgen_version[0])
&& (package_version.len() <= 1 || package_version[1] == bindgen_version[1])
&& (package_version.len() <= 2 || package_version[2] == bindgen_version[2])
&& (package_version.len() <= 3 || package_version[3] == bindgen_version[3])
&& (package_version.len() <= 4 || package_version[4] == bindgen_version[4])
&& (package_version.len() <= 5 || package_version[5] == bindgen_version[5])
&& (package_version.len() <= 6 || package_version[6] == bindgen_version[6])
&& (package_version.len() <= 7 || package_version[7] == bindgen_version[7])
&& (package_version.len() <= 8 || package_version[8] == bindgen_version[8])
&& (package_version.len() <= 9 || package_version[9] == bindgen_version[9])
&& package_version.len() < 10
}
/// Assert that the uniffi runtime version matches an expected value.
///
/// This is a helper hook for the generated Rust scaffolding, to produce a compile-time
/// error if the version of `uniffi_bindgen` used to generate the scaffolding was
/// incompatible with the version of `uniffi` being used at runtime.
#[macro_export]
macro_rules! assert_compatible_version {
($v:expr $(,)?) => {
uniffi::deps::static_assertions::const_assert!(uniffi::check_compatible_version($v));
};
}
/// Struct to use when we want to lift/lower/serialize types inside the `uniffi` crate.
struct UniFfiTag;
/// A helper function to ensure we don't read past the end of a buffer.
///
/// Rust won't actually let us read past the end of a buffer, but the `Buf` trait does not support
/// returning an explicit error in this case, and will instead panic. This is a look-before-you-leap
/// helper function to instead return an explicit error, to help with debugging.
pub fn check_remaining(buf: &[u8], num_bytes: usize) -> Result<()> {
if buf.remaining() < num_bytes {
bail!(
"not enough bytes remaining in buffer ({} < {num_bytes})",
buf.remaining(),
);
}
Ok(())
}
/// Macro to implement lowering/lifting using a `RustBuffer`
///
/// For complex types where it's too fiddly or too unsafe to convert them into a special-purpose
/// C-compatible value, you can use this trait to implement `lower()` in terms of `write()` and
/// `lift` in terms of `read()`.
///
/// This macro implements the boilerplate needed to define `lower`, `lift` and `FFIType`.
#[macro_export]
macro_rules! ffi_converter_rust_buffer_lift_and_lower {
($uniffi_tag:ty) => {
type FfiType = $crate::RustBuffer;
fn lower(v: Self) -> $crate::RustBuffer {
let mut buf = ::std::vec::Vec::new();
<Self as $crate::FfiConverter<$uniffi_tag>>::write(v, &mut buf);
$crate::RustBuffer::from_vec(buf)
}
fn try_lift(buf: $crate::RustBuffer) -> $crate::Result<Self> {
let vec = buf.destroy_into_vec();
let mut buf = vec.as_slice();
let value = <Self as $crate::FfiConverter<$uniffi_tag>>::try_read(&mut buf)?;
match $crate::deps::bytes::Buf::remaining(&buf) {
0 => Ok(value),
n => $crate::deps::anyhow::bail!(
"junk data left in buffer after lifting (count: {n})",
),
}
}
};
}
/// Macro to implement `FfiConverter<T>` for a UniFfiTag using a different UniFfiTag
///
/// This is used for external types
#[macro_export]
macro_rules! ffi_converter_forward {
// Forward a `FfiConverter` implementation
($T:ty, $existing_impl_tag:ty, $new_impl_tag:ty) => {
::uniffi::do_ffi_converter_forward!(
FfiConverter,
$T,
$T,
$existing_impl_tag,
$new_impl_tag
);
$crate::derive_ffi_traits!(local $T);
};
}
/// Macro to implement `FfiConverterArc<T>` for a UniFfiTag using a different UniFfiTag
///
/// This is used for external types
#[macro_export]
macro_rules! ffi_converter_arc_forward {
($T:ty, $existing_impl_tag:ty, $new_impl_tag:ty) => {
::uniffi::do_ffi_converter_forward!(
FfiConverterArc,
::std::sync::Arc<$T>,
$T,
$existing_impl_tag,
$new_impl_tag
);
// Note: no need to call derive_ffi_traits! because there is a blanket impl for all Arc<T>
};
}
// Generic code between the two macros above
#[doc(hidden)]
#[macro_export]
macro_rules! do_ffi_converter_forward {
($trait:ident, $rust_type:ty, $T:ty, $existing_impl_tag:ty, $new_impl_tag:ty) => {
unsafe impl $crate::$trait<$new_impl_tag> for $T {
type FfiType = <$T as $crate::$trait<$existing_impl_tag>>::FfiType;
fn lower(obj: $rust_type) -> Self::FfiType {
<$T as $crate::$trait<$existing_impl_tag>>::lower(obj)
}
fn try_lift(v: Self::FfiType) -> $crate::Result<$rust_type> {
<$T as $crate::$trait<$existing_impl_tag>>::try_lift(v)
}
fn write(obj: $rust_type, buf: &mut Vec<u8>) {
<$T as $crate::$trait<$existing_impl_tag>>::write(obj, buf)
}
fn try_read(buf: &mut &[u8]) -> $crate::Result<$rust_type> {
<$T as $crate::$trait<$existing_impl_tag>>::try_read(buf)
}
const TYPE_ID_META: ::uniffi::MetadataBuffer =
<$T as $crate::$trait<$existing_impl_tag>>::TYPE_ID_META;
}
};
}
#[cfg(test)]
mod test {
use super::{FfiConverter, UniFfiTag};
use std::time::{Duration, SystemTime};
#[test]
fn timestamp_roundtrip_post_epoch() {
let expected = SystemTime::UNIX_EPOCH + Duration::new(100, 100);
let result =
<SystemTime as FfiConverter<UniFfiTag>>::try_lift(<SystemTime as FfiConverter<
UniFfiTag,
>>::lower(expected))
.expect("Failed to lift!");
assert_eq!(expected, result)
}
#[test]
fn timestamp_roundtrip_pre_epoch() {
let expected = SystemTime::UNIX_EPOCH - Duration::new(100, 100);
let result =
<SystemTime as FfiConverter<UniFfiTag>>::try_lift(<SystemTime as FfiConverter<
UniFfiTag,
>>::lower(expected))
.expect("Failed to lift!");
assert_eq!(
expected, result,
"Expected results after lowering and lifting to be equal"
)
}
}
#[cfg(test)]
pub mod test_util {
use std::{error::Error, fmt};
use super::*;
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct TestError(pub String);
// Use FfiConverter to simplify lifting TestError out of RustBuffer to check it
unsafe impl<UT> FfiConverter<UT> for TestError {
ffi_converter_rust_buffer_lift_and_lower!(UniFfiTag);
fn write(obj: TestError, buf: &mut Vec<u8>) {
<String as FfiConverter<UniFfiTag>>::write(obj.0, buf);
}
fn try_read(buf: &mut &[u8]) -> Result<TestError> {
<String as FfiConverter<UniFfiTag>>::try_read(buf).map(TestError)
}
// Use a dummy value here since we don't actually need TYPE_ID_META
const TYPE_ID_META: MetadataBuffer = MetadataBuffer::new();
}
impl fmt::Display for TestError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{}", self.0)
}
}
impl Error for TestError {}
impl<T: Into<String>> From<T> for TestError {
fn from(v: T) -> Self {
Self(v.into())
}
}
derive_ffi_traits!(blanket TestError);
}