Rift

High-performance Mountebank-compatible HTTP/HTTPS mock server written in Rust

Rift is a high-performance, Mountebank-compatible mock server that delivers 2-250x better performance. Use your existing Mountebank configurations and enjoy faster test execution.

Documentation | Quick Start | Examples

---

Why Rift?

Mountebank Compatible

• Same REST API - Works with existing Mountebank clients and tooling
• Same Configuration - Load your imposters.json without changes
• Same Behavior - Predicates, responses, behaviors all work identically

Blazing Fast Performance

Feature	Mountebank	Rift	Speedup
Simple stubs	1,900 RPS	39,000 RPS	20x faster
JSONPath predicates	107 RPS	26,500 RPS	247x faster
XPath predicates	169 RPS	28,700 RPS	170x faster
Complex predicates	900 RPS	29,300 RPS	32x faster

Full Feature Support

• Imposters - HTTP/HTTPS mock servers
• Predicates - equals, contains, matches, exists, jsonpath, xpath, and, or, not
• Responses - Static, proxy, injection
• Behaviors - wait, decorate, copy, lookup
• Proxy Mode - Record and replay

---

Quick Start

Run with Docker

# Pull and run
docker pull zainalpour/rift-proxy:latest
docker run -p 2525:2525 -p 4545:4545 zainalpour/rift-proxy:latest

# Create your first imposter
curl -X POST http://localhost:2525/imposters \
  -H "Content-Type: application/json" \
  -d '{
    "port": 4545,
    "protocol": "http",
    "stubs": [{
      "predicates": [{ "equals": { "path": "/hello" } }],
      "responses": [{ "is": { "statusCode": 200, "body": "Hello, World!" } }]
    }]
  }'

# Test it
curl http://localhost:4545/hello

Use Existing Mountebank Config

# Load your existing imposters.json
docker run -p 2525:2525 -v $(pwd)/imposters.json:/imposters.json \
  zainalpour/rift-proxy:latest --configfile /imposters.json

---

Installation

Docker (Recommended)

docker pull zainalpour/rift-proxy:latest

Homebrew (macOS/Linux)

brew tap etacassiopeia/rift
brew install rift

Cargo (crates.io)

cargo install rift-http-proxy

Download Binary

Download pre-built binaries from GitHub Releases:

# Example for Linux x86_64
curl -LO https://github.com/EtaCassiopeia/rift/releases/latest/download/rift-vX.X.X-x86_64-unknown-linux-gnu.tar.gz
tar -xzf rift-vX.X.X-x86_64-unknown-linux-gnu.tar.gz
sudo mv rift-vX.X.X-x86_64-unknown-linux-gnu/bin/* /usr/local/bin/

Available platforms:

• Linux: x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-unknown-linux-musl, aarch64-unknown-linux-musl
• macOS: x86_64-apple-darwin, aarch64-apple-darwin
• Windows: x86_64-pc-windows-msvc

Build from Source

git clone https://github.com/EtaCassiopeia/rift.git
cd rift
cargo build --release
./target/release/rift-http-proxy

Node.js / npm

For Node.js projects, use the official npm package:

npm install @rift-vs/rift

import rift from '@rift-vs/rift';

const server = await rift.create({ port: 2525 });
// Create imposters, run tests...
await server.close();

---

Documentation

Getting Started

• Installation - Docker, binary, build from source
• Quick Start - Create your first imposter
• Node.js Integration - npm package for Node.js
• Migration Guide - Using Rift with Mountebank configs

Mountebank Compatibility

• Imposters - Mock server configuration
• Predicates - Request matching
• Responses - Response configuration
• Behaviors - wait, decorate, copy
• Proxy Mode - Record and replay

Configuration

• Mountebank Format - JSON configuration
• Native Rift Format - YAML for advanced features
• CLI Reference - Command-line options

Features

• Fault Injection - Chaos engineering
• Scripting - Rhai, Lua, JavaScript
• TLS/HTTPS - Secure connections
• Metrics - Prometheus integration
• TUI - Interactive terminal interface

Deployment

• Docker - Container deployment
• Kubernetes - K8s patterns

Reference

• REST API - Admin API reference
• Performance - Benchmarks

---

Example

{
  "port": 4545,
  "protocol": "http",
  "name": "User Service",
  "stubs": [
    {
      "predicates": [{ "equals": { "method": "GET", "path": "/users" } }],
      "responses": [{
        "is": {
          "statusCode": 200,
          "headers": { "Content-Type": "application/json" },
          "body": [{ "id": 1, "name": "Alice" }]
        }
      }]
    },
    {
      "predicates": [{
        "and": [
          { "equals": { "method": "GET" } },
          { "matches": { "path": "/users/\\d+" } }
        ]
      }],
      "responses": [{
        "is": { "statusCode": 200, "body": { "id": 1, "name": "Alice" } }
      }]
    }
  ]
}

More examples in examples/.

---

Metrics

Prometheus metrics on :9090/metrics:

curl http://localhost:9090/metrics

Metrics include request counts, latency histograms, fault injection stats, and more.

---

CLI Tools

Rift includes additional command-line tools. All tools are included when you install via Homebrew or download release binaries.

rift-tui - Interactive Terminal UI

Manage imposters and stubs through an interactive terminal interface:

# If installed via Homebrew or release binary
rift-tui

# Connect to a different admin URL
rift-tui --admin-url http://localhost:2525

Features:

• View and manage imposters with vim-style navigation (j/k)
• Create, edit, and delete stubs with JSON editor
• Generate curl commands for testing stubs
• Import/export imposter configurations
• Search and filter imposters and stubs
• Real-time metrics dashboard

rift-verify - Stub Verification

Automatically test your imposters by generating requests from predicates:

rift-verify --show-curl

rift-lint - Configuration Linter

Validate imposter configuration files before loading:

# If installed via Homebrew or release binary
rift-lint ./imposters/

# Via Docker (for CI/CD)
docker run --rm -v $(pwd):/imposters zainalpour/rift-lint .

# Via cargo
cargo install rift-lint
rift-lint ./imposters/

---

Development

# Build
cargo build --release

# Run tests
cargo test --all

# Run with debug logging
RUST_LOG=debug ./target/release/rift-http-proxy

# Run benchmarks
cd tests/benchmark && ./scripts/run-benchmark.sh

---

Contributing

Contributions welcome! Please read our contributing guidelines and submit PRs.

---

License

Apache License 2.0 - see LICENSE for details.

---

Acknowledgments

• Mountebank - The original service virtualization tool that inspired Rift's API and configuration format