Download the PHP package rocketman/spoa-php without Composer

spoa-php

A lightweight PHP framework for building HAProxy Stream Processing Offload Agent (SPOA) services

This library implements the SPOE protocol and allows PHP applications to receive messages from HAProxy, process request or session metadata, and return variables back to HAProxy for use in ACLs and routing decisions.

Features

• Native SPOE protocol implementation
• Event-driven, asynchronous I/O using ReactPHP
• Simple handler-based programming model
• Support for all HAProxy variable scopes
• Minimal runtime dependencies
• PHPUnit and PHPStan coverage

Requirements

• PHP 8.2 or later
• A running HAProxy instance with SPOE enabled

Installation

Install via Composer:

Dependencies

Runtime

• react/socket

Development

• phpunit/phpunit
• phpstan/phpstan
• react/event-loop

Core Concepts

The Connection class

The central abstraction in this framework is SPOA\Server\Connection.

Each incoming SPOE connection from HAProxy is represented by a Connection instance. Applications register message handlers on the connection and return variables (or Promises that resolve to variables) to HAProxy in response.

The framework handles:

• SPOE handshake and negotiation
• Message decoding
• Frame fragmentation
• Action encoding and responses

Your application code only needs to define handlers.

Registering message handlers

Handlers are registered by message name:

• Message Name: The event name (e.g., get-ip-reputation) must match the spoe-message identifier in your HAProxy configuration.

• Arguments ($args): An associative array of SPOA\Protocol\Arg object instances.

  • Named Arguments: Accessed via their name defined in HAProxy (e.g., $args['client_ip']).

  • Nameless Arguments: Accessed via the key arg(n), where n is the zero-based position (e.g., $args['arg(0)']).

  • Ordinal Access: As the array maintains the order defined in HAProxy, you can retreive any argument by its position regardless of its name (e.g., $fourthArg = $args[array_keys($args)[3]]).

Returning variables to HAProxy

Handlers return an associative array of variables to set or unset.

Alternatively, a handler may return a React\Promise\PromiseInterface that resolves to the associative array. This allows handlers to perform asynchronous operations before returning data to HAProxy.

Variable scopes

Variable names may be prefixed with a scope:

If no prefix is provided, the variable defaults to process scope.

Specifying null as a value will unset the variable. To set a variable to null, use Arg::null().

Getting Started

Below is a minimal SPOA agent implemented using this library. The example is intentionally procedural to focus on the framework’s programming model.

Minimal PHP agent

This example:

• Listens on a TCP socket for SPOE connections from HAProxy
• Registers a handler for a single SPOE message
• Returns a session-scoped variable to HAProxy

The application runs inside a standard ReactPHP event loop.

HAProxy Configuration

SPOE configuration (spoe-test.cfg)

HAProxy configuration excerpt

This configuration:

• Sends the client source IP to the SPOA agent
• Receives variables set by the agent
• Uses those variables in standard HAProxy ACL logic

Real-world example

A complete, working SPOA agent built using this library can be found in the Zookeeper Online music database and charting application.

In particular, see:

• SpoaTurnstile.php

This example shows how the library can be embedded into a larger application, including integration with an existing ReactPHP event loop and non-trivial decision logic.

Testing

Run the test suite:

Static analysis:

Both are executed automatically via GitHub Actions on push.

License

MIT License. See LICENSE for details.