feat: implement fastn-p2p streaming API foundation

[amitu]

🔗 Branch Context

⚠️ This PR is against feature branch feat/fastn-p2p-streaming-api, not main
📋 Feature tracking PR: #2210

This is a sub-PR that implements the foundational streaming API as part of the larger fastn-p2p feature development tracked in PR #2210.

---

Summary

API Stubs Only - This PR provides the type definitions and function signatures for fastn-p2p streaming API, but all functions are currently todo!() stubs that need actual implementation.

🚧 Current Implementation Status

✅ What's Done (API Structure)

• Type definitions for client::Session and server::Session
• Function signatures for streaming operations
• Workspace dependency setup for fastn-context
• Build success (compiles without errors)

🚨 What's NOT Done (7 TODOs)

// All of these are todo!() stubs:
client::connect()           // todo!("Connect to {target}...")
Session::accept_uni()       // todo!("Accept unidirectional stream...")
Session::accept_bi()        // todo!("Accept bidirectional stream...")
Session::into_request()     // todo!("Convert Session to Request...")
Session::open_uni()         // todo!("Open unidirectional stream...")
Session::open_bi()          // todo!("Open bidirectional stream...")
// Plus context integration is commented out

🎯 Next Steps (Phase 2a)

Before this can be used, we need to implement:

1. Core Connection - Make client::connect() actually establish iroh connections
2. Session Management - Real stream creation and lifecycle
3. Context Integration - Uncomment and wire up fastn-context
4. RPC Conversion - Implement Session::into_request()

🔧 API Design

The API structure is defined but not implemented:

Client Side (TODOs)

// Currently: todo!() 
let session = fastn_p2p::client::connect(our_key, target, protocol).await?;
session.stdin   // Defined but not working
session.stdout  // Defined but not working

Server Side (TODOs)

// Currently: todo!()
fn handle_session(session: fastn_p2p::server::Session<Protocol>) {
    let ctx = session.context(); // Structure exists but context is dummy
    let request = session.into_request(); // todo!()
}

📊 Changes

• 7 files changed: +178 insertions, -54 deletions
• New: Type definitions and signatures
• Working: Build system and dependencies
• Not Working: Any actual functionality (all TODOs)

⚠️ Important

This PR is just the foundation - it provides the API shape but no functionality. Everything panics with todo!() if called.

Status: Ready for implementation work in follow-up commits/PRs.

🤖 Generated with Claude Code

[amitu]

🚀 New Development Approach: API-First with Binary Prototypes

We're shifting our development strategy for fastn-p2p from traditional "implement then test" to "prototype with binaries, then implement".

🎯 The Strategy

Instead of implementing the TODOs in the fastn-p2p crate directly, we're:

1. Building comprehensive binaries (src/bin/) that use the entire public API surface of fastn-p2p
2. Proving our API design through real-world usage patterns before implementation
3. Fast iteration on API ergonomics while the underlying functions are still todo!()
4. High confidence - when we implement the real functionality, we know it works for multiple use cases

🛠️ Current Binary Prototypes

remote_access_daemon.rs - P2P Remote Shell Server

• Tests: server::listen(), Session<Protocol>, context integration
• Proves: Server-side streaming API, security model, session management
• Next: Protocol negotiation, command execution streaming

rshell.rs - P2P Remote Shell Client

• Tests: client::connect(), Session streaming, error handling
• Proves: Client-side API ergonomics, connection establishment, command streaming
• Next: Real iroh connection, stdin/stdout/stderr multiplexing

🔮 Future Binary Prototypes (Planned)

• HTTP/TCP Proxy: Test bidirectional streaming, connection bridging
• Audio/Video Streaming: Test high-throughput, low-latency use cases
• File Transfer: Test large data streaming, progress tracking
• Chat/Messaging: Test real-time communication patterns

🎪 Benefits of This Approach

1. API Validation: Real usage patterns expose API issues early
2. Fast Iteration: Change APIs without implementing internals
3. Multiple Use Cases: Single crate supports diverse applications
4. High Confidence: Implementation guided by proven usage patterns
5. Documentation: Binaries serve as comprehensive examples

📊 Development Phases

• Phase 1 ✅: API structure definition (current PR)
• Phase 2 🚧: Binary prototypes with TODO stubs (in progress)
• Phase 3 🔄: API refinement based on prototype learnings
• Phase 4 🚀: Actual implementation guided by proven APIs
• Phase 5 ✅: End-to-end testing with real binaries

This approach ensures our fastn-p2p APIs are battle-tested before implementation, leading to better design and higher confidence in the final product.

🤖 Generated with Claude Code