Phase 2 build initial

sdks/rust/Cargo.toml

@@ -0,0 +1,83 @@
+[package]
+name = "hcfs-sdk"
+version = "2.0.0"
+edition = "2021"
+description = "Rust SDK for the Context-Aware Hierarchical Context File System"
+license = "MIT"
+repository = "https://github.com/hcfs/hcfs"
+homepage = "https://docs.hcfs.dev/sdk/rust"
+documentation = "https://docs.rs/hcfs-sdk"
+keywords = ["hcfs", "context", "ai", "search", "embeddings"]
+categories = ["api-bindings", "web-programming::http-client"]
+authors = ["HCFS Development Team <dev@hcfs.dev>"]
+readme = "README.md"
+rust-version = "1.70"
+
+[dependencies]
+# HTTP client
+reqwest = { version = "0.11", features = ["json", "rustls-tls"], default-features = false }
+
+# Async runtime
+tokio = { version = "1.0", features = ["full"] }
+
+# Serialization
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+
+# Error handling
+thiserror = "1.0"
+anyhow = "1.0"
+
+# Time handling
+chrono = { version = "0.4", features = ["serde"] }
+
+# WebSocket support
+tokio-tungstenite = { version = "0.20", optional = true, features = ["rustls-tls-webpki-roots"] }
+futures-util = { version = "0.3", optional = true }
+
+# Caching
+moka = { version = "0.12", features = ["future"], optional = true }
+
+# Retry logic
+backoff = { version = "0.4", optional = true }
+
+# Rate limiting
+governor = { version = "0.6", optional = true }
+
+# Metrics
+prometheus = { version = "0.13", optional = true }
+
+# Tracing
+tracing = { version = "0.1", optional = true }
+
+# URL handling
+url = "2.4"
+
+# UUID for request IDs
+uuid = { version = "1.0", features = ["v4"] }
+
+[dev-dependencies]
+tokio-test = "0.4"
+wiremock = "0.5"
+
+[features]
+default = ["cache", "retry", "rate-limit"]
+websocket = ["tokio-tungstenite", "futures-util"]
+cache = ["moka"]
+retry = ["backoff"]
+rate-limit = ["governor"]
+metrics = ["prometheus"]
+tracing = ["dep:tracing"]
+full = ["websocket", "cache", "retry", "rate-limit", "metrics", "tracing"]
+
+[[example]]
+name = "basic_usage"
+required-features = ["cache"]
+
+[[example]]
+name = "websocket_streaming"
+required-features = ["websocket"]
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

sdks/rust/src/lib.rs

@@ -0,0 +1,146 @@
+//! # HCFS Rust SDK
+//! 
+//! A comprehensive Rust SDK for the Context-Aware Hierarchical Context File System (HCFS).
+//! This SDK provides both synchronous and asynchronous clients with full type safety,
+//! error handling, and advanced features like caching, retry logic, and WebSocket streaming.
+//! 
+//! ## Features
+//! 
+//! - **Type-safe API**: Full Rust type safety with comprehensive error handling
+//! - **Async/await support**: Built on tokio for high-performance async operations
+//! - **WebSocket streaming**: Real-time event notifications (with `websocket` feature)
+//! - **Intelligent caching**: Multiple caching strategies (with `cache` feature)
+//! - **Retry logic**: Configurable retry mechanisms with backoff (with `retry` feature)
+//! - **Rate limiting**: Built-in rate limiting support (with `rate-limit` feature)
+//! - **Observability**: Metrics and tracing support (with `metrics` and `tracing` features)
+//! 
+//! ## Quick Start
+//! 
+//! ```rust
+//! use hcfs_sdk::{Client, Context, Config};
+//! 
+//! #[tokio::main]
+//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
+//!     let config = Config::new("https://api.hcfs.dev/v1", "your-api-key");
+//!     let client = Client::new(config);
+//!     
+//!     let context = Context::builder()
+//!         .path("/docs/readme")
+//!         .content("Hello, HCFS!")
+//!         .summary("Getting started guide")
+//!         .build()?;
+//!     
+//!     let created = client.create_context(context).await?;
+//!     println!("Created context: {}", created.id.unwrap());
+//!     
+//!     let results = client.search_contexts("hello world").await?;
+//!     for result in results {
+//!         println!("Found: {} (score: {:.3})", result.context.path, result.score);
+//!     }
+//!     
+//!     Ok(())
+//! }
+//! ```
+//! 
+//! ## WebSocket Streaming
+//! 
+//! With the `websocket` feature enabled:
+//! 
+//! ```rust,no_run
+//! use hcfs_sdk::{Client, Config, StreamEvent};
+//! use futures_util::StreamExt;
+//! 
+//! #[tokio::main]
+//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
+//!     let config = Config::new("wss://api.hcfs.dev/v1", "your-api-key");
+//!     let client = Client::new(config);
+//!     
+//!     let mut stream = client.stream_events(Some("/docs")).await?;
+//!     
+//!     while let Some(event) = stream.next().await {
+//!         match event {
+//!             Ok(StreamEvent::ContextCreated { context, .. }) => {
+//!                 println!("New context created: {}", context.path);
+//!             }
+//!             Ok(StreamEvent::ContextUpdated { context, .. }) => {
+//!                 println!("Context updated: {}", context.path);
+//!             }
+//!             Ok(StreamEvent::ContextDeleted { path, .. }) => {
+//!                 println!("Context deleted: {}", path);
+//!             }
+//!             Err(e) => eprintln!("Stream error: {}", e),
+//!         }
+//!     }
+//!     
+//!     Ok(())
+//! }
+//! ```
+
+pub mod client;
+pub mod types;
+pub mod error;
+pub mod config;
+
+#[cfg(feature = "cache")]
+pub mod cache;
+
+#[cfg(feature = "retry")]
+pub mod retry;
+
+#[cfg(feature = "websocket")]
+pub mod websocket;
+
+// Re-exports
+pub use client::Client;
+pub use types::*;
+pub use error::{Error, Result};
+pub use config::Config;
+
+#[cfg(feature = "websocket")]
+pub use websocket::{WebSocketClient, StreamEvent};
+
+/// SDK version
+pub const VERSION: &str = env!("CARGO_PKG_VERSION");
+
+/// Default configuration values
+pub mod defaults {
+    use std::time::Duration;
+    
+    /// Default request timeout
+    pub const TIMEOUT: Duration = Duration::from_secs(30);
+    
+    /// Default maximum retry attempts
+    pub const MAX_RETRIES: usize = 3;
+    
+    /// Default retry base delay
+    pub const RETRY_BASE_DELAY: Duration = Duration::from_millis(1000);
+    
+    /// Default cache size
+    pub const CACHE_SIZE: u64 = 1000;
+    
+    /// Default cache TTL
+    pub const CACHE_TTL: Duration = Duration::from_secs(3600);
+    
+    /// Default rate limit (requests per second)
+    pub const RATE_LIMIT: u32 = 100;
+    
+    /// Default user agent
+    pub const USER_AGENT: &str = concat!("hcfs-rust/", env!("CARGO_PKG_VERSION"));
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    
+    #[test]
+    fn test_version() {
+        assert!(!VERSION.is_empty());
+    }
+    
+    #[tokio::test]
+    async fn test_client_creation() {
+        let config = Config::new("https://api.example.com", "test-key");
+        let _client = Client::new(config);
+        // Just test that client creation doesn't panic
+    }
+}