Unified Multi-Channel Push SDK with End-to-End Encryption
Features • Quick Start • Documentation • Examples • Contributing
Click to expand
|
|
|
|
graph LR
A[Application] --> B[UnifiedPush SDK]
B --> C[Channel Router]
C --> D[LAN Channel]
C --> E[WiFi Channel]
C --> F[Bluetooth Channel]
C --> G[Mesh Channel]
C --> H[Memory Channel]
C --> I[Remote Channel]
D --> J[Network Layer]
E --> J
F --> J
G --> J
H --> J
I --> J
💼 Local Network Messaging
Perfect for office, home, or industrial environments where devices communicate over local networks without internet dependency.
use std::sync::Arc;
use xlink::channels::lan::LanChannel;
use xlink::xLink;
let lan_channel: Arc<dyn xlink::core::traits::Channel> = Arc::new(LanChannel::new());
let sdk = xLink::new(capabilities, vec![lan_channel]).await?;
sdk.start().await?;📱 Mesh Network Communication
Ideal for ad-hoc networks, IoT deployments, and scenarios where devices form peer-to-peer mesh networks.
use std::sync::Arc;
use xlink::channels::mesh::MeshChannel;
let mesh_channel: Arc<dyn xlink::core::traits::Channel> = Arc::new(MeshChannel::new());
let sdk = xLink::new(capabilities, vec![mesh_channel]).await?;🔒 Secure Group Chat
Enterprise-grade encrypted group messaging with TreeKem forward secrecy and efficient broadcast.
use xlink::core::types::{DeviceId, MessagePayload};
let group_manager = sdk.group_manager();
group_manager.create_group(vec![alice_id, bob_id]).await?;
group_manager.broadcast_message(group_id, payload).await?;📹 Large File Transfer
Automatic stream handling for large files and video streams with chunking and reassembly.
use xlink::core::types::MessagePayload;
let large_data = std::fs::read("large_file.mp4")?;
sdk.send(recipient, MessagePayload::Binary(large_data)).await?;
// Automatically uses stream transmission for data > 32KB
[dependencies]
xlink = "0.1" |
[dependencies]
xlink = { version = "0.1", features = ["full"] } |
|
Step 1: Define Device Capabilities use xlink::core::types::{
ChannelType, DeviceCapabilities, DeviceId, DeviceType,
};
use std::collections::HashSet;
let device_id = DeviceId::new();
let capabilities = DeviceCapabilities {
device_id,
device_type: DeviceType::Smartphone,
device_name: "My Phone".to_string(),
supported_channels: HashSet::from([
ChannelType::Lan,
ChannelType::BluetoothLE,
]),
battery_level: Some(80),
is_charging: false,
data_cost_sensitive: false,
}; |
Step 2: Create SDK Instance use xlink::xLink;
use xlink::channels::memory::MemoryChannel;
let channel = Arc::new(MemoryChannel::new(handler, 50));
let sdk = xLink::new(capabilities, vec![channel]).await?;
sdk.start().await?; |
📖 Complete Example
use std::collections::HashSet;
use std::sync::Arc;
use xlink::channels::memory::MemoryChannel;
use xlink::core::types::{
ChannelType, DeviceCapabilities, DeviceId, DeviceType, MessagePayload,
};
use xlink::xLink;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let alice_id = DeviceId::new();
let alice_caps = DeviceCapabilities {
device_id: alice_id,
device_type: DeviceType::Smartphone,
device_name: "Alice Phone".to_string(),
supported_channels: HashSet::from([ChannelType::Lan]),
battery_level: Some(80),
is_charging: false,
data_cost_sensitive: false,
};
let channel = Arc::new(MemoryChannel::new(handler, 50));
let sdk = xLink::new(alice_caps, vec![channel]).await?;
sdk.start().await?;
// Send a message
let bob_id = DeviceId::new();
sdk.send(bob_id, MessagePayload::Text("Hello!".to_string())).await?;
sdk.stop().await;
Ok(())
}
 User Guide Complete usage guide |
 API Reference Full API documentation |
 Architecture System design docs |
 Examples Code examples |
- 🎓 Tutorials - Step-by-step learning
- 🔧 Advanced Topics - Deep dive guides
- ❓ FAQ - Frequently asked questions
- 🐛 Troubleshooting - Common issues
|
Basic point-to-point messaging between two devices. File: examples/simple_chat.rs use xlink::channels::memory::MemoryChannel;
use xlink::core::types::{ChannelType, DeviceCapabilities, MessagePayload};
use xlink::xLink;
let sdk = xLink::new(capabilities, vec![channel]).await?;
sdk.start().await?;
sdk.send(recipient, MessagePayload::Text("Hello".to_string())).await?; |
Secure group messaging with multiple participants. File: examples/group_chat.rs use xlink::group::manager::GroupManager;
let group_manager = sdk.group_manager();
let group_id = group_manager.create_group(members).await?;
group_manager.broadcast_message(group_id, payload).await?; |
|
Dynamic channel management and switching. File: examples/channel_switching.rs use xlink::channels::wifi::WifiChannel;
use xlink::channels::bluetooth::BluetoothChannel;
let wifi = Arc::new(WifiChannel::new());
let bluetooth = Arc::new(BluetoothChannel::new());
let sdk = xLink::new(capabilities, vec![wifi, bluetooth]).await?; |
Device discovery in background mode. File: examples/background_discovery.rs sdk.start().await?;
// Discovery runs automatically in background
// mDNS and BLE discovery are enabled by default |
|
Export and import SDK state for device transfer. File: examples/device_migration.rs let state = sdk.export_sdk_state()?;
std::fs::write("backup.dat", &state)?;
// On new device
let data = std::fs::read("backup.dat")?;
sdk.import_sdk_state(&data)?; |
graph TB
subgraph Application Layer
A[Application]
end
subgraph SDK Core
B[UnifiedPush SDK]
C[Channel Router]
D[Capability Manager]
E[Metrics Collector]
end
subgraph Communication Layer
F[LAN Channel]
G[WiFi Channel]
H[Bluetooth Channel]
I[Mesh Channel]
J[Memory Channel]
K[Remote Channel]
end
subgraph Security Layer
L[Crypto Engine]
M[TreeKem]
end
subgraph Services
N[Group Manager]
O[Heartbeat Manager]
P[Discovery Manager]
Q[Stream Manager]
end
subgraph Storage Layer
R[File Storage]
S[Memory Storage]
T[Distributed Storage]
end
A --> B
B --> C
B --> D
B --> E
C --> F
C --> G
C --> H
C --> I
C --> J
C --> K
C --> L
C --> M
B --> N
B --> O
B --> P
B --> Q
C --> R
C --> S
C --> T
📐 Component Details
| Component | Description | Status |
|---|---|---|
| UnifiedPush SDK | Main SDK entry point managing all components | ✅ Stable |
| Channel Router | Intelligent routing based on capabilities and network | ✅ Stable |
| Capability Manager | Device and channel capability detection and management | ✅ Stable |
| Crypto Engine | X25519 key exchange, ChaCha20Poly1305 encryption | ✅ Stable |
| TreeKem | Group key management with forward secrecy | ✅ Stable |
| Group Manager | Group creation, membership, and broadcast | ✅ Stable |
| Heartbeat Manager | Connection health monitoring | ✅ Stable |
| Discovery Manager | mDNS and BLE device discovery | ✅ Stable |
| Stream Manager | Large file chunking and reassembly | ✅ Stable |
| Metrics Collector | Performance monitoring and diagnostics | ✅ Stable |
use xlink::core::types::{ChannelType, DeviceCapabilities, DeviceType};
let capabilities = DeviceCapabilities {
device_id: DeviceId::new(),
device_type: DeviceType::Smartphone,
device_name: "My Device".to_string(),
supported_channels: HashSet::from([
ChannelType::Lan,
ChannelType::BluetoothLE,
ChannelType::WiFiDirect,
]),
battery_level: Some(100),
is_charging: true,
data_cost_sensitive: false,
};| Channel Type | Description | Use Case |
|---|---|---|
Lan |
Local Area Network communication | Office, home networks |
WiFiDirect |
WiFi direct communication | Wireless direct connection |
BluetoothLE |
Bluetooth Low Energy | Short-range, low power |
BluetoothMesh |
Bluetooth Mesh networking | Multi-hop mesh, IoT |
Internet |
Cloud/Internet communication | Remote messaging |
Memory |
In-memory channel (testing) | Testing, IPC |
🔧 All Configuration Options
| Option | Type | Default | Description |
|---|---|---|---|
device_id |
UUID | Auto-generated | Unique device identifier |
device_type |
Enum | Required | Device type (Smartphone, Laptop, etc.) |
device_name |
String | Required | Human-readable device name |
supported_channels |
Set | Required | Set of supported channel types |
battery_level |
Option | None | Current battery percentage |
is_charging |
bool | false | Whether device is charging |
data_cost_sensitive |
bool | false | Optimize for data usage |
use xlink::core::types::ComplianceConfig;
let compliance = ComplianceConfig {
retention_days: 30, // Keep data for 30 days
auto_cleanup: true, // Enable automatic cleanup
};# Run all tests
cargo test --all-features
# Run specific test categories
cargo test --test unit_core # Unit tests
cargo test --test integration_system # Integration tests
cargo test --test integration_group # Group messaging tests
cargo test --test integration_channels # Channel tests
# Run with coverage
cargo tarpaulin --out Html
# Run benchmarks
cargo bench
# Run specific test
cargo test test_name📊 Test Categories
| Category | Description | Files |
|---|---|---|
| Unit Tests | Core functionality tests | tests/unit_core.rs |
| Integration Tests | System integration tests | tests/integration_*.rs |
| Performance Tests | Benchmark tests | benches/performance.rs |
| DoS Protection | Security tests | tests/dos_protection_tests.rs |
| Memory Tests | Memory management tests | tests/test_memory_*.rs |
| Large File Tests | Stream handling tests | tests/large_file_transmission_tests.rs |
|
Message Processing |
Latency (Memory Channel) |
📈 Detailed Benchmarks
# Run benchmarks
cargo bench
# Available benchmarks:
# - bench_message_send: Message sending performance
# - bench_channel_router: Routing decision performance
# - bench_encryption: Encryption/decryption performance
# - bench_group_broadcast: Group broadcast performance
 End-to-End Encryption X25519 + ChaCha20Poly1305 |
 Group Forward Secrecy TreeKem key rotation |
 DoS Protection Rate limiting (100 msg/sec) |
 Message Signing Ed25519 signatures |
🔐 Security Details
| Operation | Algorithm | Purpose |
|---|---|---|
| Key Exchange | X25519 | Secure key agreement |
| Encryption | ChaCha20Poly1305 | Authenticated encryption |
| Signatures | Ed25519 | Message authentication |
| Key Derivation | HKDF-SHA256 | Key material derivation |
| Hashing | SHA-256 | Integrity verification |
- ✅ Rate Limiting - 100 messages/second per device
- ✅ Memory Safety - Zero-copy operations where possible
- ✅ Session Management - Automatic session cleanup on drop
- ✅ Device Migration - Encrypted state export/import
Please report security vulnerabilities to: security@example.com
gantt
title xlink Roadmap
dateFormat YYYY-MM
section Core Features
Multi-Channel Support :done, 2024-01, 2024-06
E2E Encryption :done, 2024-02, 2024-07
Group Messaging :active, 2024-05, 2024-10
section Advanced Features
Stream Management :active, 2024-06, 2024-11
Device Discovery :done, 2024-04, 2024-09
Performance Optimization :2024-10, 2025-02
section Platform Support
FFI Bindings :2024-08, 2025-01
Mobile Platform Support :2025-01, 2025-06
|
|
|
|
|
Found a bug? |
Have an idea? |
Want to contribute? |
📝 Contribution Guidelines
- Fork the repository
- Clone your fork:
git clone https://github.com/yourusername/xlink.git - Create a branch:
git checkout -b feature/amazing-feature - Make your changes
- Test your changes:
cargo test --all-features - Commit your changes:
git commit -m 'Add amazing feature' - Push to branch:
git push origin feature/amazing-feature - Create a Pull Request
- Follow Rust standard coding conventions (
cargo fmt) - Write comprehensive tests for new features
- Update documentation for API changes
- Add examples for new features
- Ensure all tests pass before submitting
This project is licensed under the MIT License.
 Rust |
 Tokio |
 GitHub |
 Crates.io |
-
🌟 Dependencies - Built on these amazing projects:
- tokio - Async runtime
- dashmap - Concurrent HashMap
- x25519-dalek - X25519 key exchange
- chacha20poly1305 - Authenticated encryption
- serde - Serialization framework
-
👥 Contributors - Thanks to all our amazing contributors!
-
💬 Community - Special thanks to our community members
 Issues Report bugs & issues |
 Discussions Ask questions & share ideas |
 GitHub View source code |
If you find this project useful, please consider giving it a ⭐️!
Built with ❤️ by Kirky.X Kirky-X@outlook.com
© 2024 xlink. All rights reserved.