feat: create fastn-context crate with hierarchical context system for debugging and operations

[amitu]

Summary

Complete implementation of fastn-context crate providing hierarchical context trees for debugging, cancellation, and operational visibility across the fastn ecosystem.

🎯 This is Our MVP - Complete Vision Coming Soon

This PR implements the foundational context system - the essential building blocks for comprehensive operational visibility. While fully functional and production-ready, this is just the beginning of our context vision.

Current Implementation (MVP)

• ✅ Hierarchical context trees with timing
• ✅ Tree-based cancellation with CancellationToken
• ✅ Live status display with ANSI formatting
• ✅ Basic distributed tracing with context persistence
• ✅ Three spawning patterns for different complexity needs

Upcoming Features (Full Vision)

• Operation tracking - "stuck on: await database-query" precision debugging
• Named locks - Deadlock detection with "who's waiting for what" visibility
• Global counters - "1,247 total connections, 47 active" with dotted path storage
• System metrics - CPU, RAM, network integrated into context trees
• P2P status distribution - fastn status remote-machine across network
• Advanced monitoring - Comprehensive dashboards and alerting

Complete Vision Teaser

Imagine this level of operational visibility:

$ fastn status alice --watch
System: CPU 12.3% | RAM 2.1GB/16GB | Network ↓125KB/s ↑67KB/s

✅ global (5d 12h, active) [1,247 total connections, 47 live]
├── Remote Access (1h 45m, active) [234 connections, 15 live]
│   ├── alice@bv478gen (23m, active) [45 commands, 1 live]
│   │   ├── stdout-handler (stuck on: "await stream-read" 12.3s) ⚠️
│   │   │   └── 🔒 HOLDS "session-output-lock" (12.3s held)
│   │   └── stderr-stream (stuck on: "await session-lock" 8.1s) ⚠️ DEADLOCK
│   │       └── ⏳ WAITING "session-output-lock" (8.1s waiting)
│   └── bob@p2nd7avq (8m, active) [12 commands, 1 live]
├── HTTP Server (5d 12h, active) [15,432 requests, 8 live]
│   └── connection-pool (45 connections, oldest 34m)
└── Chat Service (2h 15m, active) [4,567 messages, 3 conversations]

🔒 Active Locks: session-output-lock (held 12.3s) ⚠️ LONG HELD
⏳ Deadlock Risk: stderr-stream waiting for stdout-handler lock

Recent completed:
- alice.stream-455 (2.3s, success: 1.2MB processed)
- bob.command-ls (0.8s, success: file listing)
- http.request-789 (1.2s, failed: database timeout)

This complete vision provides unprecedented debugging precision - every operation visible, every bottleneck identified, every deadlock detected automatically.

🎉 Implementation Status: COMPLETE AND PRODUCTION READY

✅ All Core Features Working

Hierarchical Context Trees with Timing:

• Named contexts with parent/child relationships and creation timestamps
• Automatic tree building as operations spawn
• Duration tracking for all contexts (created_at → elapsed time)
• Recursive cancellation (cancel parent cancels all children)

Three Spawning Patterns:

ctx.spawn(task)                           // Inherit context (no child)
ctx.spawn_child("name", |ctx| task)       // Common case shortcut ⭐
ctx.child("name").spawn(|ctx| task)       // Builder pattern

Proper Async Cancellation (Key Fix):

// Works correctly in tokio::select! 
tokio::select! {
    _ = ctx.cancelled() => return,        // Clean cancellation
    connection = listener.accept() => {}  // Handle connection
    data = stream.read() => {}            // Handle data
}

Live Status Display with Timing:

let status = fastn_context::status();
println!("{}", status);

// Output:
// fastn Context Status
// ✅ global (2h 15m, active)
//   ✅ remote-access-listener (1h 45m, active)
//     ✅ alice@bv478gen (23m, active)

Distributed Tracing:

// P2P handler example
async fn handle_stream(ctx: Arc<Context>) {
    // Process stream...
    ctx.persist();  // Add to trace buffer when done
}

// Shows recent completions
let status = fastn_context::status_with_latest();
// Recent completed contexts:
// - stream-handler (2.3s, completed)
// - request-processor (0.8s, cancelled)

🤔 Relationship to fastn-observer

fastn-context and fastn-observer serve orthogonal but complementary purposes:

fastn-observer: Developer Performance Analysis

• Purpose: "Observe how fast your Rust program is"
• Audience: Developers optimizing code performance
• Focus: Historical performance metrics and Rust program speed
• Usage: Global performance tracking (fastn_observer::observe())

fastn-context: DevOps Operational Debugging

• Purpose: Live operational visibility and debugging
• Audience: DevOps/Operations monitoring running services
• Focus: Real-time operational state and task relationships
• Usage: Per-operation context trees with live status

They answer different questions:

• fastn-observer: "My app uses 15% CPU, 200MB RAM" (performance)
• fastn-context: "alice@bv478gen stuck on stdout-handler for 12 minutes" (operations)

🔮 Future Enhancements (NEXT-*.md)

Organized roadmap for complete operational visibility:

• NEXT-operation-tracking.md - Named await/select: "stuck on: await operation-name" precision
• NEXT-locks.md - Named locks with deadlock detection and timing analysis
• NEXT-counters.md - Global counters: "1,247 total connections, 47 live" with dotted paths
• NEXT-monitoring.md - System metrics integration (CPU, RAM, network) in context trees
• NEXT-metrics-and-data.md - Store arbitrary data and metrics on contexts
• NEXT-status-distribution.md - fastn status remote-machine across P2P network

Implementation approach: Each NEXT feature will be implemented as separate PR after core foundation proven in production.

🚀 Ready for Ecosystem Integration

This provides the operational backbone for all fastn services with immediate debugging value and a clear path to comprehensive monitoring capabilities.

🤖 Generated with Claude Code