ipfrs_interface/
lib.rs

1//! IPFRS Interface - High-performance HTTP Gateway and API Layer
2//!
3//! This crate provides a comprehensive API layer for IPFRS (InterPlanetary File & Reasoning System),
4//! offering multiple interfaces for accessing distributed content and computation.
5//!
6//! # Features
7//!
8//! ## HTTP Gateway
9//! - **Kubo-compatible API** (`/api/v0/*`) - Full compatibility with IPFS Kubo clients
10//! - **High-speed v1 API** (`/v1/*`) - Optimized endpoints with batch operations
11//! - **Content gateway** (`/ipfs/{cid}`) - Direct content retrieval with range requests
12//! - **Multi-range support** - Efficient sparse downloads with HTTP 206
13//!
14//! ## gRPC Interface
15//! - **BlockService** - Raw block operations (Get, Put, Has, Delete, Batch)
16//! - **DagService** - DAG operations (Get, Put, Resolve, Traverse)
17//! - **FileService** - File operations (Add, Get, List, Pin)
18//! - **TensorService** - Zero-copy tensor operations (Get, Slice, Stream)
19//! - **Streaming RPCs** - Client, server, and bidirectional streaming
20//! - **Interceptors** - Authentication, logging, metrics, rate limiting
21//!
22//! ## WebSocket Support
23//! - **Real-time events** - Block additions, peer connections, DHT queries
24//! - **Pub/sub system** - Topic-based event subscriptions
25//! - **Connection management** - Automatic cleanup and heartbeat
26//!
27//! ## Advanced Features
28//! - **Zero-copy tensor API** - Efficient ML model distribution via Safetensors
29//! - **Streaming uploads/downloads** - Memory-efficient large file handling
30//! - **Batch operations** - Parallel processing with atomic transactions
31//! - **Flow control** - Adaptive window-based congestion control
32//! - **Resume/cancel** - Robust transfer management
33//!
34//! ## Security & Performance
35//! - **Authentication** - JWT tokens, API keys, and OAuth2 (Authorization Code, Client Credentials, PKCE)
36//! - **Rate limiting** - Token bucket algorithm with per-client limits
37//! - **CORS** - Configurable cross-origin resource sharing
38//! - **Compression** - Gzip, Brotli, and Deflate with tunable levels
39//! - **HTTP caching** - ETag and Cache-Control for CDN optimization
40//! - **TLS/HTTPS** - Production-ready SSL/TLS support
41//!
42//! # Quick Start
43//!
44//! ```rust,ignore
45//! // Example usage (see examples/server.rs for a complete working example)
46//! use ipfrs_interface::GatewayConfig;
47//! use ipfrs_storage::blockstore::BlockStoreConfig;
48//!
49//! #[tokio::main]
50//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
51//!     // Create gateway with default configuration
52//!     let storage_config = BlockStoreConfig::default();
53//!     let mut gateway_config = GatewayConfig::default();
54//!     gateway_config.storage_config = storage_config;
55//!     gateway_config.listen_addr = "127.0.0.1:8080".to_string();
56//!
57//!     // See /tmp/example_server.rs for complete implementation
58//!     Ok(())
59//! }
60//! ```
61//!
62//! # Examples
63//!
64//! ## Upload a file (Kubo v0 API)
65//! ```bash
66//! curl -X POST -F "file=@myfile.txt" http://localhost:8080/api/v0/add
67//! ```
68//!
69//! ## Download via gateway
70//! ```bash
71//! curl http://localhost:8080/ipfs/<CID>
72//! ```
73//!
74//! ## Batch block operations (v1 API)
75//! ```bash
76//! curl -X POST -H "Content-Type: application/json" \
77//!   -d '{"cids":["<CID1>","<CID2>"]}' \
78//!   http://localhost:8080/v1/block/batch/get
79//! ```
80//!
81//! ## Get tensor slice (zero-copy)
82//! ```bash
83//! curl "http://localhost:8080/v1/tensor/<CID>?slice=0:10,5:15"
84//! ```
85//!
86//! # Architecture
87//!
88//! ```text
89//! ┌─────────────────┐
90//! │  HTTP Clients   │ (curl, browsers, IPFS clients)
91//! └────────┬────────┘
92//!          │
93//! ┌────────▼────────┐
94//! │  Axum Router    │ (HTTP/HTTPS)
95//! ├─────────────────┤
96//! │  Middleware     │ (CORS, Auth, Rate Limit, Compression)
97//! ├─────────────────┤
98//! │  API Handlers   │ (v0, v1, Gateway, WebSocket)
99//! └────────┬────────┘
100//!          │
101//! ┌────────▼────────┐
102//! │  gRPC Server    │ (Tonic)
103//! ├─────────────────┤
104//! │  Interceptors   │ (Auth, Logging, Metrics)
105//! ├─────────────────┤
106//! │  Services       │ (Block, DAG, File, Tensor)
107//! └────────┬────────┘
108//!          │
109//! ┌────────▼────────┐
110//! │  Core Layer     │ (ipfrs-core, ipfrs-storage, etc.)
111//! └─────────────────┘
112//! ```
113//!
114//! # Performance
115//!
116//! Target performance characteristics:
117//! - Request latency: < 10ms (simple GET)
118//! - Throughput: > 1GB/s (range requests)
119//! - Concurrent connections: 10,000+
120//! - Memory per connection: < 100KB
121//!
122//! # See Also
123//!
124//! - [`Gateway`] - Main HTTP gateway implementation
125//! - [`middleware`] - CORS, rate limiting, and compression
126//! - [`streaming`] - Streaming operations and flow control
127//! - [`websocket`] - WebSocket real-time events
128
129pub mod arrow;
130pub mod auth;
131pub mod auth_handlers;
132pub mod backpressure;
133pub mod binary_protocol;
134pub mod ffi;
135pub mod gateway;
136pub mod graphql;
137// TODO: Re-enable when tonic-build 0.14 service generation is properly configured
138// pub mod grpc;
139pub mod metrics;
140pub mod metrics_middleware;
141pub mod middleware;
142pub mod mmap;
143pub mod oauth2;
144pub mod python;
145pub mod safetensors;
146pub mod streaming;
147pub mod tensor;
148pub mod tls;
149pub mod websocket;
150pub mod zerocopy;
151
152pub use backpressure::{
153    BackpressureConfig, BackpressureController, BackpressureError, BackpressurePermit,
154    BackpressureStream,
155};
156pub use binary_protocol::{
157    BinaryMessage, ErrorResponse, GetBlockRequest, HasBlockRequest, MessageType, ProtocolError,
158    PutBlockRequest, SuccessResponse, PROTOCOL_VERSION,
159};
160pub use gateway::{Gateway, GatewayConfig};
161pub use graphql::{create_schema, IpfrsSchema};
162pub use middleware::{
163    cors_middleware, rate_limit_middleware, CacheConfig, CompressionConfig, CompressionLevel,
164    CorsConfig, CorsState, RateLimitConfig, RateLimitState,
165};
166pub use mmap::{MmapCache, MmapConfig, MmapError, MmapFile};
167pub use oauth2::{
168    AccessToken, AuthorizationCode, CodeChallengeMethod, ErrorResponse as OAuth2ErrorResponse,
169    GrantType, OAuth2Client, OAuth2ProviderConfig, OAuth2Server, RefreshToken, ResponseType, Scope,
170    TokenResponse, TokenType,
171};
172pub use safetensors::{SafetensorsFile, SafetensorsHeader, TensorData, TensorInfo};
173pub use streaming::{
174    ConcurrencyConfig, FlowControlConfig, FlowController, OperationState, OperationStatus,
175    OperationType, ProgressEvent, ProgressTracker, ResumeToken,
176};
177pub use tensor::{TensorLayout, TensorMetadata, TensorSlice};
178pub use websocket::{ws_handler, RealtimeEvent, SubscriptionManager, WsMessage, WsState};
179pub use zerocopy::ZeroCopyBuffer;
180
181// gRPC exports
182// TODO: Re-enable when tonic-build 0.14 service generation is properly configured
183// pub use grpc::{
184//     backpressure_support, AuthInterceptor, BlockServiceImpl, BlockServiceServer,
185//     ChainedInterceptor, DagServiceImpl, DagServiceServer, FileServiceImpl, FileServiceServer,
186//     GrpcServiceConfig, LoggingInterceptor, MetricsInterceptor, RateLimitInterceptor,
187//     TensorServiceImpl, TensorServiceServer,
188// };
ipfrs_interface/lib.rs

ipfrs_interface/
lib.rs
