Crate mockforge_core 

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

Quick Start: Embedding MockForge

Creating a Simple HTTP Mock Server

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

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

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

    // Configure core features
    let config = Config {
        latency_enabled: true,
        failures_enabled: false,
        default_latency: LatencyProfile::with_normal_distribution(400, 120.0),
        ..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::{
    ChainConfig, ChainDefinition, ChainLink, ChainRequest, RequestChainRegistry, Result,
};
use mockforge_core::request_chaining::RequestBody;
use serde_json::json;
use std::collections::HashMap;

let registry = RequestChainRegistry::new(ChainConfig::default());

// Define a chain: create user → add to group → verify membership
let chain = ChainDefinition {
    id: "user_onboarding".to_string(),
    name: "User Onboarding".to_string(),
    description: Some("Create user → add to group".to_string()),
    config: ChainConfig {
        enabled: true,
        ..ChainConfig::default()
    },
    links: vec![
        ChainLink {
            request: ChainRequest {
                id: "create_user".to_string(),
                method: "POST".to_string(),
                url: "https://api.example.com/users".to_string(),
                headers: HashMap::new(),
                body: Some(RequestBody::json(json!({"name": "{{faker.name}}"}))),
                depends_on: Vec::new(),
                timeout_secs: None,
                expected_status: None,
                scripting: None,
            },
            extract: HashMap::from([("user_id".to_string(), "create_user.body.id".to_string())]),
            store_as: Some("create_user_response".to_string()),
        },
        ChainLink {
            request: ChainRequest {
                id: "add_to_group".to_string(),
                method: "POST".to_string(),
                url: "https://api.example.com/groups/{{user_id}}/members".to_string(),
                headers: HashMap::new(),
                body: None,
                depends_on: vec!["create_user".to_string()],
                timeout_secs: None,
                expected_status: None,
                scripting: None,
            },
            extract: HashMap::new(),
            store_as: None,
        },
    ],
    variables: HashMap::new(),
    tags: vec!["onboarding".to_string()],
};

registry.store().register_chain(chain).await?;

Latency & Failure Injection

Simulate realistic network conditions and errors:

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

// Configure latency simulation
let latency = LatencyProfile::with_normal_distribution(400, 120.0)
    .with_min_ms(100)
    .with_max_ms(800);

// 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(true, 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

Re-exports

pub use chain_execution::ChainExecutionEngine;

pub use chain_execution::ChainExecutionResult;

pub use chain_execution::ChainExecutionStatus;

pub use chaos_utilities::ChaosConfig;

pub use chaos_utilities::ChaosEngine;

pub use chaos_utilities::ChaosResult;

pub use chaos_utilities::ChaosStatistics;

pub use conditions::evaluate_condition;

pub use conditions::ConditionContext;

pub use conditions::ConditionError;

pub use config::apply_env_overrides;

pub use config::load_config;

pub use config::load_config_with_fallback;

pub use config::save_config;

pub use config::ApiKeyConfig;

pub use config::AuthConfig;

pub use config::ServerConfig;

pub use error::Error;

pub use error::Result;

pub use failure_injection::create_failure_injector;

pub use failure_injection::FailureConfig;

pub use failure_injection::FailureInjector;

pub use failure_injection::TagFailureConfig;

pub use latency::LatencyProfile;

pub use multi_tenant::MultiTenantConfig;

pub use multi_tenant::MultiTenantWorkspaceRegistry;

pub use multi_tenant::RoutingStrategy;

pub use multi_tenant::TenantWorkspace;

pub use multi_tenant::WorkspaceContext;

pub use multi_tenant::WorkspaceRouter;

pub use multi_tenant::WorkspaceStats;

pub use network_profiles::NetworkProfile;

pub use network_profiles::NetworkProfileCatalog;

pub use openapi::OpenApiOperation;

pub use openapi::OpenApiRoute;

pub use openapi::OpenApiSchema;

pub use openapi::OpenApiSecurityRequirement;

pub use openapi::OpenApiSpec;

pub use openapi_routes::create_registry_from_file;

pub use openapi_routes::create_registry_from_json;

pub use openapi_routes::OpenApiRouteRegistry;

pub use openapi_routes::ValidationOptions;

pub use overrides::OverrideMode;

pub use overrides::OverrideRule;

pub use overrides::Overrides;

pub use overrides::PatchOp;

pub use priority_handler::MockGenerator;

pub use priority_handler::MockResponse;

pub use priority_handler::PriorityHttpHandler;

pub use priority_handler::PriorityResponse;

pub use priority_handler::SimpleMockGenerator;

pub use protocol_abstraction::MessagePattern;

pub use protocol_abstraction::MiddlewareChain;

pub use protocol_abstraction::Protocol;

pub use protocol_abstraction::ProtocolMiddleware;

pub use protocol_abstraction::ProtocolRequest;

pub use protocol_abstraction::ProtocolResponse;

pub use protocol_abstraction::RequestMatcher;

pub use protocol_abstraction::ResponseStatus;

pub use protocol_abstraction::SpecOperation;

pub use protocol_abstraction::SpecRegistry;

pub use protocol_abstraction::ValidationError as ProtocolValidationError;

pub use protocol_abstraction::ValidationResult as ProtocolValidationResult;

pub use proxy::ProxyConfig;

pub use proxy::ProxyHandler;

pub use proxy::ProxyResponse;

pub use record_replay::clean_old_fixtures;

pub use record_replay::list_fixtures;

pub use record_replay::list_ready_fixtures;

pub use record_replay::list_smoke_endpoints;

pub use record_replay::RecordHandler;

pub use record_replay::RecordReplayHandler;

pub use record_replay::RecordedRequest;

pub use record_replay::ReplayHandler;

pub use request_chaining::ChainConfig;

pub use request_chaining::ChainContext;

pub use request_chaining::ChainDefinition;

pub use request_chaining::ChainExecutionContext;

pub use request_chaining::ChainLink;

pub use request_chaining::ChainRequest;

pub use request_chaining::ChainResponse;

pub use request_chaining::ChainStore;

pub use request_chaining::ChainTemplatingContext;

pub use request_chaining::RequestChainRegistry;

pub use request_fingerprint::RequestFingerprint;

pub use request_fingerprint::RequestHandlerResult;

pub use request_fingerprint::ResponsePriority;

pub use request_fingerprint::ResponseSource;

pub use request_logger::create_grpc_log_entry;

pub use request_logger::create_http_log_entry;

pub use request_logger::create_websocket_log_entry;

pub use request_logger::get_global_logger;

pub use request_logger::init_global_logger;

pub use request_logger::log_request_global;

pub use request_logger::CentralizedRequestLogger;

pub use request_logger::RequestLogEntry;

pub use routing::HttpMethod;

pub use routing::Route;

pub use routing::RouteRegistry;

pub use schema_diff::to_enhanced_422_json;

pub use schema_diff::validation_diff;

pub use schema_diff::ValidationError;

pub use server_utils::errors::json_error;

pub use server_utils::errors::json_success;

pub use server_utils::create_socket_addr;

pub use server_utils::localhost_socket_addr;

pub use server_utils::wildcard_socket_addr;

pub use sync_watcher::FileChange;

pub use sync_watcher::SyncEvent;

pub use sync_watcher::SyncService;

pub use sync_watcher::SyncWatcher;

pub use templating::expand_str;

pub use templating::expand_tokens;

pub use time_travel::RepeatConfig;

pub use time_travel::ResponseScheduler;

pub use time_travel::ScheduledResponse;

pub use time_travel::TimeTravelConfig;

pub use time_travel::TimeTravelManager;

pub use time_travel::TimeTravelStatus;

pub use time_travel::VirtualClock;

pub use time_travel_handler::time_travel_middleware;

pub use time_travel_handler::ScheduledResponseWrapper;

pub use time_travel_handler::TimeTravelHandler;

pub use traffic_shaping::BandwidthConfig;

pub use traffic_shaping::BurstLossConfig;

pub use traffic_shaping::TrafficShaper;

pub use traffic_shaping::TrafficShapingConfig;

pub use validation::validate_openapi_operation_security;

pub use validation::validate_openapi_security;

pub use validation::Validator;

pub use workspace::EntityId;

pub use workspace::Folder;

pub use workspace::MockRequest;

pub use workspace::Workspace;

pub use workspace::WorkspaceConfig;

pub use workspace::WorkspaceRegistry;

pub use workspace_import::create_workspace_from_curl;

pub use workspace_import::create_workspace_from_har;

pub use workspace_import::create_workspace_from_insomnia;

pub use workspace_import::create_workspace_from_postman;

pub use workspace_import::import_postman_to_existing_workspace;

pub use workspace_import::import_postman_to_workspace;

pub use workspace_import::WorkspaceImportConfig;

pub use workspace_import::WorkspaceImportResult;

pub use workspace_persistence::WorkspacePersistence;

pub use ws_proxy::WsProxyConfig;

pub use ws_proxy::WsProxyHandler;

pub use ws_proxy::WsProxyRule;

Modules

ai_response

AI-assisted response generation for dynamic mock endpoints

cache

High-performance caching utilities for MockForge

chain_execution

Chain execution engine for request chaining

chaos_utilities

Chaos testing utilities with orchestration and randomness

collection_export

conditions

Condition evaluation system for override rules

config

Configuration management for MockForge

contract_validation

docker_compose

encryption

End-to-end encryption module for MockForge

error

Error types for MockForge Core

failure_injection

Enhanced failure injection system with per-tag include/exclude filters and error rate configuration.

import

Import functionality for MockForge

intelligent_behavior

Intelligent Mock Behavior System

latency

Latency simulation and fault injection for MockForge

multi_tenant

Multi-tenant workspace support for MockForge

network_profiles

Pre-configured network condition profiles for easy simulation of various network scenarios

openapi

OpenAPI specification handling and utilities

openapi_routes

OpenAPI-based route generation for MockForge

overrides

Overrides engine with templating helpers.

performance

Performance monitoring and optimization utilities

priority_handler

Priority-based HTTP request handler implementing the full priority chain: Replay → Fail → Proxy → Mock → Record

protocol_abstraction

Protocol-agnostic abstractions for unified mocking across HTTP, GraphQL, gRPC, and WebSocket

proxy

Proxy functionality for forwarding requests to upstream services

record_replay

Record and replay functionality for HTTP requests and responses Implements the Replay and Record parts of the priority chain.

request_chaining

Request chaining for MockForge

request_fingerprint

Request fingerprinting system for unique request identification and priority-based response selection.

request_logger

Centralized request logging system for all MockForge servers

request_scripting

Pre/Post request scripting for MockForge chains

routing

Route registry and routing logic for MockForge

schema_diff

JSON schema diff utilities for 422 responses.

server_utils

Common server utilities for MockForge

sync_watcher

File system watcher for bidirectional directory sync

templating

Extended templating system for MockForge with request chaining support

time_travel

Time Travel / Temporal Testing Module

time_travel_handler

Time Travel Response Handler

traffic_shaping

Traffic shaping beyond latency simulation

validation

Schema validation logic for MockForge

workspace

Workspace and folder organization for MockForge requests

workspace_import

Workspace import utilities

workspace_persistence

Persistence layer for workspace configurations

ws_proxy

WebSocket proxy functionality for tunneling connections to upstream services

Structs

Config

Core configuration for MockForge

Uuid

A Universally Unique Identifier (UUID).