Flaxon++

Flaxon++ is a Go HTTP sidecar for Flaxon. The sidecar accepts HTTP traffic and exchanges framed MessagePack messages with the unchanged Flaxon application over a Unix domain socket (UDS).

Source code and full documentation: github.com/aldanedev-create/FlaxonPlusplus

Status: the supported production scope is HTTP request forwarding on Linux hosts with Unix-domain-socket support. HTTP support is covered by automated protocol and ASGI tests. OS limits, and benchmark results; this project makes no unmeasured “millions of users” guarantee.

Install

Requirements: Python 3.9+, Go 1.21+, and a host that supports Unix domain sockets. On Windows, verify UDS support in your target environment before using sidecar mode.

python -m pip install flaxon-plusplus

Build your first app

Start in direct development mode. Your Flaxon routes stay ordinary routes; the plugin is loaded at application startup and exposes its health endpoints.

mkdir my-store && cd my-store
python -m venv .venv
# Linux/macOS: source .venv/bin/activate
# Windows PowerShell: .\.venv\Scripts\Activate.ps1
python -m pip install flaxon flaxon-plusplus uvicorn

Create app.py:

from flaxon import Flaxon
from flaxon_plusplus import FlaxonPlusPlusConfig, FlaxonPlusPlusPlugin

app = Flaxon("my-store")
plugin = FlaxonPlusPlusPlugin(FlaxonPlusPlusConfig(dev_mode=True))

@app.on_startup
async def load_flaxonplusplus():
    await app.plugins.load_plugin(plugin)

@app.get("/")
async def home():
    return {"message": "My Flaxon++ app is running"}

@app.get("/products")
async def products():
    return [{"id": 1, "name": "Keyboard", "price": 89.99}]

Run it with python -m flaxon run app:app --host 127.0.0.1 --port 8000. Open http://127.0.0.1:8000/, then check http://127.0.0.1:8000/_flaxonpp/health to confirm the plugin loaded. For a complete storefront with Jinax templates, see the Amazon-style example on GitHub.

For development from this checkout, use an editable install so source changes are picked up immediately:

python -m pip install -e ".[test,demo]"

Build the sidecar:

cd go
go build -o bin/flaxonpp ./cmd/flaxonpp

On Windows, use bin/flaxonpp.exe instead.

Use with an existing app

Keep your normal route handlers. Load the plugin during Flaxon startup; the plugin then schedules its own sidecar startup when dev_mode is false.

from flaxon import Flaxon
from flaxon_plusplus import FlaxonPlusPlusConfig, FlaxonPlusPlusPlugin

app = Flaxon("store")
plugin = FlaxonPlusPlusPlugin(
    FlaxonPlusPlusConfig(port=8080, dev_mode=True)  # start in direct mode
)

@app.on_startup
async def load_plugin():
    await app.plugins.load_plugin(plugin)

@app.get("/products")
async def products():
    return [{"id": 1, "name": "Keyboard"}]

For sidecar mode, build the Go binary, set dev_mode=False, and configure an absolute binary path, unique uds_path, and port. The app continues to serve ordinary Flaxon routes; send public traffic to the sidecar port.

For the production Linux/UDS configuration, binary build steps, deployment checklist, and release gate, read the production guide on GitHub.

Configuration

FlaxonPlusPlusConfig accepts constructor values and FLAXONPP_ environment variables. Important settings:

Setting	Default	Meaning
port / FLAXONPP_PORT	8080	Sidecar HTTP port
host / FLAXONPP_HOST	0.0.0.0	Sidecar bind address
uds_path / FLAXONPP_UDS_PATH	/tmp/flaxonpp.sock	IPC socket path
ipc_connections	4	UDS worker connections
worker_pool_size	CPU count	Capped to ipc_connections
dev_mode	False	Direct Flaxon serving; no sidecar process
enable_websockets	False	Experimental; do not enable in production

Plugin diagnostics are registered at /_flaxonpp/health, /_flaxonpp/ready, /_flaxonpp/live, and (when enabled) /_flaxonpp/metrics.

Amazon-style demo

A runnable e-commerce API lives in examples/amazon_clone. It demonstrates catalog search, carts, and checkout while loading this plugin in editable-install development mode.

python -m pip install -e ".[demo]"
python -m flaxon run examples.amazon_clone.app:app --reload

See its usage guide for requests and the sidecar-mode switch.

Production deployment

The PyPI package is the Python plugin. Build the Go sidecar from the matching source release and deploy it alongside your application. See the production guide for the supported platform, hardened configuration, release gate, and operational checklist.

Development and verification

python -m pytest -q
cd go && go test ./...

The Python package uses a compact frame protocol:

4 byte total frame length | 1 byte frame type | 8 byte connection ID | MessagePack map

Keep the Python and Go frame encoders in lockstep. Changes require a protocol round-trip test before release.

Production checklist

• Use a process supervisor and one unique UDS path per app instance.
• Bind to a private interface or place a TLS-capable reverse proxy in front.
• Set connection/file-descriptor limits and benchmark the exact workload.
• Add observability, request limits, database-backed state, authentication, and payment-provider controls in the application.
• Do not place sensitive secrets in plugin configuration or log output.

License

MIT. See LICENSE.