Expose tier storage configuration across the FFI boundary

Introduce FFI-safe abstractions and builder APIs to allow foreign
language targets to configure custom backup and ephemeral stores when
constructing nodes with a custom store.

Major changes include:

- Addition of FfiDynStoreTrait, an FFI-safe equivalent of DynStoreTrait,
  working around uniffi's lack of support for Pin<Box<T>>
- Addition of FfiDynStore, a concrete wrapper for foreign language store
  implementations
- Provision of FfiDynStoreTrait implementation for DynStoreWrapper to bridge
  native Rust stores to FFI layer (useful in testing)
- Extension of ArcedNodeBuilder with methods for configuring backup and
  ephemeral stores
- Exposure of build_with_store so foreign targets can build nodes with
  custom store implementations
- Addition of build_node_with_store test helper to abstract uniffi-gated
  store wrapping at build_with_store call sites

Author: enigbe

Cargo.toml

@@ -63,6 +63,7 @@ bitcoin = "0.32.7"
 bip39 = { version = "2.0.0", features = ["rand"] }
 bip21 = { version = "0.5", features = ["std"], default-features = false }
 
+async-trait = { version = "0.1.89" }
 base64 = { version = "0.22.1", default-features = false, features = ["std"] }
 rand = { version = "0.9.2", default-features = false, features = ["std", "thread_rng", "os_rng"] }
 chrono = { version = "0.4", default-features = false, features = ["clock"] }

bindings/ldk_node.udl

@@ -103,6 +103,53 @@ interface LogWriter {
 	void log(LogRecord record);
 };
 
+interface FfiDynStore {
+    [Name=from_store]
+    constructor(FfiDynStoreTrait store);
+};
+
+[Trait, WithForeign]
+interface FfiDynStoreTrait {
+    [Throws=IOError]
+    sequence<u8> read(string primary_namespace, string secondary_namespace, string key);
+    [Throws=IOError]
+    void write(string primary_namespace, string secondary_namespace, string key, sequence<u8> buf);
+    [Throws=IOError]
+    void remove(string primary_namespace, string secondary_namespace, string key, boolean lazy);
+    [Throws=IOError]
+    sequence<string> list(string primary_namespace, string secondary_namespace);
+    [Throws=IOError, Async]
+    sequence<u8> read_async(string primary_namespace, string secondary_namespace, string key);
+    [Throws=IOError, Async]
+    void write_async(string primary_namespace, string secondary_namespace, string key, sequence<u8> buf);
+    [Throws=IOError, Async]
+    void remove_async(string primary_namespace, string secondary_namespace, string key,  boolean lazy);
+    [Throws=IOError, Async]
+    sequence<string> list_async(string primary_namespace, string secondary_namespace);
+};
+
+[Error]
+enum IOError {
+  	"NotFound",
+    "PermissionDenied",
+    "ConnectionRefused",
+    "ConnectionReset",
+    "ConnectionAborted",
+    "NotConnected",
+    "AddrInUse",
+    "AddrNotAvailable",
+    "BrokenPipe",
+    "AlreadyExists",
+    "WouldBlock",
+    "InvalidInput",
+    "InvalidData",
+    "TimedOut",
+    "WriteZero",
+    "Interrupted",
+    "UnexpectedEof",
+    "Other",
+};
+
 interface Builder {
 	constructor();
 	[Name=from_config]
@@ -127,6 +174,8 @@ interface Builder {
 	void set_announcement_addresses(sequence<SocketAddress> announcement_addresses);
 	[Throws=BuildError]
 	void set_node_alias(string node_alias);
+	void set_backup_store(FfiDynStore backup_store);
+	void set_ephemeral_store(FfiDynStore ephemeral_store);
 	[Throws=BuildError]
 	void set_async_payments_role(AsyncPaymentsRole? role);
 	void set_wallet_recovery_mode();
@@ -140,6 +189,8 @@ interface Builder {
 	Node build_with_vss_store_and_fixed_headers(NodeEntropy node_entropy, string vss_url, string store_id, record<string, string> fixed_headers);
 	[Throws=BuildError]
 	Node build_with_vss_store_and_header_provider(NodeEntropy node_entropy, string vss_url, string store_id, VssHeaderProvider header_provider);
+	[Throws=BuildError]
+	Node build_with_store(NodeEntropy node_entropy, FfiDynStore store);
 };
 
 interface Node {

src/builder.rs

@@ -52,6 +52,8 @@ use crate::connection::ConnectionManager;
 use crate::entropy::NodeEntropy;
 use crate::event::EventQueue;
 use crate::fee_estimator::OnchainFeeEstimator;
+#[cfg(feature = "uniffi")]
+use crate::ffi::FfiDynStore;
 use crate::gossip::GossipSource;
 use crate::io::sqlite_store::SqliteStore;
 use crate::io::tier_store::TierStore;
@@ -582,7 +584,6 @@ impl NodeBuilder {
 	/// of all critical data written to the primary store.
 	///
 	/// Backup writes are non-blocking and do not affect primary store operation performance.
-	#[allow(dead_code)]
 	pub fn set_backup_store(&mut self, backup_store: Arc<DynStore>) -> &mut Self {
 		let tier_store_config = self.tier_store_config.get_or_insert(TierStoreConfig::default());
 		tier_store_config.backup = Some(backup_store);
@@ -596,7 +597,6 @@ impl NodeBuilder {
 	/// can be rebuilt if lost.
 	///
 	/// If not set, non-critical data will be stored in the primary store.
-	#[allow(dead_code)]
 	pub fn set_ephemeral_store(&mut self, ephemeral_store: Arc<DynStore>) -> &mut Self {
 		let tier_store_config = self.tier_store_config.get_or_insert(TierStoreConfig::default());
 		tier_store_config.ephemeral = Some(ephemeral_store);
@@ -1005,6 +1005,32 @@ impl ArcedNodeBuilder {
 		self.inner.write().unwrap().set_wallet_recovery_mode();
 	}
 
+	/// Configures the backup store for local disaster recovery.
+	///
+	/// When building with tiered storage, this store receives asynchronous copies
+	/// of all critical data written to the primary store.
+	///
+	/// Backup writes are non-blocking and do not affect primary store operation performance.
+	///
+	pub fn set_backup_store(&self, backup_store: Arc<FfiDynStore>) {
+		let wrapper = DynStoreWrapper((*backup_store).clone());
+		let store: Arc<DynStore> = Arc::new(wrapper);
+		self.inner.write().unwrap().set_backup_store(store);
+	}
+
+	/// Configures the ephemeral store for non-critical, frequently-accessed data.
+	///
+	/// When building with tiered storage, this store is used for ephemeral data like
+	/// the network graph and scorer data to reduce latency for reads. Data stored here
+	/// can be rebuilt if lost.
+	///
+	/// If not set, non-critical data will be stored in the primary store.
+	pub fn set_ephemeral_store(&self, ephemeral_store: Arc<FfiDynStore>) {
+		let wrapper = DynStoreWrapper((*ephemeral_store).clone());
+		let store: Arc<DynStore> = Arc::new(wrapper);
+		self.inner.write().unwrap().set_ephemeral_store(store);
+	}
+
 	/// Builds a [`Node`] instance with a [`SqliteStore`] backend and according to the options
 	/// previously configured.
 	pub fn build(&self, node_entropy: Arc<NodeEntropy>) -> Result<Arc<Node>, BuildError> {
@@ -1104,12 +1130,19 @@ impl ArcedNodeBuilder {
 	}
 
 	/// Builds a [`Node`] instance according to the options previously configured.
-	// Note that the generics here don't actually work for Uniffi, but we don't currently expose
-	// this so its not needed.
-	pub fn build_with_store<S: SyncAndAsyncKVStore + Send + Sync + 'static>(
-		&self, node_entropy: Arc<NodeEntropy>, kv_store: S,
+	///
+	/// The provided `kv_store` will be used as the primary storage backend. Optionally,
+	/// an ephemeral store for frequently-accessed non-critical data (e.g., network graph, scorer)
+	/// and a backup store for local disaster recovery can be configured via
+	/// [`set_ephemeral_store`] and [`set_backup_store`].
+	///
+	/// [`set_ephemeral_store`]: Self::set_ephemeral_store
+	/// [`set_backup_store`]: Self::set_backup_store
+	pub fn build_with_store(
+		&self, node_entropy: Arc<NodeEntropy>, kv_store: Arc<FfiDynStore>,
 	) -> Result<Arc<Node>, BuildError> {
-		self.inner.read().unwrap().build_with_store(*node_entropy, kv_store).map(Arc::new)
+		let store = (*kv_store).clone();
+		self.inner.read().unwrap().build_with_store(*node_entropy, store).map(Arc::new)
 	}
 }