Introduction

Molock is a production-ready mock server designed for high-throughput environments, CI/CD pipelines, and stress testing. Built in Rust with Actix-web, it provides configurable and observable mock endpoints with native OpenTelemetry integration.

🏛️ Core Pillars

Molock is built on three foundational pillars:

1. 🚀 Extreme Performance: Leveraging Rust and Actix-web for zero-allocation hot paths and maximum throughput (>10k req/s).
2. 🔭 Native Observability: OpenTelemetry is a first-class citizen, providing out-of-the-box traces, metrics, and logs.
3. 🛡️ Rigorous Quality: Developed using strict Test-Driven Development (TDD) with >80% line/branch coverage and SLSA Level 2 supply chain security.

🏗️ Architecture

Molock follows a modular architecture designed for speed and extensibility:

graph TD
    Client[HTTP Client] --> Server[Actix-web Server]
    Server --> Engine[Rule Engine]
    Engine --> Matcher{Request Matcher}
    Matcher -->|Match| Exec[Executor]
    Matcher -->|No Match| Fallback[404 Default]
    Exec --> Template[Template Renderer]
    Template --> Response[HTTP Response]

    Server -.-> Telemetry[Tracing/Metrics/Logs]
    Telemetry -.-> Collector[OTel Collector]

Getting Started

To get started with Molock, you’ll need to install the project and run the server.

Prerequisites

• Rust: Version 1.70 or higher.
• Docker & Docker Compose: For running the observability stack (Jaeger, Prometheus, Grafana).
• Make: (Optional) For using the provided shortcuts in the Makefile.

Installation

# Clone the repository
git clone https://github.com/fike/molock.git
cd molock

# Build the project
make build

# Run tests
make test

# Start the server with default configuration
make run

Immediate Usage

Once the server is running, you can test it with curl:

# Health check (with dynamic timestamp)
curl http://localhost:8080/health

# Path parameter matching
curl http://localhost:8080/users/123

# Regex/Condition matching (triggers 404 if not found)
curl http://localhost:8080/users/unknown

Configuration Guide

Molock is highly configurable via YAML files. The default configuration can be found in config/molock-config.yaml.

Server Configuration

The server section defines the basic network settings for the mock server.

server:
  port: 8080
  workers: 4
  host: "0.0.0.0"
  max_request_size: 10485760  # 10MB

Telemetry Configuration

Molock has native support for OpenTelemetry.

telemetry:
  enabled: true
  service_name: "molock"
  service_version: "0.1.0"
  endpoint: "http://localhost:4317"
  protocol: "grpc"
  sampling_rate: 1.0
  log_level: "info"
  log_format: "json"

Endpoints

Endpoints are the heart of Molock. Each endpoint consists of a name, method, path, and a list of responses.

Request Matching

Molock matches incoming requests based on:

• Method: HTTP method (GET, POST, etc.)
• Path: Supports parameters (e.g., /users/:id) and regex.
• Conditions: Logic applied to headers, query parameters, and body.

Response Features

• Status: The HTTP status code to return.
• Body: The response payload, supporting templates (e.g., {{id}}).
• Headers: Custom HTTP headers.
• Delay: Fixed (e.g., 50ms) or random delays.
• Probability: Failure injection or random response selection.
• Stateful Logic: Simulate retries using state counters (e.g., request_count).

Example: Dynamic Response

  - name: "Get User"
    method: GET
    path: "/users/:id"
    responses:
      - status: 200
        delay: 50ms
        body: '{"id": "{{id}}", "name": "John Doe"}'
      - status: 404
        condition: "id == 'unknown'"
        body: '{"error": "User not found"}'

Observability

Molock is designed with observability as a core requirement. It integrates with OpenTelemetry to provide deep insights into its internal operations and the traffic it handles.

Core Concepts

• Traces: Every request handled by Molock generates a span, allowing you to trace the lifecycle of a mock request and see matching logic and delays.
• Metrics: Molock exports Prometheus-compatible metrics for request counts, error rates, and latency histograms.
• Logs: Structured JSON logs are correlated with trace IDs for easy troubleshooting.

Local Observability Stack

You can start a complete monitoring stack locally using Docker Compose:

docker-compose -f deployment/docker-compose.yml up -d

Accessing the Tools

• Jaeger (Traces): http://localhost:16686
• Prometheus (Metrics): http://localhost:9090
• Grafana (Dashboards): http://localhost:3000

Validating Observability

We provide a script to verify that your OTel configuration is working correctly and that data is reaching the collector:

./tests/validate_observability.sh

Contributing

Thank you for your interest in contributing to Molock!

The source of truth for our contribution guidelines is the CONTRIBUTING.md file in the root of the repository.

Key Principles

• TDD (Test-Driven Development): All features and bug fixes must have accompanying tests.
• Zero-Warning Policy: Code must pass clippy and fmt without any warnings.
• Branch Protocol: Never commit directly to main. Always use feature branches.
• Observability: New features must include appropriate telemetry (spans, metrics, logs).

Development Workflow

1. Find an issue in our tracker (bd ready).
2. Claim the issue (bd update <id> --claim).
3. Create a feature branch.
4. Implement your changes following the TDD cycle.
5. Submit a Pull Request.