Add FFI document interface base

lnx-compile/shared/Cargo.toml

@@ -6,6 +6,7 @@ members = [
 ]
 
 [workspace.dependencies]
+thiserror = "2"
 serde = "1"
 serde_derive = "1"
 serde_json = "1"

lnx-compile/shared/lnx-ffi/Cargo.toml

@@ -5,3 +5,4 @@ edition = "2021"
 
 [dependencies]
 rkyv = { workspace = true }
+thiserror = { workspace = true }

lnx-compile/shared/lnx-ffi/src/document.rs

@@ -0,0 +1,36 @@
+use crate::error::DocumentError;
+use crate::format::Format;
+
+#[macro_export]
+/// A magic macro for exporting interactions between the
+/// compiled library and main process.
+/// 
+/// This is done on the base implementation of a type implementing
+/// [Document].
+macro_rules! extern_magic {
+    () => {};
+}
+/// A common document interface between the main lnx process and the compiled
+/// libraries.
+/// 
+/// 
+pub trait Document: Sized {
+    /// The type the document uses as its [rkyv::Archived] view.
+    type ArchivedView;
+
+    /// Load a set of [Document] instances from the given buffer with the given format.
+    fn load_owned_from_buffer(buffer: &[u8], kind: Format) -> Result<Vec<Self>, DocumentError>;
+
+    /// Serializes the document to a rkyv buffer.
+    fn serialize(&self) -> Result<(), DocumentError>;
+
+    /// Gets a reference to the archived document.
+    fn access<'a>(buffer: &'a [u8]) -> Result<&'a Self::ArchivedView, DocumentError>;
+}
+
+pub trait ArchivedDocument {
+    /// Serialize the document to JSON string.
+    fn serialize_to_json(&self);
+    /// Serialize the document to MSGPACK binary data.
+    fn serialize_to_msgpack(&self);
+}

lnx-compile/shared/lnx-ffi/src/error.rs

@@ -0,0 +1,61 @@
+use std::ffi::CString;
+use std::fmt::{Debug, Display, Formatter};
+
+#[repr(C)]
+#[derive(Debug, thiserror::Error)]
+#[error("{kind:?}: {message}")]
+/// An error that can occur from the document FFI api.
+pub struct DocumentError {
+    kind: ErrorKind,
+    message: AssumedSafeCString,
+}
+
+
+#[repr(C)]
+#[derive(Debug)]
+/// The kind of error that originated.
+pub enum ErrorKind {
+    /// THe document is malformed.
+    Malformed,
+}
+
+
+#[repr(transparent)]
+/// A wrapper type that internally knows the CString 
+/// is safely UTF-8. This is just for interop.
+struct AssumedSafeCString(CString);
+
+impl AssumedSafeCString {
+    fn as_str(&self) -> &str {
+        let inner = self.0.as_bytes();
+        unsafe { std::str::from_utf8_unchecked(inner) }
+    }
+}
+
+impl Display for AssumedSafeCString {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        <str as Display>::fmt(self.as_str(), f)
+    }
+}
+
+impl Debug for AssumedSafeCString {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        <str as Debug>::fmt(self.as_str(), f)
+    }
+}
+
+impl From<&str> for AssumedSafeCString {
+    fn from(value: &str) -> Self {
+        let inner = CString::new(value)
+            .expect("String should not contain null terminator within it");
+        Self(inner)
+    }
+}
+
+impl From<String> for AssumedSafeCString {
+    fn from(value: String) -> Self {
+        let inner = CString::new(value)
+            .expect("String should not contain null terminator within it");
+        Self(inner)
+    }
+}

lnx-compile/shared/lnx-ffi/src/format.rs

@@ -0,0 +1,13 @@
+
+#[repr(C)]
+/// A signal that indicates what format a buffer is in.
+pub enum Format {
+    /// The buffer is in the JSON format as a single object.
+    Json,
+    /// The buffer is in the NDJSON format which contains potentially
+    /// multiple documents.
+    Ndjson,
+    /// The buffer is in the MSGPACK format which contains potentially
+    /// multiple documents _or_ a single object map.
+    Msgpack,
+}

lnx-compile/shared/lnx-ffi/src/lib.rs

@@ -0,0 +1,3 @@
+mod document;
+mod format;
+mod error;