Expand description
§pforge-runtime
Core runtime library for pforge - a zero-boilerplate MCP server framework.
This crate provides the execution engine for MCP servers defined via YAML configuration, including handler registration, dispatch, middleware, state management, and fault tolerance.
§Quick Start
use pforge_runtime::{Handler, HandlerRegistry, Result};
use serde::{Deserialize, Serialize};
use schemars::JsonSchema;
// Define input/output types
#[derive(Debug, Deserialize, JsonSchema)]
struct GreetInput {
name: String,
}
#[derive(Debug, Serialize, JsonSchema)]
struct GreetOutput {
message: String,
}
// Implement handler
struct GreetHandler;
#[async_trait::async_trait]
impl Handler for GreetHandler {
type Input = GreetInput;
type Output = GreetOutput;
type Error = pforge_runtime::Error;
async fn handle(&self, input: Self::Input) -> Result<Self::Output> {
Ok(GreetOutput {
message: format!("Hello, {}!", input.name),
})
}
}
// Register and dispatch
let mut registry = HandlerRegistry::new();
registry.register("greet", GreetHandler);
let input = serde_json::json!({"name": "World"});
let input_bytes = serde_json::to_vec(&input)?;
let output_bytes = registry.dispatch("greet", &input_bytes).await?;
let output: serde_json::Value = serde_json::from_slice(&output_bytes)?;
assert_eq!(output["message"], "Hello, World!");§Features
- Zero-overhead dispatch: O(1) average-case handler lookup with FxHash
- Type safety: Full compile-time type checking with Serde + JsonSchema
- Async-first: Built on tokio for high-performance async execution
- Fault tolerance: Circuit breaker, retry with exponential backoff, timeouts
- State management: In-memory backend (trueno-db KV persistence coming in Phase 6)
- Middleware: Composable request/response processing chain
- MCP protocol: Full support for resources, prompts, and tools
Re-exports§
pub use error::Error;pub use error::Result;pub use handler::Handler;pub use handlers::CliHandler;pub use handlers::HttpHandler;pub use handlers::PipelineHandler;pub use middleware::LoggingMiddleware;pub use middleware::Middleware;pub use middleware::MiddlewareChain;pub use middleware::ValidationMiddleware;pub use prompt::PromptManager;pub use prompt::PromptMetadata;pub use recovery::CircuitBreaker;pub use recovery::CircuitBreakerConfig;pub use recovery::CircuitState;pub use recovery::ErrorTracker;pub use recovery::FallbackHandler;pub use recovery::RecoveryMiddleware;pub use registry::HandlerRegistry;pub use resource::ResourceHandler;pub use resource::ResourceManager;pub use server::McpServer;pub use state::MemoryStateManager;pub use state::StateManager;pub use telemetry::ComponentHealth;pub use telemetry::HealthCheck;pub use telemetry::HealthStatus;pub use telemetry::MetricsCollector;pub use telemetry::TelemetryMiddleware;pub use timeout::retry_with_policy;pub use timeout::with_timeout;pub use timeout::RetryMiddleware;pub use timeout::RetryPolicy;pub use timeout::TimeoutMiddleware;