Expand description
§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 specificationsopenapi_routes: Register routes from OpenAPI specs with validationvalidation: Request/response validation against schemas
§Request Processing
routing: Route matching and registrationtemplating: Template variable expansion ({{uuid}}, {{now}}, etc.)request_chaining: Multi-step request workflowsoverrides: Dynamic request/response modifications
§Chaos Engineering
latency: Latency injection with configurable profilesfailure_injection: Simulate service failures and errorstraffic_shaping: Bandwidth limiting and packet loss
§Proxy & Hybrid
§Persistence & Import
workspace: Workspace management for organizing mocksworkspace_import: Import from Postman, Insomnia, cURL, HARrecord_replay: Record real requests and replay as fixtures
§Observability
request_logger: Centralized request loggingperformance: 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 servermockforge-grpc: gRPC mock servermockforge-ws: WebSocket mock servermockforge-graphql: GraphQL mock servermockforge-plugin-core: Plugin developmentmockforge-data: Synthetic data generation
§Documentation
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;Deprecated pub use behavioral_cloning::BehavioralSequence;Deprecated pub use behavioral_cloning::EdgeAmplificationConfig;Deprecated pub use behavioral_cloning::EdgeAmplifier;Deprecated pub use behavioral_cloning::EndpointProbabilityModel;Deprecated pub use behavioral_cloning::ErrorPattern;Deprecated pub use behavioral_cloning::LatencyDistribution;Deprecated pub use behavioral_cloning::PayloadVariation;Deprecated pub use behavioral_cloning::ProbabilisticModel;Deprecated pub use behavioral_cloning::SequenceLearner;Deprecated pub use behavioral_cloning::SequenceStep;Deprecated 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 custom_fixture::NestedFixture;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;Deprecated pub use git_watch::GitWatchService;Deprecated 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;Deprecated pub use multi_tenant::MultiTenantWorkspaceRegistry;Deprecated pub use multi_tenant::RoutingStrategy;Deprecated pub use multi_tenant::TenantWorkspace;Deprecated pub use multi_tenant::WorkspaceContext;Deprecated pub use multi_tenant::WorkspaceRouter;Deprecated pub use multi_tenant::WorkspaceStats;Deprecated 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_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;Deprecated pub use proxy::ProxyHandler;Deprecated pub use proxy::ProxyResponse;Deprecated 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_http_log_entry_with_query;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 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;Deprecated pub use schema_diff::validation_diff;Deprecated pub use schema_diff::ValidationError;Deprecated 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;Deprecated pub use sync_watcher::SyncEvent;Deprecated pub use sync_watcher::SyncService;Deprecated pub use sync_watcher::SyncWatcher;Deprecated 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::promotion_trait::PromotionService;Deprecated pub use workspace::EntityId;Deprecated pub use workspace::Folder;Deprecated pub use workspace::MockRequest;Deprecated pub use workspace::Workspace;Deprecated pub use workspace::WorkspaceConfig;Deprecated pub use workspace::WorkspaceRegistry;Deprecated pub use workspace_import::create_workspace_from_curl;Deprecated pub use workspace_import::create_workspace_from_har;Deprecated pub use workspace_import::create_workspace_from_insomnia;Deprecated pub use workspace_import::create_workspace_from_postman;Deprecated pub use workspace_import::import_postman_to_existing_workspace;Deprecated pub use workspace_import::import_postman_to_workspace;Deprecated pub use workspace_import::WorkspaceImportConfig;Deprecated pub use workspace_import::WorkspaceImportResult;Deprecated pub use workspace_persistence::WorkspacePersistence;Deprecated 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 Deprecated - Pillars: [Contracts][AI]
- ai_
response Deprecated - AI-assisted response generation for dynamic mock endpoints
- ai_
studio Deprecated - AI Studio - Unified AI Copilot for all AI-powered features Pillars: [AI]
- behavioral_
cloning Deprecated - Behavioral cloning of backends - learn from recorded traffic to create realistic mock behavior Behavioral Cloning of Backends
- behavioral_
economics Deprecated - Behavioral Economics Engine
- chain_
execution - Chain execution engine for request chaining
- chaos_
utilities - Pillars: [Reality]
- codegen
Deprecated - Code generation from OpenAPI specifications
- conditions
- Condition evaluation system for override rules
- config
- Configuration management for MockForge
- consistency
- Cross-protocol consistency engine for unified state across all protocols Pillars: [Reality]
- consumer_
contracts Deprecated - Consumer-driven contracts for tracking usage and detecting consumer-specific breaking changes Consumer-driven contracts
- contract_
drift Deprecated - Contract validation for ensuring API contracts match specifications Pillars: [Contracts]
- contract_
validation Deprecated - Contract validation for ensuring API contracts match specifications Pillars: [Contracts]
- 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
- drift_
gitops Deprecated - GitOps integration for drift budget violations GitOps integration for drift budget violations
- encryption
Deprecated - 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
- git_
watch Deprecated - Git Watch Mode
- graph
- Graph visualization data structures for MockForge
- import
Deprecated - Import functionality for MockForge
- incidents
- Incident management for drift and contract violations
- intelligent_
behavior Deprecated - Intelligent Mock Behavior System
- latency
- Pillars: [Reality]
- lifecycle
- Lifecycle hooks for extensibility
- multi_
tenant Deprecated - Multi-tenant workspace support for MockForge
- network_
profiles - Pre-configured network condition profiles for easy simulation of various network scenarios
- odata_
rewrite - OData function call URI rewrite middleware OData function call URI rewrite layer
- 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
- pillar_
tracking - Pillar usage tracking utilities Pillar usage tracking 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
- protocol_
server - Protocol server lifecycle trait for uniform server startup and shutdown Protocol server lifecycle trait for uniform server startup and shutdown.
- proxy
Deprecated - 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
- 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 Deprecated - 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 Deprecated - File system watcher for bidirectional directory sync
- template_
expansion - Template expansion utilities (Send-safe, isolated from templating module) Template expansion utilities for request context variables
- 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
- tls
- Shared TLS utilities for building rustls server and client configurations. Shared TLS utilities for MockForge protocol crates.
- traffic_
shaping - Traffic shaping beyond latency simulation
- validation
- Pillars: [Contracts]
- verification
- Request verification API for MockForge
- voice
- Pillars: [AI][DevX]
- workspace
Deprecated - Workspace and folder organization for MockForge requests
- workspace_
import Deprecated - Workspace import utilities
- workspace_
persistence Deprecated - Persistence layer for workspace configurations
- ws_
proxy - WebSocket proxy functionality for tunneling connections to upstream services