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 ab_testing::apply_variant_to_response;

pub use ab_testing::select_variant;

pub use ab_testing::ABTestConfig;

pub use ab_testing::ABTestReport;

pub use ab_testing::ABTestingMiddlewareState;

pub use ab_testing::MockVariant;

pub use ab_testing::VariantAllocation;

pub use ab_testing::VariantAnalytics;

pub use ab_testing::VariantComparison;

pub use ab_testing::VariantManager;

pub use ab_testing::VariantSelectionStrategy;

pub use behavioral_cloning::AmplificationScope;

pub use behavioral_cloning::BehavioralSequence;

pub use behavioral_cloning::EdgeAmplificationConfig;

pub use behavioral_cloning::EdgeAmplifier;

pub use behavioral_cloning::EndpointProbabilityModel;

pub use behavioral_cloning::ErrorPattern;

pub use behavioral_cloning::LatencyDistribution;

pub use behavioral_cloning::PayloadVariation;

pub use behavioral_cloning::ProbabilisticModel;

pub use behavioral_cloning::SequenceLearner;

pub use behavioral_cloning::SequenceStep;

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 consistency::ConsistencyEngine;

pub use consistency::EntityState;

pub use consistency::ProtocolState;

pub use consistency::SessionInfo;

pub use consistency::StateChangeEvent;

pub use consistency::UnifiedState;

pub use custom_fixture::CustomFixture;

pub use custom_fixture::CustomFixtureLoader;

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 deceptive_canary::CanaryRoutingStrategy;

pub use deceptive_canary::CanaryStats;

pub use deceptive_canary::DeceptiveCanaryConfig;

pub use deceptive_canary::DeceptiveCanaryRouter;

pub use deceptive_canary::TeamIdentifiers;

pub use error::Error;

pub use error::Result;

pub use failure_analysis::ContributingFactor;

pub use failure_analysis::FailureContext;

pub use failure_analysis::FailureContextCollector;

pub use failure_analysis::FailureNarrative;

pub use failure_analysis::FailureNarrativeGenerator;

pub use failure_analysis::NarrativeFrame;

pub use failure_injection::create_failure_injector;

pub use failure_injection::FailureConfig;

pub use failure_injection::FailureInjector;

pub use failure_injection::TagFailureConfig;

pub use fidelity::FidelityCalculator;

pub use fidelity::FidelityScore;

pub use fidelity::SampleComparator;

pub use fidelity::SchemaComparator;

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 pillars::Pillar;

pub use pillars::PillarMetadata;

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 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 runtime_validation::RuntimeValidationError;

pub use runtime_validation::RuntimeValidationResult;

pub use runtime_validation::RuntimeValidatorConfig;

pub use runtime_validation::SchemaMetadata;

pub use scenario_studio::ConditionOperator;

pub use scenario_studio::FlowCondition;

pub use scenario_studio::FlowConnection;

pub use scenario_studio::FlowDefinition;

pub use scenario_studio::FlowExecutionResult;

pub use scenario_studio::FlowExecutor;

pub use scenario_studio::FlowPosition;

pub use scenario_studio::FlowStep;

pub use scenario_studio::FlowStepResult;

pub use scenario_studio::FlowType;

pub use scenario_studio::FlowVariant;

pub use scenario_studio::StepType;

pub use scenarios::types::StepResult;

pub use scenarios::ScenarioDefinition;

pub use scenarios::ScenarioExecutor;

pub use scenarios::ScenarioParameter;

pub use scenarios::ScenarioRegistry;

pub use scenarios::ScenarioResult;

pub use scenarios::ScenarioStep;

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 snapshots::SnapshotComponents;

pub use snapshots::SnapshotManager;

pub use snapshots::SnapshotManifest;

pub use snapshots::SnapshotMetadata;

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::GeneratedWorkspaceScenario;

pub use voice::HookTranspiler;

pub use voice::ParsedCommand;

pub use voice::ParsedWorkspaceScenario;

pub use voice::VoiceCommandParser;

pub use voice::VoiceSpecGenerator;

pub use voice::WorkspaceConfigSummary;

pub use voice::WorkspaceScenarioGenerator;

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

ab_testing

A/B Testing for Mocks

ai_contract_diff

Pillars: [Contracts][AI]

ai_response

AI-assisted response generation for dynamic mock endpoints

ai_studio

AI Studio - Unified AI Copilot for all AI-powered features Pillars: [AI]

behavioral_cloning

Behavioral cloning of backends - learn from recorded traffic to create realistic mock behavior Behavioral Cloning of Backends

cache

High-performance caching utilities for MockForge

chain_execution

Chain execution engine for request chaining

chaos_utilities

Pillars: [Reality]

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

consistency

Cross-protocol consistency engine for unified state across all protocols Cross-protocol consistency engine

consumer_contracts

Consumer-driven contracts for tracking usage and detecting consumer-specific breaking changes Consumer-driven contracts

contract_drift

Contract validation for ensuring API contracts match specifications Pillars: [Contracts]

contract_validation

Contract validation for ensuring API contracts match specifications Pillars: [Contracts]

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

deceptive_canary

Deceptive canary mode for routing team traffic to deceptive deploys Deceptive Canary Mode

docker_compose

Docker Compose integration for containerized mock deployments

drift_gitops

GitOps integration for drift budget violations GitOps integration for drift budget violations

encryption

End-to-end encryption module for MockForge

error

Error types for MockForge Core

failure_analysis

Failure analysis and root-cause narrative generation

failure_injection

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

fidelity

Fidelity Score Calculator

generate_config

Configuration for mock generation from OpenAPI specifications

generative_schema

Pillars: [Reality][AI]

git_watch

Git Watch Mode

graph

Graph visualization data structures for MockForge

import

Import functionality for MockForge

incidents

Incident management for drift and contract violations

intelligent_behavior

Intelligent Mock Behavior System

latency

Pillars: [Reality]

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

pillars

Pillar metadata system for compile-time pillar tagging Pillar metadata system for compile-time pillar tagging

pr_generation

Pull request generation for contract changes

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

Pillars: [Reality]

reality_continuum

Pillars: [Reality]

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

runtime_validation

Runtime validation for SDKs (request/response validation at runtime) Runtime validation for SDKs

scenario_studio

Scenario Studio - Visual editor for co-editing business flows Scenario Studio

scenarios

Scenario-First SDKs

schema_diff

Pillars: [Contracts]

security

Security module for MockForge

server_utils

Common server utilities for MockForge

snapshots

Time travel and snapshot functionality for saving and restoring system states Time travel and snapshot functionality

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

Pillars: [DevX]

time_travel

Time Travel / Temporal Testing Module

time_travel_handler

Time Travel Response Handler

traffic_shaping

Traffic shaping beyond latency simulation

validation

Pillars: [Contracts]

verification

Request verification API for MockForge

voice

Pillars: [AI][DevX]

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).