Molock - High-Performance Mock Server

⚠️ DISCLAIMER: Experimental Project

This project is an experimental codebase created using AI-assisted development.

Before using in production:

• Code has not been manually reviewed by humans
• Security audits have not been completed
• API/behavior may change without notice
• Test coverage meets project standards but may have edge cases

Use at your own risk.

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

Features

• High Performance: Built with Rust and Actix-web for maximum throughput
• Dynamic Rules: Configure endpoints with flexible matching rules
• Response Control: Add delays, failure injection, and stateful behavior
• OpenTelemetry Integration: Built-in tracing, metrics, and logging
• Hot Reload: Watch configuration files for live updates
• Docker Ready: Production-ready container images
• Comprehensive Testing: >80% code coverage with unit and integration tests

Security & Supply Chain

Molock is committed to supply chain security. The project implements OpenSSF SLSA Level 2 requirements:

• Provenance: Cryptographically signed build provenance for all releases
• Hosted Build: All builds run on GitHub Actions (hosted infrastructure)
• Verified: SLSA provenance is automatically verified in CI on main branch

Verifying Releases

You can verify the authenticity of Molock releases using the SLSA verifier:

# Install the SLSA verifier
go install github.com/slsa-framework/slsa-verifier/cli/slsa-verifier@latest

# Verify a release
slsa-verifier --provenance-path <provenance-file> --artifact-path <binary> --source-uri github.com/fike/molock

Release artifacts and provenance are available on the Releases page.

Quick Start

Prerequisites

• Rust 1.70+
• Docker and Docker Compose (for deployment)

Installation

# Clone the repository
git clone https://github.com/your-org/molock.git
cd molock

# Build the project
make build

# Run tests
make test

# Start the server
make run

Using Docker

# Build and run with Docker Compose
make docker-build
make docker-run

Configuration

Molock uses YAML configuration files. See config/molock-config.yaml for examples:

server:
  port: 8080
  workers: 4

endpoints:
  - 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": "not found"}'

  - name: "Retry Example"
    method: GET
    path: "/retry"
    stateful: true
    responses:
      - status: 200
        condition: "request_count > 2"
        body: "OK"
      - status: 503
        default: true
        body: "Service Unavailable"

Configuration Options

• Server: Port, workers, host, and request size limits
• Telemetry: OpenTelemetry endpoint, service name, sampling rate
• Logging: Log level, format, and OpenTelemetry log integration
• Endpoints: HTTP methods, paths with parameters, response rules

Response Features

• Delays: Fixed (100ms) or random ranges (100-500ms)
• Conditions: Simple expressions using request data
• Probability: Random response selection with weights
• Stateful: Per-client counters for retry logic
• Templates: Dynamic response generation with variables

Observability

Molock integrates with OpenTelemetry for comprehensive observability:

• Traces: Request spans with timing and metadata
• Metrics: Request counts, errors, and latency histograms
• Logs: Structured JSON logging with trace context

Local Development Stack

# Start the full observability stack
docker-compose -f deployment/docker-compose.yml up

Access the monitoring tools:

• Jaeger: http://localhost:16686 (traces)
• Prometheus: http://localhost:9090 (metrics)
• Grafana: http://localhost:3000 (dashboards)

API Reference

Health Check

GET /health

Returns server health status.

Metrics

GET /metrics

Prometheus-formatted metrics (when not using OTLP).

Mock Endpoints

All configured endpoints are available at their specified paths. The server matches requests based on:

• HTTP method
• Path (with parameter support: /users/:id)
• Query parameters
• Headers
• Request body

Development

Project Structure

molock/
├── src/
│   ├── config/     # Configuration loading and parsing
│   ├── server/     # Actix web server setup
│   ├── rules/      # Rule matching and execution
│   ├── telemetry/  # OpenTelemetry integration
│   └── utils/      # Helper functions
├── tests/          # Integration tests
├── config/         # Configuration files
├── deployment/     # Docker and deployment artifacts
└── .ai/           # AI-assisted development documentation

Building and Testing

# Build release binary
make build

# Run all tests
make test

# Run tests with coverage
make test-coverage

# Check code quality
make lint
make fmt

# Development mode
make dev

Benchmarking

Molock includes comprehensive Apache Benchmark (ab) tests for performance evaluation:

# Install Apache Benchmark (if not already installed)
sudo apt-get install apache2-utils  # Ubuntu/Debian
brew install apachebench            # macOS
sudo yum install httpd-tools        # RHEL/CentOS

# Run comprehensive benchmark suite
make benchmark

# Run individual benchmark scenarios
make benchmark-health     # Health endpoint benchmarks
make benchmark-users     # User endpoint benchmarks  
make benchmark-delay     # Delayed response benchmarks
make benchmark-post      # POST endpoint benchmarks

For detailed benchmarking instructions, see BENCHMARKING.md.

Adding New Features (TDD Required)

1. Write failing tests first following TDD guidelines in .ai/TDD_GUIDE.md
2. Implement minimal solution to make tests pass
3. Refactor while keeping tests green
4. Ensure 80%+ test coverage using make test-coverage
5. Follow coding conventions in .ai/Agents.md
6. Update documentation as needed
7. Run make test and make lint before committing

IMPORTANT: All contributions MUST follow Test-Driven Development (TDD) principles. PRs without adequate test coverage (<80%) will be rejected.

Deployment

Docker

# Build the Docker image
docker build -f deployment/Dockerfile -t molock .

# Run the container
docker run -p 8080:8080 -v ./config:/etc/molock/config molock

Kubernetes

See the deployment/ directory for example Kubernetes manifests.

Environment Variables

• MOLOCK_CONFIG_PATH: Path to configuration file
• OTEL_EXPORTER_OTLP_ENDPOINT: OpenTelemetry collector endpoint
• OTEL_SERVICE_NAME: Service name for telemetry
• RUST_LOG: Log level (info, debug, trace)

Contributing

Please read .ai/CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

For AI-Assisted Development

This project supports AI-assisted development workflows:

Configuration File	Description
AGENTS.md (root)	Project-specific instructions and conventions
.ai/Agents.md	Extended guidelines, TDD workflow, and skills
.ai/.cursorrules	IDE-specific rules

Quick Commands

# Build and test
make build
make test

# Code quality
make lint
make fmt
make test-coverage

# Development
make run
make dev

See .ai/Agents.md for detailed guidelines, or AGENTS.md for a standardized format compatible with AI coding agents.

License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.

Support

• Issues: Use the GitHub issue tracker
• Documentation: Check .ai/Skills.md for technical guidance
• Questions: Open a discussion on GitHub

Acknowledgments

• Built with Actix-web
• Observability with OpenTelemetry
• Configuration with Serde
• Testing with Tokio

License

Molock is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.