molock 0.1.0

High-performance mock server for CI/CD pipelines and testing
molock-0.1.0 is not a library.

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

SLSA 2

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

License

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