add server support

lib/src/lib.rs

@@ -14,6 +14,7 @@ pub mod atomic;
 pub mod kv;
 pub mod replica;
 pub mod result;
+pub mod server;
 pub mod status;
 pub mod string;
 pub mod task;
@@ -26,6 +27,7 @@ pub(crate) mod types {
     pub(crate) use crate::kv::{TCKVList, TCKV};
     pub(crate) use crate::replica::TCReplica;
     pub(crate) use crate::result::TCResult;
+    pub(crate) use crate::server::TCServer;
     pub(crate) use crate::status::TCStatus;
     pub(crate) use crate::string::{TCString, TCStringList};
     pub(crate) use crate::task::{TCTask, TCTaskList};

lib/src/replica.rs

@@ -100,8 +100,9 @@ pub unsafe extern "C" fn tc_replica_new_in_memory() -> *mut TCReplica {
     unsafe { TCReplica::from(Replica::new(storage)).return_ptr() }
 }
 
-/// Create a new TCReplica with an on-disk database having the given filename. On error, a string
-/// is written to the `error_out` parameter (if it is not NULL) and NULL is returned.
+/// Create a new TCReplica with an on-disk database having the given filename.  On error, a string
+/// is written to the error_out parameter (if it is not NULL) and NULL is returned.  The caller
+/// must free this string.
 #[no_mangle]
 pub unsafe extern "C" fn tc_replica_new_on_disk(
     path: *mut TCString,
@@ -258,7 +259,31 @@ pub unsafe extern "C" fn tc_replica_import_task_with_uuid(
     )
 }
 
-// TODO: tc_replica_sync
+/// Synchronize this replica with a server.
+///
+/// The `server` argument remains owned by the caller, and must be freed explicitly.
+#[no_mangle]
+pub unsafe extern "C" fn tc_replica_sync(
+    rep: *mut TCReplica,
+    server: *mut TCServer,
+    avoid_snapshots: bool,
+) -> TCResult {
+    wrap(
+        rep,
+        |rep| {
+            debug_assert!(!server.is_null());
+            // SAFETY:
+            //  - server is not NULL
+            //  - *server is a valid TCServer (promised by caller)
+            //  - server is valid for the lifetime of tc_replica_sync (not threadsafe)
+            //  - server will not be accessed simultaneously (not threadsafe)
+            let server = unsafe { TCServer::from_ptr_arg_ref_mut(server) };
+            rep.sync(server.as_mut(), avoid_snapshots)?;
+            Ok(TCResult::Ok)
+        },
+        TCResult::Error,
+    )
+}
 
 /// Undo local operations until the most recent UndoPoint.
 ///

lib/src/server.rs

@@ -0,0 +1,139 @@
+use crate::traits::*;
+use crate::types::*;
+use crate::util::err_to_tcstring;
+use taskchampion::{Server, ServerConfig};
+
+/// TCServer represents an interface to a sync server.  Aside from new and free, a server
+/// has no C-accessible API, but is designed to be passed to `tc_replica_sync`.
+///
+/// ## Safety
+///
+/// TCServer are not threadsafe, and must not be used with multiple replicas simultaneously.
+pub struct TCServer(Box<dyn Server>);
+
+impl PassByPointer for TCServer {}
+
+impl From<Box<dyn Server>> for TCServer {
+    fn from(server: Box<dyn Server>) -> TCServer {
+        TCServer(server)
+    }
+}
+
+impl AsMut<Box<dyn Server>> for TCServer {
+    fn as_mut(&mut self) -> &mut Box<dyn Server> {
+        &mut self.0
+    }
+}
+
+/// Utility function to allow using `?` notation to return an error value.  
+fn wrap<T, F>(f: F, error_out: *mut *mut TCString, err_value: T) -> T
+where
+    F: FnOnce() -> anyhow::Result<T>,
+{
+    match f() {
+        Ok(v) => v,
+        Err(e) => {
+            if !error_out.is_null() {
+                // SAFETY:
+                // - error_out is not NULL (checked)
+                // - ..and points to a valid pointer (promised by caller)
+                // - caller will free this string (promised by caller)
+                unsafe {
+                    *error_out = err_to_tcstring(e).return_ptr();
+                }
+            }
+            err_value
+        }
+    }
+}
+
+/// Create a new TCServer that operates locally (on-disk).  See the TaskChampion docs for the
+/// description of the arguments.
+///
+/// On error, a string is written to the error_out parameter (if it is not NULL) and NULL is
+/// returned.  The caller must free this string.
+///
+/// The server must be freed after it is used - tc_replica_sync does not automatically free it.
+#[no_mangle]
+pub unsafe extern "C" fn tc_server_new_local(
+    server_dir: *mut TCString,
+    error_out: *mut *mut TCString,
+) -> *mut TCServer {
+    wrap(
+        || {
+            // SAFETY: see TCString docstring
+            let server_dir = unsafe { TCString::take_from_ptr_arg(server_dir) };
+            let server_config = ServerConfig::Local {
+                server_dir: server_dir.to_path_buf(),
+            };
+            let server = server_config.into_server()?;
+            // SAFETY: caller promises to free this server.
+            Ok(unsafe { TCServer::return_ptr(server.into()) })
+        },
+        error_out,
+        std::ptr::null_mut(),
+    )
+}
+
+/// Create a new TCServer that connects to a remote server.  See the TaskChampion docs for the
+/// description of the arguments.
+///
+/// On error, a string is written to the error_out parameter (if it is not NULL) and NULL is
+/// returned.  The caller must free this string.
+///
+/// The server must be freed after it is used - tc_replica_sync does not automatically free it.
+#[no_mangle]
+pub unsafe extern "C" fn tc_server_new_remote(
+    origin: *mut TCString,
+    client_key: TCUuid,
+    encryption_secret: *mut TCString,
+    error_out: *mut *mut TCString,
+) -> *mut TCServer {
+    wrap(
+        || {
+            debug_assert!(!origin.is_null());
+            debug_assert!(!encryption_secret.is_null());
+            // SAFETY:
+            //  - origin is not NULL
+            //  - origin is valid (promised by caller)
+            //  - origin ownership is transferred to this function
+            let origin = unsafe { TCString::take_from_ptr_arg(origin) }.into_string()?;
+
+            // SAFETY:
+            //  - client_key is a valid Uuid (any 8-byte sequence counts)
+
+            let client_key = unsafe { TCUuid::val_from_arg(client_key) };
+            // SAFETY:
+            //  - encryption_secret is not NULL
+            //  - encryption_secret is valid (promised by caller)
+            //  - encryption_secret ownership is transferred to this function
+            let encryption_secret = unsafe { TCString::take_from_ptr_arg(encryption_secret) }
+                .as_bytes()
+                .to_vec();
+
+            let server_config = ServerConfig::Remote {
+                origin,
+                client_key,
+                encryption_secret,
+            };
+            let server = server_config.into_server()?;
+            // SAFETY: caller promises to free this server.
+            Ok(unsafe { TCServer::return_ptr(server.into()) })
+        },
+        error_out,
+        std::ptr::null_mut(),
+    )
+}
+
+/// Free a server.  The server may not be used after this function returns and must not be freed
+/// more than once.
+#[no_mangle]
+pub unsafe extern "C" fn tc_server_free(server: *mut TCServer) {
+    debug_assert!(!server.is_null());
+    // SAFETY:
+    //  - server is not NULL
+    //  - server came from tc_server_new_.., which used return_ptr
+    //  - server will not be used after (promised by caller)
+    let server = unsafe { TCServer::take_from_ptr_arg(server) };
+    drop(server);
+}

lib/src/string.rs

@@ -82,7 +82,7 @@ impl<'a> TCString<'a> {
         }
     }
 
-    fn as_bytes(&self) -> &[u8] {
+    pub(crate) fn as_bytes(&self) -> &[u8] {
         match self {
             TCString::CString(cstring) => cstring.as_bytes(),
             TCString::CStr(cstr) => cstr.to_bytes(),