hexswitch 0.1.1

Hexagonal runtime switchboard for config-driven microservices

HexSwitch

Hexagonal runtime switchboard for config-driven microservices.

Description

HexSwitch is a runtime system designed to orchestrate microservices using a hexagonal architecture pattern. It provides a configuration-driven approach to wiring together inbound and outbound adapters, enabling flexible and maintainable service communication.

Status: Core runtime functionality is implemented, including adapter framework, HTTP inbound adapter, and runtime orchestration. The system can now run microservices with config-driven adapter wiring.

Installation

Install HexSwitch in development mode:

pip install -e ".[dev]"

This installs the package and all development dependencies (linting, testing, type checking).

Running Tests

Run the test suite:

pytest

Run with coverage report:

pytest --cov=src/hexswitch --cov-report=html

Run only unit tests:

pytest tests/unit/

Run only integration tests:

pytest tests/integration/

Run Docker integration tests:

pytest tests/integration/test_docker.py -m docker

Run multi-container integration tests:

pytest tests/integration/test_multi_container.py -v

Or use the test scripts:

# Linux/Mac
./scripts/test-docker.sh

# Windows PowerShell
.\scripts\test-docker.ps1

Multi-Container Testing

Test interactions between multiple HexSwitch instances:

# Start multi-container setup
docker compose -f docker-compose.multi-test.yml up -d

# Run tests
pytest tests/integration/test_multi_container.py -v

# Stop and cleanup
docker compose -f docker-compose.multi-test.yml down -v

For detailed development instructions, see Development Guide.

Running the CLI

After installation, you can run HexSwitch from the command line:

Available Commands

Show version:

hexswitch version
# or
hexswitch --version  # backwards compatible

Create example configuration:

hexswitch init

Create configuration from template:

hexswitch init --template hex-config.http-only
hexswitch init --list-templates  # List available templates

Configuration Templates

HexSwitch supports Jinja2 templates for configuration files. Templates allow you to use environment variables and dynamic values in your configuration.

Template files must have a .j2 extension (e.g., hex-config.yaml.j2). The load_config() function automatically detects and renders templates before parsing YAML.

Available templates:

• hex-config.yaml.j2 - Full configuration with all adapters
• hex-config.http-only.yaml.j2 - Minimal HTTP-only configuration
• hex-config.with-mcp.yaml.j2 - Configuration with MCP client adapter

Example template usage:

service:
  name: {{ env.SERVICE_NAME | default("example-service") }}
  runtime: python

inbound:
  http:
    enabled: {{ env.ENABLE_HTTP | default(true) }}
    port: {{ env.HTTP_PORT | default(8000) | int }}
    base_path: {{ env.BASE_PATH | default("/api") }}

Environment variables are available via env.VAR_NAME in templates. Use Jinja2 filters like default(), int(), bool() for type conversion. hexswitch init

Creates hex-config.yaml with example configuration

hexswitch init --force # Overwrite existing file

**Validate configuration:**
```bash
hexswitch validate
# Validates hex-config.yaml (default)
hexswitch validate --config path/to/config.yaml

Run runtime (dry-run mode):

hexswitch run --dry-run
# Shows execution plan without starting runtime

Run runtime:

hexswitch run
# Starts the runtime with all enabled adapters

Global Options

• --log-level: Set logging level (DEBUG, INFO, WARNING, ERROR)
• --config: Path to configuration file (default: hex-config.yaml)

Example Workflow

# 1. Create example configuration
hexswitch init

# 2. Validate configuration
hexswitch validate

# 3. Preview execution plan
hexswitch run --dry-run

# 4. Run runtime
hexswitch run

Or run it as a Python module:

python -m hexswitch.app version
python -m hexswitch.app init
python -m hexswitch.app validate
python -m hexswitch.app run --dry-run

Project Structure

• src/hexswitch/ - Python package (core runtime, adapters, handlers)
• tests/ - Test suite (unit and integration tests)
• docs/ - Project documentation

Development

See CONTRIBUTING.md for development guidelines and workflow.

Docker

Build and test the Docker image:

# Build Docker image
docker build -t hexswitch:latest .

# Test Docker image
docker run --rm hexswitch:latest hexswitch version

For more details, see Development Guide.

Documentation

• Development Guide - Installation, testing, and Docker build instructions
• Architecture Overview - High-level architecture description
• Branch Protection Rules - GitHub branch protection guidelines
• Contributing Guidelines - How to contribute to the project