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

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 (from GitHub Container Registry)
docker pull ghcr.io/etacassiopeia/rift-proxy:latest
docker run -p 2525:2525 ghcr.io/etacassiopeia/rift-proxy:latest

# Or from Docker Hub
docker pull etacassiopeia/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 \
  ghcr.io/etacassiopeia/rift-proxy:latest --configfile /imposters.json

Installation

Docker (Recommended)

# GitHub Container Registry (recommended)
docker pull ghcr.io/etacassiopeia/rift-proxy:latest

# Or Docker Hub
docker pull etacassiopeia/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 ghcr.io/etacassiopeia/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