9 files changed, 265 insertions, 0 deletions
diff --git a/src/rust/Cargo.lock b/src/rust/Cargo.lock
new file mode 100644
index 0000000000..4ac9606ce8
--- /dev/null
+++ b/src/rust/Cargo.lock
@@ -0,0 +1,14 @@
+[root]
+name = "tor_util"
+version = "0.0.1"
+dependencies = [
+ "libc 0.2.22 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[metadata]
+"checksum libc 0.2.22 (registry+https://github.com/rust-lang/crates.io-index)" = "babb8281da88cba992fa1f4ddec7d63ed96280a1a53ec9b919fd37b53d71e502"
diff --git a/src/rust/Cargo.toml b/src/rust/Cargo.toml
new file mode 100644
index 0000000000..527c536323
--- /dev/null
+++ b/src/rust/Cargo.toml
@@ -0,0 +1,14 @@
+[workspace]
+members = ["tor_util"]
+
+[profile.release]
+debug = true
+panic = "abort"
+
+[source.crates-io]
+registry = 'https://github.com/rust-lang/crates.io-index'
+replace-with = 'vendored-sources'
+
+[source.vendored-sources]
+directory = 'vendor'
+
diff --git a/src/rust/include.am b/src/rust/include.am
new file mode 100644
index 0000000000..e198049071
--- /dev/null
+++ b/src/rust/include.am
@@ -0,0 +1,5 @@
+include src/rust/tor_util/include.am
+
+EXTRA_DIST +=\
+	src/rust/Cargo.toml \
+	src/rust/Cargo.lock
diff --git a/src/rust/tor_util/Cargo.toml b/src/rust/tor_util/Cargo.toml
new file mode 100644
index 0000000000..f175fbdfb0
--- /dev/null
+++ b/src/rust/tor_util/Cargo.toml
@@ -0,0 +1,13 @@
+[package]
+authors = ["The Tor Project"]
+name = "tor_util"
+version = "0.0.1"
+
+[lib]
+name = "tor_util"
+path = "lib.rs"
+crate_type = ["rlib", "staticlib"]
+
+[dependencies]
+libc = "*"
+
diff --git a/src/rust/tor_util/ffi.rs b/src/rust/tor_util/ffi.rs
new file mode 100644
index 0000000000..af4bfc41af
--- /dev/null
+++ b/src/rust/tor_util/ffi.rs
@@ -0,0 +1,56 @@
+//! FFI functions, only to be called from C.
+//!
+//! Equivalent C versions of these live in `src/common/compat_rust.c`
+
+use std::mem::forget;
+use std::ffi::CString;
+
+use libc;
+use rust_string::RustString;
+
+/// Free the passed `RustString` (`rust_str_t` in C), to be used in place of
+/// `tor_free`().
+///
+/// # Examples
+/// ```c
+/// rust_str_t r_s = rust_welcome_string();
+/// rust_str_free(r_s);
+/// ```
+#[no_mangle]
+#[cfg_attr(feature = "cargo-clippy", allow(needless_pass_by_value))]
+pub unsafe extern "C" fn rust_str_free(_str: RustString) {
+    // Empty body: Just drop _str and we're done (Drop takes care of it).
+}
+
+/// Lends an immutable, NUL-terminated C String.
+///
+/// # Examples
+/// ```c
+/// rust_str_t r_s = rust_welcome_string();
+/// const char *s = rust_str_get(r_s);
+/// printf("%s", s);
+/// rust_str_free(r_s);
+/// ```
+#[no_mangle]
+pub unsafe extern "C" fn rust_str_get(str: RustString) -> *const libc::c_char {
+    let res = str.as_ptr();
+    forget(str);
+    res
+}
+
+/// Returns a short string to announce Rust support during startup.
+///
+/// # Examples
+/// ```c
+/// rust_str_t r_s = rust_welcome_string();
+/// const char *s = rust_str_get(r_s);
+/// printf("%s", s);
+/// rust_str_free(r_s);
+/// ```
+#[no_mangle]
+pub extern "C" fn rust_welcome_string() -> RustString {
+    let s = CString::new("Tor is running with Rust integration. Please report \
+                          any bugs you encouter.")
+            .unwrap();
+    RustString::from(s)
+}
diff --git a/src/rust/tor_util/include.am b/src/rust/tor_util/include.am
new file mode 100644
index 0000000000..3b877649a3
--- /dev/null
+++ b/src/rust/tor_util/include.am
@@ -0,0 +1,12 @@
+EXTRA_DIST +=\
+	src/rust/tor_util/Cargo.toml \
+	src/rust/tor_util/lib.rs \
+	src/rust/tor_util/ffi.rs \
+	src/rust/tor_util/rust_string.rs
+
+src/rust/target/release/libtor_util.a: FORCE
+	( cd "$(abs_top_srcdir)/src/rust/tor_util" ; \
+		CARGO_TARGET_DIR="$(abs_top_builddir)/src/rust/target" \
+		$(CARGO) build --release --quiet --frozen )
+
+FORCE:
diff --git a/src/rust/tor_util/lib.rs b/src/rust/tor_util/lib.rs
new file mode 100644
index 0000000000..79d583d1ae
--- /dev/null
+++ b/src/rust/tor_util/lib.rs
@@ -0,0 +1,13 @@
+//! C <-> Rust compatibility helpers and types.
+//!
+//! Generically useful, small scale helpers should go here. This goes for both
+//! the C side (in the form of the ffi module) as well as the Rust side
+//! (individual modules per functionality). The corresponding C stuff lives in
+//! `src/common/compat_rust.{c,h}`.
+
+extern crate libc;
+
+mod rust_string;
+pub mod ffi;
+
+pub use rust_string::*;
diff --git a/src/rust/tor_util/rust_string.rs b/src/rust/tor_util/rust_string.rs
new file mode 100644
index 0000000000..46ec3fd7a8
--- /dev/null
+++ b/src/rust/tor_util/rust_string.rs
@@ -0,0 +1,101 @@
+use std::ffi::CString;
+use std::mem::forget;
+use libc;
+
+/// Compatibility wrapper for strings allocated in Rust and passed to C.
+///
+/// Rust doesn't ensure the safety of freeing memory across an FFI boundary, so
+/// we need to take special care to ensure we're not accidentally calling
+/// `tor_free`() on any string allocated in Rust. To more easily differentiate
+/// between strings that possibly (if Rust support is enabled) were allocated
+/// in Rust, C has the `rust_str_t` helper type. The equivalent on the Rust
+/// side is `RustString`.
+///
+/// Note: This type must not be used for strings allocated in C.
+#[repr(C)]
+#[derive(Debug)]
+pub struct RustString(*mut libc::c_char);
+
+impl RustString {
+    /// Returns a pointer to the underlying NUL-terminated byte array.
+    ///
+    /// Note that this function is not typically useful for Rust callers,
+    /// except in a direct FFI context.
+    ///
+    /// # Examples
+    /// ```
+    /// # use tor_util::RustString;
+    /// use std::ffi::CString;
+    ///
+    /// let r = RustString::from(CString::new("asdf").unwrap());
+    /// let c_str = r.as_ptr();
+    /// assert_eq!(b'a', unsafe { *c_str as u8});
+    /// ```
+    pub fn as_ptr(&self) -> *const libc::c_char {
+        self.0 as *const libc::c_char
+    }
+}
+
+impl From<CString> for RustString {
+    /// Constructs a new `RustString`
+    ///
+    /// # Examples
+    /// ```
+    /// # use tor_util::RustString;
+    /// use std::ffi::CString;
+    ///
+    /// let r = RustString::from(CString::new("asdf").unwrap());
+    /// ```
+    fn from(str: CString) -> RustString {
+        RustString(str.into_raw())
+    }
+}
+
+impl Into<CString> for RustString {
+    /// Reconstructs a `CString` from this `RustString`.
+    ///
+    /// Useful to take ownership back from a `RustString` that was given to C
+    /// code.
+    ///
+    /// # Examples
+    /// ```
+    /// # use tor_util::RustString;
+    /// use std::ffi::CString;
+    ///
+    /// let cs = CString::new("asdf").unwrap();
+    /// let r = RustString::from(cs.clone());
+    /// let cs2 = r.into();
+    /// assert_eq!(cs, cs2);
+    /// ```
+    fn into(self) -> CString {
+        // Calling from_raw is always OK here: We only construct self using
+        // valid CStrings and don't expose anything that could mutate it
+        let ret = unsafe { CString::from_raw(self.0) };
+        forget(self);
+        ret
+    }
+}
+
+impl Drop for RustString {
+    fn drop(&mut self) {
+        // Don't use into() here, because we would need to move out of
+        // self. Same safety consideration. Immediately drop the created
+        // CString, which takes care of freeing the wrapped string.
+        unsafe { CString::from_raw(self.0) };
+    }
+}
+
+#[cfg(test)]
+mod test {
+    use std::mem;
+    use super::*;
+
+    use libc;
+
+    /// Ensures we're not adding overhead by using RustString.
+    #[test]
+    fn size_of() {
+        assert_eq!(mem::size_of::<*mut libc::c_char>(),
+                   mem::size_of::<RustString>())
+    }
+}
diff --git a/src/rust/tor_util/tests/rust_string.rs b/src/rust/tor_util/tests/rust_string.rs
new file mode 100644
index 0000000000..1ff605a43c
--- /dev/null
+++ b/src/rust/tor_util/tests/rust_string.rs
@@ -0,0 +1,37 @@
+extern crate tor_util;
+extern crate libc;
+
+use std::ffi::CString;
+use tor_util::RustString;
+
+#[test]
+fn rust_string_conversions_preserve_c_string() {
+    let s = CString::new("asdf foo").unwrap();
+    let r = RustString::from(s.clone());
+    let r2 = RustString::from(s.clone());
+    let c = r2.as_ptr();
+    assert_eq!(unsafe { libc::strlen(c) }, 8);
+    let c_str = r.into();
+    assert_eq!(s, c_str);
+}
+
+#[test]
+fn empty_string() {
+    let s = CString::new("").unwrap();
+    let r = RustString::from(s.clone());
+    let c = r.as_ptr();
+    assert_eq!(unsafe { libc::strlen(c) }, 0);
+    let c_str = r.into();
+    assert_eq!(s, c_str);
+}
+
+#[test]
+fn c_string_with_unicode() {
+    // The euro sign is three bytes
+    let s = CString::new("asd€asd").unwrap();
+    let r = RustString::from(s.clone());
+    let c = r.as_ptr();
+    assert_eq!(unsafe { libc::strlen(c) }, 9);
+    let c_str = r.into();
+    assert_eq!(s, c_str);
+}