SPOE Forge

A pure Python framework for building SPOE (Stream Processing Offload Engine) agents that communicate with HAProxy using the SPOA protocol.

Overview

SPOE Forge provides a clean, decorator-based API for creating agents that process HAProxy messages and return actions. Built on an async I/O core with synchronous protocol parsing, it's designed for high-performance production environments. Or at least as performant as python will allow.

Why SPOE Forge?

Originally created to power a Google OAuth2 authentication backend for HAProxy, it became clear the project could be converted to an abstracted framework. I noticed during the development of this project that there was a lack of well-maintained, easily understood implementations of the SPOA protocol in python.

Key Features

• Simple decorator-based API - Register message handlers with @agent.message()
• Sync and async handlers - Plain functions run in a worker thread; async def handlers run on the event loop
• Embeddable - Blocking agent.run(), or await agent.serve() inside an existing event loop; both accept an ssl context for TLS to HAProxy
• Full SPOP protocol support - Complete implementation of the SPOA protocol
• Concurrent pipelining - When HAProxy negotiates the pipelining capability, NOTIFY frames are processed concurrently (bounded by max_concurrent_frames, default 100) with ACKs sent as handlers complete
• Health check support - Built-in HAProxy health check handling

Installation

Install from PyPI:

pip install spoe-forge

Quick Start

Basic Example

from spoe_forge import (
    SpoeForge,
    AgentContext,
    SetVarAction,
    ActionScope
)

# Create an agent
agent = SpoeForge(name="my-agent", debug=False)

# Register a message handler
@agent.message("check-request")
def handle_request(ctx: AgentContext) -> list[SetVarAction]:
    """Process incoming request and set HAProxy variables"""

    # Get message arguments from HAProxy
    client_ip = ctx.get_arg("client_ip")
    request_path = ctx.get_arg("path")

    # Your business logic here
    is_allowed = check_access(client_ip, request_path)

    # Return actions to set HAProxy variables
    return [
        SetVarAction(
            scope=ActionScope.TRANSACTION,
            name="access_allowed",
            value=is_allowed
        )
    ]

# Start the server
if __name__ == "__main__":
    agent.run(host="0.0.0.0", port=12345)

HAProxy Configuration

SPOE Forge works with HAProxy's SPOE configuration. For details on configuring HAProxy to communicate with your agent, see the official HAProxy SPOE documentation.

Local Development

Running with Docker

A complete local development environment is provided using Docker Compose, including a sample SPOE agent, HAProxy, and a test backend service.

Quick start:

cd docker
docker compose up --build

This starts three services:

• SPOA Agent (spoa) - Sample SPOE Forge agent running on port 8500
• Whoami (whoami) - Simple backend service for testing
• HAProxy (haproxy) - Configured to communicate with the WhoAmI example BE Service, the SPOA agent, and is listening on port 8080

Test the setup:

# Open logs
docker compose logs

# Visit the dev url in your browser
http://localhost:8080

Check both the docker logs and the X-Test-Arg header displayed on the WhoAmI page.

Make any updates to the HAProxy configs or the sample_server.py files in ./docker/ to support your testing.

Health Checks

SPOE Forge includes a built-in CLI healthcheck utility for monitoring agent health in containerized environments.

Basic usage:

# Basic usage
spoe-forge healthcheck --host 127.0.0.1 --port 8500

# Use default host and port
spoe-forge healthcheck


# Quiet mode, only exit codes
spoe-forge healthcheck --quiet

# Help info
spoe-forge --help
spoe-forge healthcheck --help

Docker Integration:

The provided docker-compose.yml includes a pre-configured healthcheck for the sample SPOE agent as a reference:

healthcheck:
  test: ["CMD", "uv", "run", "spoe-forge", "healthcheck", "--host", "127.0.0.1", "--port", "8500", "--quiet"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 10s

View healthcheck status:

docker compose ps     # Shows health status
docker inspect spoa   # Detailed healthcheck info

Exit codes:

• 0: Health check passed
• 1: Health check failed
• 2: Invalid usage

Roadmap

Future enhancements under consideration with no timeline guaranteed:

• Middleware support
• Much more extended documentation and examples

License

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

Contributing

Any and all contributions welcome.

Support

For issues and questions, please file an issue on GitHub.

Acknowledgments

Built to solve real-world production needs for HAProxy SPOA agents. Special thanks to the HAProxy team for excellent documentation of the SPOE protocol.

Extra shoutout to Christopher Faulet for responding to some questions about a few hiccups along the way.