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 data_source::DataSource;

pub use data_source::DataSourceConfig;

pub use data_source::DataSourceContent;

pub use data_source::DataSourceFactory;

pub use data_source::DataSourceManager;

pub use data_source::DataSourceType;

pub use data_source::GitDataSource;

pub use data_source::HttpDataSource;

pub use data_source::LocalDataSource;

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 generate_config::discover_config_file;

pub use generate_config::load_generate_config;

pub use generate_config::load_generate_config_with_fallback;

pub use generate_config::save_generate_config;

pub use generate_config::BarrelType;

pub use generate_config::GenerateConfig;

pub use generate_config::GenerateOptions;

pub use generate_config::InputConfig;

pub use generate_config::OutputConfig;

pub use generate_config::PluginConfig;

pub use git_watch::GitWatchConfig;

pub use git_watch::GitWatchService;

pub use graph::builder::GraphBuilder;

pub use graph::relationships;

pub use graph::ClusterType;

pub use graph::EdgeType;

pub use graph::GraphCluster;

pub use graph::GraphData;

pub use graph::GraphEdge;

pub use graph::GraphNode;

pub use graph::NodeType;

pub use graph::Protocol as GraphProtocol;

pub use latency::LatencyProfile;

pub use lifecycle::LifecycleHook;

pub use lifecycle::LifecycleHookRegistry;

pub use lifecycle::MockLifecycleEvent;

pub use lifecycle::RequestContext;

pub use lifecycle::ResponseContext;

pub use lifecycle::ServerLifecycleEvent;

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 output_control::apply_banner;

pub use output_control::apply_extension;

pub use output_control::apply_file_naming_template;

pub use output_control::build_file_naming_context;

pub use output_control::process_generated_file;

pub use output_control::BarrelGenerator;

pub use output_control::FileNamingContext;

pub use output_control::GeneratedFile;

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 reality::PresetMetadata;

pub use reality::RealityConfig;

pub use reality::RealityEngine;

pub use reality::RealityLevel;

pub use reality::RealityPreset;

pub use reality_continuum::ContinuumConfig;

pub use reality_continuum::ContinuumRule;

pub use reality_continuum::MergeStrategy;

pub use reality_continuum::RealityContinuumEngine;

pub use reality_continuum::ResponseBlender;

pub use reality_continuum::TimeSchedule;

pub use reality_continuum::TransitionCurve;

pub use reality_continuum::TransitionMode;

pub use custom_fixture::CustomFixture;

pub use custom_fixture::CustomFixtureLoader;

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 route_chaos::RouteChaosInjector;

pub use route_chaos::RouteFaultResponse;

pub use route_chaos::RouteMatcher;

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 spec_parser::GraphQLValidator;

pub use spec_parser::OpenApiValidator;

pub use spec_parser::SpecFormat;

pub use stateful_handler::ResourceIdExtract;

pub use stateful_handler::StateInfo;

pub use stateful_handler::StateResponse;

pub use stateful_handler::StatefulConfig;

pub use stateful_handler::StatefulResponse;

pub use stateful_handler::StatefulResponseHandler;

pub use stateful_handler::TransitionTrigger;

pub use sync_watcher::FileChange;

pub use sync_watcher::SyncEvent;

pub use sync_watcher::SyncService;

pub use sync_watcher::SyncWatcher;

pub use template_library::TemplateLibrary;

pub use template_library::TemplateLibraryEntry;

pub use template_library::TemplateLibraryManager;

pub use template_library::TemplateMarketplace;

pub use template_library::TemplateMetadata;

pub use template_library::TemplateVersion;

pub use templating::expand_str;

pub use templating::expand_tokens;

pub use time_travel::cron::CronJob;

pub use time_travel::cron::CronJobAction;

pub use time_travel::cron::CronScheduler;

pub use time_travel::get_global_clock;

pub use time_travel::is_time_travel_enabled;

pub use time_travel::now as time_travel_now;

pub use time_travel::register_global_clock;

pub use time_travel::unregister_global_clock;

pub use time_travel::RepeatConfig;

pub use time_travel::ResponseScheduler;

pub use time_travel::ScheduledResponse;

pub use time_travel::TimeScenario;

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 verification::matches_verification_pattern;

pub use verification::verify_at_least;

pub use verification::verify_never;

pub use verification::verify_requests;

pub use verification::verify_sequence;

pub use verification::VerificationCount;

pub use verification::VerificationRequest;

pub use verification::VerificationResult;

pub use voice::ConversationContext;

pub use voice::ConversationManager;

pub use voice::ConversationState;

pub use voice::ParsedCommand;

pub use voice::VoiceCommandParser;

pub use voice::VoiceSpecGenerator;

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_contract_diff

AI-powered contract diff analysis

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

codegen

Code generation from OpenAPI specifications

collection_export

Collection export utilities for exporting mock data in various formats

conditions

Condition evaluation system for override rules

config

Configuration management for MockForge

contract_validation

Contract validation for ensuring API contracts match specifications

contract_webhooks

Contract webhooks for notifying external systems about contract changes Contract change webhook system

custom_fixture

Custom fixture format support for simple JSON fixtures

data_source

Data source abstraction for loading test data from multiple sources Data Source Abstraction

docker_compose

Docker Compose integration for containerized mock deployments

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.

generate_config

Configuration for mock generation from OpenAPI specifications

generative_schema

Generative Schema Mode - Complete API ecosystem generation from JSON examples

git_watch

Git Watch Mode

graph

Graph visualization data structures for MockForge

import

Import functionality for MockForge

intelligent_behavior

Intelligent Mock Behavior System

latency

Latency simulation and fault injection for MockForge

lifecycle

Lifecycle hooks for extensibility

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

output_control

Output control utilities for MockForge generation

overrides

Overrides engine with templating helpers.

performance

Performance monitoring and optimization utilities

priority_handler

Priority-based HTTP request handler implementing the full priority chain: Custom Fixtures → Replay → Stateful → Route Chaos (per-route fault/latency) → Global 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

reality

Reality Slider - Unified control for mock environment realism

reality_continuum

Reality Continuum - Dynamic blending of mock and real data sources

record_replay

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

request_capture

Request capture system for contract diff analysis

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

route_chaos

Per-route fault injection and latency simulation

routing

Route registry and routing logic for MockForge

schema_diff

JSON schema diff utilities for 422 responses.

security

Security module for MockForge

server_utils

Common server utilities for MockForge

spec_parser

Unified specification parser and validator

stateful_handler

Stateful response handler for HTTP requests

sync_watcher

File system watcher for bidirectional directory sync

template_library

Template library system for shared templates, versioning, and marketplace Template Library System

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

verification

Request verification API for MockForge

voice

Voice + LLM Interface 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).