dhl/README.md

DHL - Simple HTTP/HTTPS Mock Server

DHL is a lightweight, configurable HTTP/HTTPS mock server built with Rust and Axum. It allows you to define multiple routes that return static JSON responses from files.

Features

• Live Configuration Reloading: Changes to config.json (routes, status codes, etc.) and response files are applied immediately without restarting the server.
• Multi-Route Support: Define as many paths as you need.
• JSON Response Files: Responses are loaded from external JSON files.
• Colorized Request Logging: Detailed logging of incoming requests with terminal colors. Status codes are color-coded for quick identification:
  • 2xx Success: Green
  • 4xx Client Error: Yellow
  • 5xx Server Error: Red
• Header Masking: Sensitive headers like Authorization can be masked in logs.
• HTTPS/TLS Support: Optional TLS support for secure connections.
• Automatic Default Generation: Creates default configuration and response files if they are missing.
• Custom 404 Handler: Returns a standard {"error": "Not Found"} JSON for unknown paths.

Configuration (config.json)

The server is configured via a config.json file in the root directory.

Example Configuration

{
  "host": "127.0.0.1",
  "port": 3000,
  "routes": [
    {
      "path": "/",
      "response_file": "response.json",
      "status_code": 200
    },
    {
      "path": "/api/status",
      "response_file": "status.json",
      "status_code": 201
    }
  ],
  "masking": {
    "enabled": true,
    "headers": ["authorization", "x-api-key", "cookie"]
  },
  "tls": {
    "enabled": false,
    "cert_path": "cert.pem",
    "key_path": "key.pem"
  }
}

Fields

Field	Type	Description
host	String	The IP address to bind to (e.g., 127.0.0.1 or 0.0.0.0).
port	Number	The port to listen on.
routes	Array	A list of route configuration objects (see below).
masking	Object	Configuration for masking sensitive headers in logs.
tls	Object	Configuration for HTTPS/TLS support.

Route Object

Field	Type	Description
path	String	The URL path (e.g., / or /api/data).
response_file	String	Path to the JSON file containing the response body.
status_code	Number	The HTTP status code to return (e.g., 200, 201, 400).

Masking Object

Field	Type	Description
enabled	Boolean	Whether to enable header masking.
headers	Array	List of header names (case-insensitive) to mask in the logs.

TLS Object

Field	Type	Description
enabled	Boolean	Whether to enable HTTPS.
cert_path	String	Path to the PEM-encoded TLS certificate file.
key_path	String	Path to the PEM-encoded TLS private key file.

Usage

Running Locally

Ensure you have Rust installed.

cargo run

Building for Release

cargo build --release

Using with Docker

You can run DHL as a Docker container. The application automatically generates a default config.json and response.json if they are missing in the work directory.

Build the Image

docker build -t dhl .

Run with Docker CLI

To persist your configuration and response files, mount a local directory to /app in the container. The application will create default files in that directory if it is empty.

# Create a folder for your mock data
mkdir mock-data

# Run the container and mount the folder
docker run -p 3000:3000 -v $(pwd)/mock-data:/app dhl

Run with Docker Compose

An example docker-compose.yml is provided in the root directory:

version: '3.8'

services:
  dhl:
    build: .
    ports:
      - "3000:3000"
    volumes:
      - ./mock-data:/app
    restart: unless-stopped

To start:

docker-compose up -d

Note: The default host is set to 0.0.0.0 for Docker compatibility. If you are using a custom config.json, ensure the host is set to 0.0.0.0.

Release Assets

When downloading a release, you will find:

• The dhl binary (Linux) or dhl.exe (Windows).
• config.json: An example configuration file.
• response.json: An example response file.

Simply place the binary and the two JSON files in the same folder and start the application.

CI/CD

This project includes a Gitea Actions workflow that automatically:

1. Builds the application for Linux and Windows.
2. Packages them into dhl-linux.tar.gz and dhl-windows.zip respectively, including example configuration files.
3. Creates a Gitea Release with these assets whenever a version tag (e.g., v0.5.0) is pushed.

Project Structure

The code is modularized for better maintainability:

• src/main.rs: Entry point and server initialization.
• src/config.rs: Configuration loading and structures.
• src/handlers.rs: Route handling logic and fallback.
• src/middleware.rs: Request logging middleware.
• src/state.rs: Shared application state.