Add fula-flutter crate for Flutter bindings

Introduces the new fula-flutter crate providing Flutter/Dart bindings for Fula decentralized storage, supporting Android and Web via flutter_rust_bridge. Implements API modules for client, encrypted, chunked, forest, sharing, rotation, and multipart operations, along with error handling and type definitions. Updates workspace configuration and documentation for Flutter and WASM integration.

Author: ehsan6sha

Cargo.lock

@@ -6,6 +6,7 @@ members = [
     "crates/fula-core",
     "crates/fula-cli",
     "crates/fula-client",
+    "crates/fula-flutter",
 ]
 
 # Root package for examples

Cargo.toml

@@ -0,0 +1,55 @@
+[package]
+name = "fula-flutter"
+description = "Flutter bindings for Fula decentralized storage - works on Android and Web"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+authors.workspace = true
+rust-version.workspace = true
+
+[lib]
+crate-type = ["cdylib", "staticlib", "lib"]
+
+[dependencies]
+# flutter_rust_bridge
+flutter_rust_bridge = "2"
+
+# Error handling
+anyhow = { workspace = true }
+thiserror = { workspace = true }
+
+# Async
+futures = { workspace = true }
+
+# Serialization
+serde = { workspace = true }
+serde_json = { workspace = true }
+
+# Time
+chrono = { workspace = true }
+
+# Utilities
+bytes = { workspace = true }
+
+# Thread safety
+parking_lot = { workspace = true }
+
+# Platform-specific dependencies
+[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
+# Native: fula-client with default features (includes tokio)
+fula-client = { path = "../fula-client" }
+fula-crypto = { path = "../fula-crypto" }
+
+[target.'cfg(target_arch = "wasm32")'.dependencies]
+# WASM: fula-client without tokio
+fula-client = { path = "../fula-client", default-features = false }
+fula-crypto = { path = "../fula-crypto", default-features = false, features = ["wasm"] }
+wasm-bindgen-futures = "0.4"
+
+[dev-dependencies]
+# For WASM tests
+wasm-bindgen-test = "0.3"
+
+[features]
+default = []

crates/fula-flutter/Cargo.toml

@@ -0,0 +1,70 @@
+//! Chunked/streaming operations
+//!
+//! Functions for handling large files using chunked encryption.
+//! Files above a certain threshold are automatically split into chunks.
+
+use crate::api::types::*;
+use crate::api::error::FulaResult;
+
+/// Default chunk size (256 KB)
+pub const DEFAULT_CHUNK_SIZE: u32 = 256 * 1024;
+
+/// Threshold for using chunked encryption (5 MB)
+pub const CHUNKED_THRESHOLD: u64 = 5 * 1024 * 1024;
+
+// ============================================================================
+// Chunked Operations
+// ============================================================================
+
+/// Upload a large file using chunked encryption
+///
+/// The file is split into chunks, each encrypted separately.
+/// This is more efficient for large files and enables partial downloads.
+pub async fn put_chunked(
+    client: &EncryptedClientHandle,
+    bucket: String,
+    key: String,
+    data: Vec<u8>,
+    chunk_size: Option<u32>,
+) -> FulaResult<PutResult> {
+    let guard = client.inner.read();
+    let chunk_size = chunk_size.map(|s| s as usize);
+    let result = guard.put_object_chunked(&bucket, &key, &data, chunk_size).await?;
+    Ok(result.into())
+}
+
+/// Download and decrypt a chunked file
+///
+/// Automatically handles reassembly of chunks.
+pub async fn get_chunked(
+    client: &EncryptedClientHandle,
+    bucket: String,
+    key: String,
+) -> FulaResult<Vec<u8>> {
+    let guard = client.inner.read();
+    let data = guard.get_object_chunked(&bucket, &key).await?;
+    Ok(data.to_vec())
+}
+
+/// Download a range of bytes from a file
+///
+/// For chunked files, only the necessary chunks are downloaded.
+/// This is efficient for large files when you only need part of the content.
+pub async fn get_range(
+    client: &EncryptedClientHandle,
+    bucket: String,
+    key: String,
+    offset: u64,
+    length: u64,
+) -> FulaResult<Vec<u8>> {
+    let guard = client.inner.read();
+    let data = guard.get_object_range(&bucket, &key, offset, length).await?;
+    Ok(data.to_vec())
+}
+
+/// Check if a file size warrants chunked upload
+///
+/// Returns true if the size is above the chunked threshold.
+pub fn should_use_chunked(size: u64) -> bool {
+    size > CHUNKED_THRESHOLD
+}

crates/fula-flutter/src/api/chunked.rs

@@ -0,0 +1,258 @@
+//! Core FulaClient wrapper operations
+//!
+//! These functions wrap the underlying FulaClient for plain (unencrypted) operations.
+
+use std::sync::Arc;
+use std::time::Duration;
+use bytes::Bytes;
+
+use crate::api::types::*;
+use crate::api::error::{FulaError, FulaResult};
+
+// ============================================================================
+// Client Creation
+// ============================================================================
+
+/// Create a new Fula client with the given configuration
+pub fn create_client(config: FulaConfig) -> FulaResult<FulaClientHandle> {
+    let inner_config = fula_client::Config::new(&config.endpoint)
+        .with_timeout(Duration::from_secs(config.timeout_seconds));
+
+    let inner_config = if let Some(token) = config.access_token {
+        inner_config.with_token(token)
+    } else {
+        inner_config
+    };
+
+    let client = fula_client::FulaClient::new(inner_config)?;
+
+    Ok(FulaClientHandle {
+        inner: Arc::new(client),
+    })
+}
+
+/// Create a new encrypted client with the given configuration
+pub fn create_encrypted_client(
+    config: FulaConfig,
+    encryption: EncryptionConfig,
+) -> FulaResult<EncryptedClientHandle> {
+    let inner_config = fula_client::Config::new(&config.endpoint)
+        .with_timeout(Duration::from_secs(config.timeout_seconds));
+
+    let inner_config = if let Some(token) = config.access_token {
+        inner_config.with_token(token)
+    } else {
+        inner_config
+    };
+
+    // Create encryption config
+    let enc_config = if let Some(secret_key) = encryption.secret_key {
+        if secret_key.len() != 32 {
+            return Err(FulaError::InvalidConfig(
+                "Secret key must be exactly 32 bytes".to_string()
+            ));
+        }
+        let mut key_bytes = [0u8; 32];
+        key_bytes.copy_from_slice(&secret_key);
+        let secret = fula_crypto::SecretKey::from_bytes(&key_bytes)
+            .map_err(|e| FulaError::Encryption(e.to_string()))?;
+        fula_client::EncryptionConfig::from_secret_key(secret)
+    } else {
+        fula_client::EncryptionConfig::new()
+    };
+
+    let enc_config = enc_config.with_metadata_privacy(encryption.enable_metadata_privacy);
+    let enc_config = match encryption.obfuscation_mode {
+        ObfuscationMode::Deterministic => {
+            enc_config.with_obfuscation_mode(fula_client::KeyObfuscation::DeterministicHash)
+        }
+        ObfuscationMode::Random => {
+            enc_config.with_obfuscation_mode(fula_client::KeyObfuscation::RandomUuid)
+        }
+    };
+
+    let client = fula_client::EncryptedClient::new(inner_config, enc_config)?;
+
+    Ok(EncryptedClientHandle {
+        inner: Arc::new(parking_lot::RwLock::new(client)),
+    })
+}
+
+/// Create encrypted client with pinning support
+pub fn create_encrypted_client_with_pinning(
+    config: FulaConfig,
+    encryption: EncryptionConfig,
+    pinning: PinningConfig,
+) -> FulaResult<EncryptedClientHandle> {
+    let inner_config = fula_client::Config::new(&config.endpoint)
+        .with_timeout(Duration::from_secs(config.timeout_seconds));
+
+    let inner_config = if let Some(token) = config.access_token {
+        inner_config.with_token(token)
+    } else {
+        inner_config
+    };
+
+    // Create encryption config
+    let enc_config = if let Some(secret_key) = encryption.secret_key {
+        if secret_key.len() != 32 {
+            return Err(FulaError::InvalidConfig(
+                "Secret key must be exactly 32 bytes".to_string()
+            ));
+        }
+        let mut key_bytes = [0u8; 32];
+        key_bytes.copy_from_slice(&secret_key);
+        let secret = fula_crypto::SecretKey::from_bytes(&key_bytes)
+            .map_err(|e| FulaError::Encryption(e.to_string()))?;
+        fula_client::EncryptionConfig::from_secret_key(secret)
+    } else {
+        fula_client::EncryptionConfig::new()
+    };
+
+    let enc_config = enc_config.with_metadata_privacy(encryption.enable_metadata_privacy);
+
+    let pinning_creds = fula_client::PinningCredentials::new(
+        pinning.endpoint,
+        pinning.token,
+    );
+
+    let client = fula_client::EncryptedClient::new_with_pinning(
+        inner_config,
+        enc_config,
+        pinning_creds,
+    )?;
+
+    Ok(EncryptedClientHandle {
+        inner: Arc::new(parking_lot::RwLock::new(client)),
+    })
+}
+
+// ============================================================================
+// Bucket Operations
+// ============================================================================
+
+/// List all buckets
+pub async fn list_buckets(client: &FulaClientHandle) -> FulaResult<Vec<BucketInfo>> {
+    let result = client.inner.list_buckets().await?;
+    Ok(result.buckets.into_iter().map(|b| b.into()).collect())
+}
+
+/// Create a new bucket
+pub async fn create_bucket(client: &FulaClientHandle, name: String) -> FulaResult<()> {
+    client.inner.create_bucket(&name).await?;
+    Ok(())
+}
+
+/// Delete a bucket
+pub async fn delete_bucket(client: &FulaClientHandle, name: String) -> FulaResult<()> {
+    client.inner.delete_bucket(&name).await?;
+    Ok(())
+}
+
+/// Check if a bucket exists
+pub async fn bucket_exists(client: &FulaClientHandle, name: String) -> FulaResult<bool> {
+    Ok(client.inner.bucket_exists(&name).await?)
+}
+
+// ============================================================================
+// Object Operations
+// ============================================================================
+
+/// Upload an object
+pub async fn put_object(
+    client: &FulaClientHandle,
+    bucket: String,
+    key: String,
+    data: Vec<u8>,
+) -> FulaResult<PutResult> {
+    let result = client.inner.put_object(&bucket, &key, Bytes::from(data)).await?;
+    Ok(result.into())
+}
+
+/// Upload an object with metadata
+pub async fn put_object_with_metadata(
+    client: &FulaClientHandle,
+    bucket: String,
+    key: String,
+    data: Vec<u8>,
+    metadata: ObjectMetadata,
+) -> FulaResult<PutResult> {
+    let result = client.inner.put_object_with_metadata(
+        &bucket,
+        &key,
+        Bytes::from(data),
+        Some(metadata.into()),
+    ).await?;
+    Ok(result.into())
+}
+
+/// Download an object
+pub async fn get_object(
+    client: &FulaClientHandle,
+    bucket: String,
+    key: String,
+) -> FulaResult<Vec<u8>> {
+    let data = client.inner.get_object(&bucket, &key).await?;
+    Ok(data.to_vec())
+}
+
+/// Download an object with metadata
+pub async fn get_object_with_metadata(
+    client: &FulaClientHandle,
+    bucket: String,
+    key: String,
+) -> FulaResult<GetObjectResult> {
+    let result = client.inner.get_object_with_metadata(&bucket, &key).await?;
+    Ok(result.into())
+}
+
+/// Get object metadata without downloading content
+pub async fn head_object(
+    client: &FulaClientHandle,
+    bucket: String,
+    key: String,
+) -> FulaResult<HeadResult> {
+    let result = client.inner.head_object(&bucket, &key).await?;
+    Ok(result.into())
+}
+
+/// Delete an object
+pub async fn delete_object(
+    client: &FulaClientHandle,
+    bucket: String,
+    key: String,
+) -> FulaResult<()> {
+    client.inner.delete_object(&bucket, &key).await?;
+    Ok(())
+}
+
+/// Check if an object exists
+pub async fn object_exists(
+    client: &FulaClientHandle,
+    bucket: String,
+    key: String,
+) -> FulaResult<bool> {
+    Ok(client.inner.object_exists(&bucket, &key).await?)
+}
+
+/// Copy an object
+pub async fn copy_object(
+    client: &FulaClientHandle,
+    src_bucket: String,
+    src_key: String,
+    dst_bucket: String,
+    dst_key: String,
+) -> FulaResult<CopyResult> {
+    let result = client.inner.copy_object(&src_bucket, &src_key, &dst_bucket, &dst_key).await?;
+    Ok(result.into())
+}
+
+/// List objects in a bucket
+pub async fn list_objects(
+    client: &FulaClientHandle,
+    bucket: String,
+    options: ListOptions,
+) -> FulaResult<ListObjectsResult> {
+    let result = client.inner.list_objects(&bucket, Some(options.into())).await?;
+    Ok(result.into())
+}