feat(p2p): add MeshNode integrating all production modules
New mesh_node.rs providing a production-ready node: - MeshNodeBuilder for fluent configuration - MeshConfig integration for all settings - MeshMetrics tracking for all operations - Rate limiting on incoming messages - Backpressure controller - Graceful shutdown via ShutdownCoordinator - Optional FappRouter based on capabilities - MeshRouter for envelope routing - TransportManager for multi-transport support Key APIs: - MeshNodeBuilder::new().fapp_relay().build() - node.process_incoming() with rate limiting + metrics - node.gc() for store/routing table cleanup - node.shutdown() for graceful termination 222 tests passing (203 lib + 3 fapp_flow + 16 multi_node)
This commit is contained in:
220
crates/meshservice/README.md
Normal file
220
crates/meshservice/README.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# MeshService
|
||||
|
||||
A generic decentralized service layer for mesh networks. Build any peer-to-peer service following the **Announce → Query → Response → Reserve** pattern.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Application Services │
|
||||
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
|
||||
│ │ FAPP │ │ Housing │ │ Repair │ │ Custom │ ... │
|
||||
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
|
||||
│ └────────────┴────────────┴────────────┘ │
|
||||
│ Service Layer (this crate) │
|
||||
│ ServiceMessage, ServiceRouter, Verification │
|
||||
│ ─────────────────────────────────────────────────────── │
|
||||
│ Mesh Layer │
|
||||
│ (provided by quicprochat-p2p or other mesh impl) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Features
|
||||
|
||||
- **Generic Protocol**: Any service can be built on top (therapy appointments, housing, repairs, tutoring...)
|
||||
- **Ed25519 Signatures**: All messages cryptographically signed
|
||||
- **Verification Framework**: Multi-level trust (self-asserted, peer-endorsed, registry-verified)
|
||||
- **Efficient Wire Format**: Fixed 64-byte header + CBOR payload
|
||||
- **Pluggable Handlers**: Register custom services with the router
|
||||
- **Built-in Services**: FAPP (psychotherapy) and Housing included
|
||||
|
||||
## Quick Start
|
||||
|
||||
```rust
|
||||
use meshservice::{
|
||||
capabilities,
|
||||
identity::ServiceIdentity,
|
||||
router::ServiceRouter,
|
||||
services::fapp::{FappService, SlotAnnounce, SlotQuery, Specialism, Modality},
|
||||
};
|
||||
|
||||
// Create identity
|
||||
let identity = ServiceIdentity::generate();
|
||||
|
||||
// Create router with FAPP service
|
||||
let mut router = ServiceRouter::new(capabilities::RELAY);
|
||||
router.register(Box::new(FappService::relay()));
|
||||
|
||||
// Therapist announces slots
|
||||
let announce = SlotAnnounce::new(
|
||||
&[Specialism::CognitiveBehavioral],
|
||||
Modality::VideoCall,
|
||||
"104", // Postal prefix
|
||||
)
|
||||
.with_slots(3)
|
||||
.with_profile("https://therapists.de/dr-mueller");
|
||||
|
||||
let msg = meshservice::services::fapp::create_announce(&identity, &announce, 1)?;
|
||||
router.handle(msg, Some(identity.public_key()))?;
|
||||
|
||||
// Patient queries
|
||||
let query = SlotQuery::new(Specialism::CognitiveBehavioral, "104");
|
||||
let query_msg = meshservice::services::fapp::create_query(&identity, &query)?;
|
||||
let matches = router.query(&query_msg);
|
||||
|
||||
println!("Found {} therapists", matches.len());
|
||||
```
|
||||
|
||||
## Built-in Services
|
||||
|
||||
### FAPP (Free Appointment Propagation Protocol)
|
||||
|
||||
Decentralized psychotherapy appointment discovery:
|
||||
|
||||
| Service ID | Purpose |
|
||||
|------------|---------|
|
||||
| `0x0001` | Therapist slot announcements, patient queries |
|
||||
|
||||
```rust
|
||||
use meshservice::services::fapp::{SlotAnnounce, Specialism, Modality};
|
||||
|
||||
let announce = SlotAnnounce::new(
|
||||
&[Specialism::TraumaFocused, Specialism::CognitiveBehavioral],
|
||||
Modality::InPerson,
|
||||
"104",
|
||||
)
|
||||
.with_slots(2)
|
||||
.with_profile("https://kbv.de/123");
|
||||
```
|
||||
|
||||
### Housing
|
||||
|
||||
Decentralized room/apartment sharing:
|
||||
|
||||
| Service ID | Purpose |
|
||||
|------------|---------|
|
||||
| `0x0002` | Listing announcements, seeker queries |
|
||||
|
||||
```rust
|
||||
use meshservice::services::housing::{ListingAnnounce, ListingType, amenities};
|
||||
|
||||
let listing = ListingAnnounce::new(ListingType::Apartment, 65, 850, "104")
|
||||
.with_rooms(2)
|
||||
.with_amenities(amenities::FURNISHED | amenities::BALCONY);
|
||||
```
|
||||
|
||||
## Verification Framework
|
||||
|
||||
Three trust levels:
|
||||
|
||||
| Level | Description | Example |
|
||||
|-------|-------------|---------|
|
||||
| 0 - None | Bare announcement | Anonymous |
|
||||
| 1 - Self-Asserted | Profile URL provided | Website link |
|
||||
| 2 - Peer-Endorsed | Trusted peers vouch | Community rating |
|
||||
| 3 - Registry-Verified | Official registry | KBV license |
|
||||
|
||||
```rust
|
||||
use meshservice::verification::{Verification, TrustedVerifiers, VerificationLevel};
|
||||
|
||||
// Add trusted verifier
|
||||
let mut verifiers = TrustedVerifiers::new();
|
||||
verifiers.add(registry_public_key, "KBV Registry", VerificationLevel::RegistryVerified);
|
||||
router.set_trusted_verifiers(verifiers);
|
||||
|
||||
// Require verification for announces
|
||||
router.set_min_verification_level(2);
|
||||
```
|
||||
|
||||
## Wire Protocol
|
||||
|
||||
64-byte fixed header for efficient parsing:
|
||||
|
||||
```
|
||||
0-3 service_id (u32 LE)
|
||||
4 message_type (u8)
|
||||
5 version (u8)
|
||||
6-7 flags (reserved)
|
||||
8-23 message_id (16 bytes)
|
||||
24-39 sender_address (16 bytes)
|
||||
40-47 sequence (u64 LE)
|
||||
48-49 ttl_hours (u16 LE)
|
||||
50-57 timestamp (u64 LE)
|
||||
58 hop_count (u8)
|
||||
59 max_hops (u8)
|
||||
60-63 payload_len (u32 LE)
|
||||
---
|
||||
64+ signature (64 bytes)
|
||||
128+ payload (CBOR)
|
||||
... verifications (optional CBOR)
|
||||
```
|
||||
|
||||
## Building Custom Services
|
||||
|
||||
Implement `ServiceHandler`:
|
||||
|
||||
```rust
|
||||
use meshservice::router::{ServiceHandler, ServiceAction, HandlerContext};
|
||||
|
||||
struct MyService;
|
||||
|
||||
impl ServiceHandler for MyService {
|
||||
fn service_id(&self) -> u32 { 0x8001 } // Custom range
|
||||
fn name(&self) -> &str { "MyService" }
|
||||
|
||||
fn handle(&self, message: &ServiceMessage, ctx: &HandlerContext)
|
||||
-> Result<ServiceAction, ServiceError>
|
||||
{
|
||||
match message.message_type {
|
||||
MessageType::Announce => Ok(ServiceAction::StoreAndForward),
|
||||
MessageType::Query => {
|
||||
// Find matches, respond...
|
||||
Ok(ServiceAction::Handled)
|
||||
}
|
||||
_ => Ok(ServiceAction::Drop)
|
||||
}
|
||||
}
|
||||
|
||||
fn matches_query(&self, announce: &StoredMessage, query: &ServiceMessage) -> bool {
|
||||
// Custom matching logic
|
||||
true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Service IDs
|
||||
|
||||
| ID | Service |
|
||||
|----|---------|
|
||||
| `0x0001` | FAPP (Psychotherapy) |
|
||||
| `0x0002` | Housing |
|
||||
| `0x0003` | Repair |
|
||||
| `0x0004` | Tutoring |
|
||||
| `0x0005` | Medical |
|
||||
| `0x0006` | Legal |
|
||||
| `0x0007` | Volunteer |
|
||||
| `0x0008` | Events |
|
||||
| `0x8000+` | Custom/User-defined |
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
# FAPP demo (therapist + patient)
|
||||
cargo run --example fapp_service
|
||||
|
||||
# Housing demo (landlord + seeker)
|
||||
cargo run --example housing_service
|
||||
|
||||
# Multi-service mesh
|
||||
cargo run --example multi_service
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
cargo test
|
||||
```
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
Reference in New Issue
Block a user