Crate mockforge_grpc

Expand description

§MockForge gRPC

Flexible gRPC mocking library with dynamic service discovery and HTTP bridge.

This crate provides comprehensive gRPC mocking capabilities with:

Dynamic Service Discovery: Auto-discover and mock services from .proto files
HTTP Bridge: Expose gRPC services as REST APIs with OpenAPI documentation
gRPC Reflection: Built-in server reflection for service discovery
Streaming Support: Full support for unary, server, client, and bidirectional streaming
Protocol Buffer Parsing: Runtime parsing of .proto files without code generation

§Overview

MockForge gRPC eliminates the need to hardcode service implementations. Simply provide .proto files, and MockForge will automatically:

Parse protobuf definitions
Generate mock service implementations
Handle all RPC methods (unary and streaming)
Optionally expose as REST APIs via HTTP Bridge

§Quick Start

§Basic gRPC Server

use mockforge_grpc::start;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    // Start gRPC server on port 50051
    // Automatically discovers .proto files in ./proto directory
    start(50051).await?;
    Ok(())
}

§With Custom Configuration

use mockforge_grpc::{start_with_config, DynamicGrpcConfig};
use mockforge_grpc::dynamic::http_bridge::HttpBridgeConfig;
use mockforge_core::LatencyProfile;

let config = DynamicGrpcConfig {
    proto_dir: "./my-protos".to_string(),
    enable_reflection: true,
    excluded_services: vec!["ExperimentalService".to_string()],
    http_bridge: Some(HttpBridgeConfig {
        enabled: true,
        base_path: "/api".to_string(),
        ..Default::default()
    }),
    ..Default::default()
};

let latency = Some(LatencyProfile::with_normal_distribution(120, 35.0));
start_with_config(50051, latency, config).await?;

§HTTP Bridge Mode

Expose gRPC services as REST APIs:

use mockforge_grpc::{start_with_config, DynamicGrpcConfig};
use mockforge_grpc::dynamic::http_bridge::HttpBridgeConfig;

let config = DynamicGrpcConfig {
    proto_dir: "./proto".to_string(),
    http_bridge: Some(HttpBridgeConfig {
        enabled: true,
        base_path: "/api".to_string(),
        ..Default::default()
    }),
    ..Default::default()
};

start_with_config(50051, None, config).await?;
// Now accessible via:
// - gRPC: localhost:50051
// - REST: http://localhost:8080/api/{service}/{method}
// - OpenAPI: http://localhost:8080/api/docs

§TLS/mTLS Configuration

Enable TLS encryption for secure gRPC connections:

use mockforge_grpc::{start_with_config, DynamicGrpcConfig, GrpcTlsConfig};

// Basic TLS
let config = DynamicGrpcConfig {
    proto_dir: "./proto".to_string(),
    tls: Some(GrpcTlsConfig::new("server.crt", "server.key")),
    ..Default::default()
};

// Or with mutual TLS (client certificate verification)
let mtls_config = DynamicGrpcConfig {
    proto_dir: "./proto".to_string(),
    tls: Some(GrpcTlsConfig::with_mtls("server.crt", "server.key", "client-ca.crt")),
    ..Default::default()
};

start_with_config(50051, None, config).await?;

TLS can also be configured via environment variables:

GRPC_TLS_CERT: Path to server certificate (PEM format)
GRPC_TLS_KEY: Path to server private key (PEM format)
GRPC_TLS_CLIENT_CA: Optional path to client CA for mTLS

§Dynamic Service Discovery

MockForge automatically discovers and mocks all services defined in your .proto files:

// user.proto
service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
  rpc ListUsers(ListUsersRequest) returns (stream User);
  rpc CreateUser(stream CreateUserRequest) returns (CreateUserResponse);
  rpc Chat(stream ChatMessage) returns (stream ChatMessage);
}

All four method types (unary, server streaming, client streaming, bidirectional) are automatically supported without any code generation or manual implementation.

§gRPC Reflection

Enable reflection for service discovery by gRPC clients:

# List services
grpcurl -plaintext localhost:50051 list

# Describe a service
grpcurl -plaintext localhost:50051 describe UserService

# Call a method
grpcurl -plaintext -d '{"user_id": "123"}' localhost:50051 UserService/GetUser

§HTTP Bridge

The HTTP Bridge automatically converts gRPC services to REST endpoints:

# gRPC call
grpcurl -d '{"user_id": "123"}' localhost:50051 UserService/GetUser

# Equivalent HTTP call
curl -X POST http://localhost:8080/api/userservice/getuser \
  -H "Content-Type: application/json" \
  -d '{"user_id": "123"}'

# OpenAPI documentation
curl http://localhost:8080/api/docs

§Advanced Data Synthesis

Generate realistic mock data using intelligent field inference:

Detects field types from names (email, phone, id, etc.)
Maintains referential integrity across related messages
Supports deterministic seeding for reproducible tests

§Key Modules

dynamic: Dynamic service discovery and mocking
reflection: gRPC reflection protocol implementation
registry: Service and method registry

§Examples

See the examples directory for complete working examples.

mockforge-core: Core mocking functionality
mockforge-data: Synthetic data generation

§Documentation

Re-exports§

pub use dynamic::proto_parser::ProtoService;
pub use dynamic::service_generator::MockResponse;
pub use dynamic::DynamicGrpcConfig;
pub use dynamic::GrpcTlsConfig;
pub use dynamic::ServiceRegistry;
pub use reflection::MockReflectionProxy;
pub use reflection::ProxyConfig;
pub use reflection::ReflectionProxy;
pub use registry::GrpcProtoRegistry;

Modules§

dynamic: Dynamic gRPC service discovery and registration
generated: Generated Protocol Buffer code from .proto files
reflection: Reflection-based gRPC proxy implementation
registry: gRPC Proto Registry - SpecRegistry implementation for gRPC

Functions§

start: Start gRPC server with default configuration
start_with_config: Start gRPC server with custom configuration
start_with_latency: Start gRPC server with latency configuration