feat: Add first-class middleware integration to Client/Protocol/Transport

[guyernest]

Summary

The middleware system (Middleware, AdvancedMiddleware, MiddlewareChain, EnhancedMiddlewareChain) is comprehensive and powerful, but there's no standard integration path to attach middleware to Client, Protocol, or Transport. Users must manually invoke middleware chains, which is error-prone and defeats the purpose of having middleware infrastructure.

Current State

What exists:

• ✅ Comprehensive middleware traits (Middleware, AdvancedMiddleware)
• ✅ Chain implementations (MiddlewareChain, EnhancedMiddlewareChain)
• ✅ Built-in middleware (Logging, Auth, Retry, RateLimit, CircuitBreaker, Metrics, Compression)
• ✅ Priority ordering, context propagation, conditional execution
• ✅ Excellent documentation in pmcp-book/src/ch11-middleware.md

What's missing:

• ❌ No ClientBuilder::with_middleware_chain(...) or similar API
• ❌ No automatic middleware invocation on requests/responses
• ❌ No integration examples showing middleware running on real client operations
• ❌ Users must manually call chain.process_request() / chain.process_response()

Current workaround (manual integration):

// Manual middleware invocation - cumbersome and easy to forget
let mut client = Client::new(transport);
let mut middleware_chain = MiddlewareChain::new();
middleware_chain.add(Arc::new(LoggingMiddleware::default()));

// Must manually intercept before/after every operation
let mut request = create_request("tools/list", None);
middleware_chain.process_request(&mut request).await?;
let response = client.call_method(request).await?;
middleware_chain.process_response(&mut response).await?;

Proposed Solution

Add first-class middleware integration at one or more levels:

Option 1: Client-level Integration (Recommended)

use pmcp::{Client, ClientCapabilities, MiddlewareChain, LoggingMiddleware};
use std::sync::Arc;
use tracing::Level;

let mut chain = MiddlewareChain::new();
chain.add(Arc::new(LoggingMiddleware::new(Level::INFO)));

let client = Client::builder()
    .capabilities(ClientCapabilities::default())
    .with_middleware_chain(chain)  // ← NEW API
    .streamable_http_transport("http://localhost:8080")
    .await?
    .build()
    .await?;

// Middleware runs automatically on all operations
let tools = client.list_tools(None).await?;  // Logging middleware runs transparently

Option 2: Transport-level Integration

use pmcp::{StdioTransport, LoggingMiddleware};

let transport = StdioTransport::new()
    .with_middleware(Arc::new(LoggingMiddleware::default()));  // ← NEW API

let client = Client::new(transport);
// Middleware intercepts all transport send/receive operations

Option 3: Protocol-level Integration

use pmcp::shared::{Protocol, ProtocolOptions};

let protocol = Protocol::new(ProtocolOptions {
    middleware: Some(chain),  // ← NEW FIELD
    ..Default::default()
});

Implementation Approach

Client-level (Recommended Starting Point)

1. Update Client struct:

pub struct Client {
    transport: Box<dyn Transport>,
    middleware: Option<Arc<MiddlewareChain>>,  // NEW
    // ... existing fields
}

2. Add builder method:

impl ClientBuilder {
    pub fn with_middleware_chain(mut self, chain: MiddlewareChain) -> Self {
        self.middleware = Some(Arc::new(chain));
        self
    }
}

3. Intercept in request/response methods:

impl Client {
    pub async fn call_method(&mut self, mut request: JSONRPCRequest) -> Result<JSONRPCResponse> {
        // Apply middleware to request
        if let Some(ref middleware) = self.middleware {
            middleware.process_request(&mut request).await?;
        }

        // Send request
        let response = /* ... existing logic ... */;

        // Apply middleware to response
        if let Some(ref middleware) = self.middleware {
            middleware.process_response(&mut response).await?;
        }

        Ok(response)
    }
}

Enhanced Middleware Support

For EnhancedMiddlewareChain with context:

pub fn with_enhanced_middleware_chain(mut self, chain: EnhancedMiddlewareChain) -> Self {
    self.enhanced_middleware = Some(Arc::new(chain));
    self
}

// In request handling:
let context = MiddlewareContext::with_request_id(generate_request_id());
middleware.process_request_with_context(&mut request, &context).await?;

Comparison with TypeScript SDK

TypeScript SDK (~/Development/mcp/sdk/typescript-sdk):

• HTTP-only: fetch wrapper middleware
• Limited scope: Only HTTP transport layer

Rust SDK (current + proposed):

• ✅ Protocol-first: Hooks at JSON-RPC level AND raw transport messages
• ✅ Transport-agnostic: Works with stdio, WebSocket, HTTP, Streamable HTTP
• ✅ Advanced patterns: Rate limiting, circuit breakers, metrics, compression
• ✅ Priority ordering and conditional execution
• ⚠️ Missing: First-class integration (this issue)

With this enhancement, Rust SDK would be superior in every aspect.

Benefits

1. Zero-boilerplate usage: Set up once, runs automatically
2. Reduced error surface: Can't forget to apply middleware
3. Clear integration point: Obvious where/how to attach middleware
4. Matches user expectations: Standard pattern from other middleware systems
5. Makes powerful middleware system usable: Current system is powerful but disconnected

Example Use Case

Production deployment with observability:

use pmcp::shared::{
    EnhancedMiddlewareChain,
    MetricsMiddleware,
    LoggingMiddleware,
    RateLimitMiddleware,
    CircuitBreakerMiddleware,
};

let mut chain = EnhancedMiddlewareChain::new();
chain.add(Arc::new(MetricsMiddleware::new("my-service".to_string())));
chain.add(Arc::new(LoggingMiddleware::new(Level::INFO)));
chain.add(Arc::new(RateLimitMiddleware::new(100, 200, Duration::from_secs(1))));
chain.add(Arc::new(CircuitBreakerMiddleware::new(5, Duration::from_secs(60), Duration::from_secs(30))));

// One-line integration
let client = Client::builder()
    .with_enhanced_middleware_chain(chain)
    .streamable_http_transport("http://localhost:8080")
    .await?
    .build()
    .await?;

// All operations now have:
// - Automatic metrics collection
// - Request/response logging
// - Rate limiting protection
// - Circuit breaker fault tolerance
let tools = client.list_tools(None).await?;

Proposed Implementation Plan

1. Phase 1: Client-level integration (highest impact, easiest to implement)

   • Add with_middleware_chain() to ClientBuilder
   • Add with_enhanced_middleware_chain() to ClientBuilder
   • Intercept in Client::call_method() and similar methods
   • Update examples/15_middleware.rs with real integration

2. Phase 2: Transport-level integration (for advanced use cases)

   • Add with_middleware() to transport implementations
   • Intercept Transport::send() / Transport::receive()

3. Phase 3: Protocol-level integration (if needed)

   • Add middleware field to ProtocolOptions
   • Intercept in Protocol request handling

4. Documentation updates:

   • Update pmcp-book/src/ch11-middleware.md with integration examples
   • Add "Real-World Integration" section
   • Update examples/15_middleware.rs and examples/30_enhanced_middleware.rs

Files to Modify

• src/client/mod.rs or src/client/builder.rs - Add builder methods
• src/client/client.rs - Add middleware interception
• src/shared/protocol.rs - Optional: Protocol-level integration
• src/shared/transport.rs - Optional: Transport trait extension
• examples/15_middleware.rs - Update with real integration
• examples/30_enhanced_middleware.rs - Update with real integration
• pmcp-book/src/ch11-middleware.md - Add integration documentation

Breaking Changes

None - This is purely additive. All existing code continues to work, and middleware remains optional.

References

• Current middleware implementation: src/shared/middleware.rs
• Middleware documentation: pmcp-book/src/ch11-middleware.md
• Basic middleware example: examples/15_middleware.rs
• Enhanced middleware example: examples/30_enhanced_middleware.rs
• TypeScript SDK comparison: ~/Development/mcp/sdk/typescript-sdk

---

Priority: High
Complexity: Medium
Impact: High - Makes middleware system actually usable in production

This enhancement would complete the middleware story and make PMCP's middleware system best-in-class across all MCP SDKs.

[guyernest]

Significant progress has been made on this issue! The HTTP transport layer now has full first-class middleware integration.

✅ What's Been Completed

HTTP-Level Middleware Integration (COMPLETE)

✅ Transport-level configuration:

use pmcp::client::http_middleware::HttpMiddlewareChain;
use pmcp::shared::streamable_http::{StreamableHttpTransport, StreamableHttpTransportConfig};

let mut http_chain = HttpMiddlewareChain::new();
http_chain.add(Arc::new(LoggingMiddleware::default()));
http_chain.add(Arc::new(OAuthClientMiddleware::new(token)));

let config = StreamableHttpTransportConfig {
    url: Url::parse("http://localhost:8080").unwrap(),
    http_middleware_chain: Some(Arc::new(http_chain)),  // ← First-class integration\!
    // ...
};

let transport = StreamableHttpTransport::new(config);
let mut client = ClientBuilder::new(transport).build();

// Middleware runs automatically on ALL operations - zero manual calls\!
let tools = client.list_tools(None).await?;  // Middleware runs transparently

✅ Automatic invocation - No manual chain.process_request() calls needed:

• build_request_with_middleware() - Called automatically before HTTP send
• apply_response_middleware() - Called automatically after HTTP receive
• Short-circuit error handling with on_error hooks
• Priority-based execution ordering

✅ Clean architecture:

• Configuration via StreamableHttpTransportConfig::http_middleware_chain
• Middleware chain is Option<Arc<HttpMiddlewareChain>> - zero overhead when unused
• Fast path optimization when no middleware configured

✅ Production-ready features:

• Error handling with on_error lifecycle
• Context metadata for middleware coordination
• Priority-based ordering (lower runs first)
• Conditional execution via should_execute()

Test Coverage

✅ 23 integration tests demonstrating automatic middleware invocation:

• Real client-server interactions
• Multiple middleware chaining
• Error scenarios
• Retry coordination

Documentation

✅ Chapter 11: Middleware - Complete HTTP middleware section
✅ Chapter 10.3: Streamable HTTP - Integration guide
✅ examples/40_middleware_demo.rs - Full demonstration

⚠️ What's Still Pending

1. ClientBuilder API (HIGH PRIORITY)

Desired API:

let client = Client::builder()
    .capabilities(ClientCapabilities::default())
    .with_middleware_chain(chain)  // ← Doesn't exist yet
    .streamable_http_transport("http://localhost:8080")
    .await?
    .build()
    .await?;

Current workaround: Configure via transport config (works but less ergonomic)

Implementation needed:

• Add middleware_chain: Option<Arc<MiddlewareChain>> field to ClientBuilder
• Add .with_middleware_chain() builder method
• Pass middleware to transport during client construction
• Update all transport builders to accept middleware

2. Protocol-Level Middleware Auto-Invocation (MEDIUM PRIORITY)

Current state: Protocol middleware (AdvancedMiddleware) requires manual calls:

// Manual invocation required
let mut request = create_request("tools/list", None);
middleware_chain.process_request(&mut request).await?;
let response = client.call_method(request).await?;
middleware_chain.process_response(&mut response).await?;

Desired state: Automatic invocation like HTTP middleware

Implementation needed:

• Add middleware chain to Protocol struct
• Wrap all request/response paths with automatic middleware invocation
• Ensure backward compatibility

3. Unified Middleware Configuration (LOW PRIORITY)

Desired: Single configuration point for both HTTP and Protocol middleware

let client = Client::builder()
    .with_http_middleware(http_chain)      // HTTP layer
    .with_protocol_middleware(proto_chain) // Protocol layer
    .build();

Benefit: Clear separation of concerns, easier to understand

Progress Summary

Component	Status	Notes
HTTP middleware integration	✅ COMPLETE	Full automatic invocation
HTTP middleware config API	✅ COMPLETE	Via transport config
HTTP middleware tests	✅ COMPLETE	23 integration tests
HTTP middleware docs	✅ COMPLETE	Chapter 11 + examples
ClientBuilder API	❌ TODO	No .with_middleware_chain()
Protocol middleware auto-invoke	❌ TODO	Still requires manual calls
Unified middleware config	❌ TODO	Separate HTTP/Protocol APIs

What Works Today

Users can immediately use HTTP middleware with this pattern:

use pmcp::client::http_middleware::HttpMiddlewareChain;
use pmcp::client::oauth_middleware::{OAuthClientMiddleware, BearerToken};
use pmcp::shared::streamable_http::{StreamableHttpTransport, StreamableHttpTransportConfig};
use std::sync::Arc;

let mut http_chain = HttpMiddlewareChain::new();
http_chain.add(Arc::new(OAuthClientMiddleware::new(token)));

let config = StreamableHttpTransportConfig {
    url: Url::parse("http://localhost:8080")?,
    http_middleware_chain: Some(Arc::new(http_chain)),
    // ... other config
};

let transport = StreamableHttpTransport::new(config);
let mut client = ClientBuilder::new(transport).build();

// All HTTP operations now have middleware applied automatically\!
client.initialize(ClientCapabilities::minimal()).await?;
client.list_tools(None).await?;

This provides immediate value while we continue improving the ergonomics.

Files Changed (HTTP Layer)

• src/client/http_middleware.rs (356 lines)
• src/shared/streamable_http.rs (integration code)
• tests/http_middleware_integration.rs (764 lines)
• tests/sse_middleware_integration.rs (421 lines)
• tests/streamable_http_oauth_integration.rs (361 lines)

Next Steps

1. Add ClientBuilder::with_middleware_chain() - Improves ergonomics
2. Add Protocol middleware auto-invocation - Parity with HTTP layer
3. Update documentation - Show both patterns

Related Issues

• ✅ feat: Add HttpMiddleware trait for transport-level HTTP concerns #82 - HttpMiddleware trait (RESOLVED)
• ✅ feat: Add OAuth client-side middleware with token injection and auto-refresh #83 - OAuth client middleware (RESOLVED)
• ⚠️ feat: Add first-class middleware integration to Client/Protocol/Transport #80 - This issue (IN PROGRESS - HTTP complete, Client/Protocol pending)

---

The HTTP middleware integration is production-ready and provides immediate value. The remaining work (ClientBuilder API, Protocol auto-invocation) will further improve ergonomics. 🚀