spoe-forge 0.0.1__tar.gz

spoe_forge-0.0.1/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.3
+Name: spoe-forge
+Version: 0.0.1
+Summary: A pure Python framework for building HAProxy SPOE agents
+Keywords: haproxy,spoe,spoa,spop
+Author: Mike O'Donnell
+Author-email: Mike O'Donnell <mike@devferret.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: pre-commit>=4.1.0 ; extra == 'dev'
+Requires-Dist: ruff==0.14.2 ; extra == 'dev'
+Requires-Dist: pytest==9.0.1 ; extra == 'test'
+Requires-Dist: pytest-asyncio==1.3.0 ; extra == 'test'
+Requires-Dist: coveralls==4.0.2 ; extra == 'test'
+Requires-Dist: coverage==7.13.0 ; extra == 'test'
+Requires-Dist: pytest-cov==7.0.0 ; extra == 'test'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/mwodonnell/spoe-forge
+Project-URL: Repository, https://github.com/mwodonnell/spoe-forge
+Provides-Extra: dev
+Provides-Extra: test
+Description-Content-Type: text/markdown
+
+# SPOE Forge
+
+A pure Python framework for building SPOE (Stream Processing Offload Engine) agents that communicate
+with HAProxy using the SPOA protocol.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![Coverage Status](https://coveralls.io/repos/github/mwodonnell/spoe-forge/badge.svg?branch=unit-tests)](https://coveralls.io/github/mwodonnell/spoe-forge?branch=unit-tests)
+
+## Overview
+
+SPOE Forge provides a clean, decorator-based API for creating agents that process HAProxy messages and return
+actions. Built with async/await throughout, 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()`
+- **Full SPOP protocol support** - Complete implementation of the SPOA protocol
+- **Health check support** - Built-in HAProxy health check handling
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install spoe-forge
+```
+
+## Quick Start
+
+### Basic Example
+
+```python
+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](https://www.haproxy.org/download/3.3/doc/SPOE.txt).
+
+## 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:**
+
+```bash
+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:**
+
+```bash
+# 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.
+
+## 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](LICENSE) file for details.
+
+## Contributing
+
+Any and all contributions welcome.
+
+## Support
+
+For issues and questions, please [file an issue on GitHub](https://github.com/mwodonnell/spoe-forge/issues).
+
+## 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](https://github.com/capflam) for responding to some questions about a
+few hiccups along the way.

spoe_forge-0.0.1/README.md

@@ -0,0 +1,141 @@
+# SPOE Forge
+
+A pure Python framework for building SPOE (Stream Processing Offload Engine) agents that communicate
+with HAProxy using the SPOA protocol.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![Coverage Status](https://coveralls.io/repos/github/mwodonnell/spoe-forge/badge.svg?branch=unit-tests)](https://coveralls.io/github/mwodonnell/spoe-forge?branch=unit-tests)
+
+## Overview
+
+SPOE Forge provides a clean, decorator-based API for creating agents that process HAProxy messages and return
+actions. Built with async/await throughout, 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()`
+- **Full SPOP protocol support** - Complete implementation of the SPOA protocol
+- **Health check support** - Built-in HAProxy health check handling
+
+## Installation
+
+Install from PyPI:
+
+```bash
+pip install spoe-forge
+```
+
+## Quick Start
+
+### Basic Example
+
+```python
+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](https://www.haproxy.org/download/3.3/doc/SPOE.txt).
+
+## 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:**
+
+```bash
+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:**
+
+```bash
+# 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.
+
+## 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](LICENSE) file for details.
+
+## Contributing
+
+Any and all contributions welcome.
+
+## Support
+
+For issues and questions, please [file an issue on GitHub](https://github.com/mwodonnell/spoe-forge/issues).
+
+## 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](https://github.com/capflam) for responding to some questions about a
+few hiccups along the way.

spoe_forge-0.0.1/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["uv_build>=0.9.17,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "spoe_forge"
+module-root = ""
+
+[project]
+name = "spoe-forge"
+version = "0.0.1"
+description = "A pure Python framework for building HAProxy SPOE agents"
+authors = [
+    {name = "Mike O'Donnell", email = "mike@devferret.com"},
+]
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.12"
+keywords = ["haproxy", "spoe", "spoa", "spop"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+]
+
+[project.urls]
+Homepage = "https://github.com/mwodonnell/spoe-forge"
+Repository = "https://github.com/mwodonnell/spoe-forge"
+
+[project.optional-dependencies]
+dev = [
+    "pre-commit>=4.1.0",
+    "ruff==0.14.2",
+]
+test = [
+    "pytest==9.0.1",
+    "pytest-asyncio==1.3.0",
+    "coveralls==4.0.2",
+    "coverage==7.13.0",
+    "pytest-cov==7.0.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = [
+    "--verbose",
+    "--cov=spoe_forge",
+    "--cov-report=term-missing",
+    "--cov-report=html"
+]

spoe_forge-0.0.1/spoe_forge/__init__.py

@@ -0,0 +1,15 @@
+"""SPOE Forge - A Python framework for building HAProxy SPOA agents."""
+
+from spoe_forge.spoe_forge import SpoeForge
+from spoe_forge.spop.spop_types import SetVarAction, UnsetVarAction, Action
+from spoe_forge.spop.constants import ActionScope
+from spoe_forge.agent.context import AgentContext
+
+__all__ = [
+    "SpoeForge",
+    "AgentContext",
+    "Action",
+    "ActionScope",
+    "SetVarAction",
+    "UnsetVarAction",
+]

spoe_forge-0.0.1/spoe_forge/agent/context.py

@@ -0,0 +1,53 @@
+import logging
+
+from spoe_forge.spop.spop_types import SpoaDataType
+
+logger = logging.getLogger(__name__)
+
+
+class AgentContext:
+    """
+    Context object passed to message handlers containing message data.
+
+    Provides access to message name and arguments from HAProxy NOTIFY frames.
+    """
+
+    def __init__(self, message: str, args: dict[str, SpoaDataType]):
+        """
+        Create a new agent context.
+
+        :param str message: Message name from NOTIFY frame
+        :param dict[str, SpoaDataType] args: Message arguments
+        """
+        self._message = message
+        self._args = args
+
+    def get_arg(self, arg: str, default: SpoaDataType = None) -> SpoaDataType:
+        """
+        Retrieve a message argument by name.
+
+        :param str arg: Argument name to retrieve
+        :param default: Default value to return if argument is not present.
+        :return: Argument value, or None if not found
+        """
+        try:
+            return self._args[arg]
+        except KeyError:
+            return default
+
+    def get_args(self) -> dict[str, SpoaDataType]:
+        """
+        Retrieve all message arguments.
+
+        :return: Dictionary mapping argument names to values
+        """
+        return self._args
+
+    def has_arg(self, arg: str) -> bool:
+        """
+        Check if an argument exists in the message.
+
+        :param str arg: Argument name to check
+        :return: True if argument exists, False otherwise
+        """
+        return arg in self._args

spoe_forge-0.0.1/spoe_forge/agent/exceptions.py

@@ -0,0 +1,7 @@
+from spoe_forge.exception import SpoeForgeError
+
+
+class SpoeAgentError(SpoeForgeError):
+    """Exception raised when agent message processing fails."""
+
+    pass

spoe_forge-0.0.1/spoe_forge/agent/registry.py

@@ -0,0 +1,67 @@
+import asyncio
+import logging
+from typing import Callable
+
+from spoe_forge.agent.context import AgentContext
+from spoe_forge.agent.exceptions import SpoeAgentError
+from spoe_forge.spop.spop_types import SpoaDataType, Action
+
+logger = logging.getLogger(__name__)
+
+MessageHandlerFunc = Callable[[AgentContext], list[Action]]
+
+
+class AgentRegistry:
+    """
+    Internal registry mapping message names to handler functions.
+
+    Note: Users don't interact with this directly - it's used by the Agent class.
+    """
+
+    def __init__(self):
+        """Initialize a new agent registry."""
+        self._handlers: dict[str, MessageHandlerFunc] = {}
+        self._validation_cache: dict[str, bool] = {}
+
+    def register(self, message_name: str, handler: MessageHandlerFunc) -> None:
+        """
+        Register a handler for a message type.
+
+        :param str message_name: Message name to handle
+        :param MessageHandlerFunc handler: User-defined handler function
+        """
+        if message_name in self._handlers:
+            logger.warning(f"Overwriting existing handler for message '{message_name}'")
+
+        self._handlers[message_name] = handler
+        logger.debug(f"Registered handler for message '{message_name}'")
+
+    async def handle_message(
+        self, message: str, args: dict[str, SpoaDataType]
+    ) -> list[Action]:
+        """
+        Route a message to its registered handler.
+
+        Wraps synchronous handlers with asyncio.to_thread for async compatibility.
+
+        :param str message: Message name to handle
+        :param dict[str, SpoaDataType] args: Message arguments
+        :return: List of actions from handler (empty if no handler registered)
+        :raises SpoeAgentError: If handler raises an exception
+        """
+        handler = self._handlers.get(message)
+
+        if handler is None:
+            logger.warning(f"No handler registered for message '{message}'")
+            return []
+
+        ctx = AgentContext(message, args)
+        try:
+            return await asyncio.to_thread(handler, ctx)
+        except Exception as e:
+            logger.error(
+                f"Error in handler for message '{message}': {e}", exc_info=True
+            )
+            # Convert to our own error - will be caught in our own handlers to
+            # cause a graceful kill of the connection
+            raise SpoeAgentError(e)

spoe_forge-0.0.1/spoe_forge/exception.py

@@ -0,0 +1,4 @@
+class SpoeForgeError(Exception):
+    """Base exception class for all SPOE Forge errors."""
+
+    pass

spoe_forge-0.0.1/spoe_forge/log.py

@@ -0,0 +1,60 @@
+import logging
+import sys
+
+
+_default_handler = logging.StreamHandler(sys.stderr)
+_default_handler.setFormatter(
+    logging.Formatter("%(levelname)s | %(asctime)s | %(name)s | %(message)s")
+)
+
+
+def _has_level_handler(logger: logging.Logger) -> bool:
+    """
+    Check if there is a handler in the logging chain that will handle the
+    given logger's effective level.
+
+    This traverses the logger hierarchy to check if any parent logger
+    has a handler configured. Based on Flask's implementation.
+
+    :param logger: Logger to check
+    :return: True if a handler exists in the chain, False otherwise
+    """
+    level = logger.getEffectiveLevel()
+    current = logger
+
+    while current:
+        if any(handler.level <= level for handler in current.handlers):
+            return True
+
+        if not current.propagate:
+            break
+
+        current = current.parent
+
+    return False
+
+
+def create_logger(debug: bool = False) -> logging.Logger:
+    """
+    Get the SPOE Forge logger and configure it if needed.
+
+    This follows Flask's pattern:
+    - Uses 'spoe_forge' as the logger name
+    - Only adds default handler if no handler exists in the hierarchy
+    - Respects existing logging configuration
+
+    Internal function - called by spoe_forge.py at import time.
+
+    :return: Configured logger instance
+    """
+    logger = logging.getLogger("spoe_forge")
+
+    # Only add handler if none exists in the hierarchy
+    if not _has_level_handler(logger):
+        logger.addHandler(_default_handler)
+
+    # Set default level if not already set
+    if not logger.level:
+        logger.setLevel(logging.DEBUG if debug else logging.INFO)
+
+    return logger