MockForge Core

Core functionality and shared logic for the MockForge mocking framework.

This crate provides the foundational building blocks used across all MockForge protocols (HTTP, WebSocket, gRPC, GraphQL). It can be used as a library to programmatically create and manage mock servers, or to build custom mocking solutions.

Overview

MockForge Core includes:

• Routing & Validation: OpenAPI-based route registration and request validation
• Request/Response Processing: Template expansion, data generation, and transformation
• Chaos Engineering: Latency injection, failure simulation, and traffic shaping
• Proxy & Hybrid Mode: Forward requests to real backends with intelligent fallback
• Request Chaining: Multi-step request workflows with context passing
• Workspace Management: Organize and persist mock configurations
• Observability: Request logging, metrics collection, and tracing

Library feature selection

The minimal-build corrections described here are unreleased.

Default features include data generation, AI, contracts, workspace management, voice, advanced engines, and scripting. Embedded applications can disable the bundle and enable individual features:

mockforge-core = { version = "0.3.233", default-features = false, features = ["workspace-mgmt"] }

Shared configuration types remain available with default features disabled, so JSON and YAML configuration can be moved between builds. An engine's configuration does not enable its Cargo feature. Workspace persistence and synchronization require workspace-mgmt; continuum blending and behavioral economics require advanced, which enables workspace management for snapshots and multi-tenant routing. Voice workspace construction requires workspace management and data and enables those two prerequisites. The advanced consistency engine enables the intelligence crate's persona data types because its state contains PersonaProfile.

The targeted configuration and basic request controls can be run independently:

cargo test -p mockforge-core --no-default-features --test optional_feature_basics

Quick Start: Embedding MockForge

Creating a Simple HTTP Mock Server

use mockforge_core::{
    OpenApiSpec, OpenApiRouteRegistry, ValidationOptions,
    LatencyProfile, Config,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Load OpenAPI specification
    let spec = OpenApiSpec::from_file("api.json").await?;

    // Create route registry with validation
    let registry = OpenApiRouteRegistry::new(spec, ValidationOptions::default());

    // Configure core features
    let config = Config {
        latency_enabled: true,
        failures_enabled: false,
        default_latency: LatencyProfile::normal(),
        ..Default::default()
    };

    // Build your HTTP server with the registry
    // (See mockforge-http crate for router building)

    Ok(())
}

Request Chaining

Chain multiple requests together with shared context:

use mockforge_core::{ChainDefinition, ChainRequest, RequestChainRegistry};

# async fn example() -> Result<(), Box<dyn std::error::Error>> {
let mut registry = RequestChainRegistry::new();

// Define a chain: create user → add to group → verify membership
let chain = ChainDefinition {
    name: "user_onboarding".to_string(),
    steps: vec![
        ChainRequest {
            method: "POST".to_string(),
            path: "/users".to_string(),
            body: Some(r#"{"name": "{{faker.name}}"}"#.to_string()),
            extract: vec![("user_id".to_string(), "$.id".to_string())],
            ..Default::default()
        },
        ChainRequest {
            method: "POST".to_string(),
            path: "/groups/{{user_id}}/members".to_string(),
            ..Default::default()
        },
    ],
};

registry.register_chain("user_onboarding", chain)?;
# Ok(())
# }

Latency & Failure Injection

Simulate realistic network conditions and errors:

use mockforge_core::{LatencyProfile, FailureConfig, create_failure_injector};

// Configure latency simulation
let latency = LatencyProfile::slow(); // 300-800ms

// Configure failure injection
let failure_config = FailureConfig {
    global_error_rate: 0.05, // 5% of requests fail
    default_status_codes: vec![500, 502, 503],
    ..Default::default()
};

let injector = create_failure_injector(Some(failure_config));

Key Modules

OpenAPI Support

• [openapi]: Parse and work with OpenAPI specifications
• [openapi_routes]: Register routes from OpenAPI specs with validation
• [validation]: Request/response validation against schemas

Request Processing

• [routing]: Route matching and registration
• [templating]: Template variable expansion ({{uuid}}, {{now}}, etc.)
• [request_chaining]: Multi-step request workflows
• [overrides]: Dynamic request/response modifications

Chaos Engineering

• [latency]: Latency injection with configurable profiles
• [failure_injection]: Simulate service failures and errors
• [traffic_shaping]: Bandwidth limiting and packet loss

Proxy & Hybrid

• [proxy]: Forward requests to upstream services
• [ws_proxy]: WebSocket proxy with message transformation

Persistence & Import

• [workspace]: Workspace management for organizing mocks
• [workspace_import]: Import from Postman, Insomnia, cURL, HAR
• [record_replay]: Record real requests and replay as fixtures

Observability

• [request_logger]: Centralized request logging
• [performance]: Performance metrics and profiling

Feature Flags

This crate supports several optional features:

• openapi: OpenAPI specification support (enabled by default)
• validation: Request/response validation (enabled by default)
• templating: Template expansion (enabled by default)
• chaos: Chaos engineering features (enabled by default)
• proxy: Proxy and hybrid mode (enabled by default)
• workspace: Workspace management (enabled by default)

Examples

See the examples directory for complete working examples.

Related Crates

• mockforge-http: HTTP/REST mock server
• mockforge-grpc: gRPC mock server
• mockforge-ws: WebSocket mock server
• mockforge-graphql: GraphQL mock server
• mockforge-plugin-core: Plugin development
• mockforge-data: Synthetic data generation

Documentation

• MockForge Book
• API Reference
• GitHub Repository