Metadata-Version: 2.4
Name: flaxon-plusplus
Version: 0.2.0
Summary: HTTP sidecar for Flaxon applications
Author-email: Aldane Hutchinson <aldanehutchinson5@gmail.com>
Maintainer-email: ALdane Hutchinson <aldanehutchinson5@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/aldanedev-create/FlaxonPlusplus
Project-URL: Repository, https://github.com/aldanedev-create/FlaxonPlusplus.git
Project-URL: Documentation, https://github.com/aldanedev-create/FlaxonPlusplus/tree/main/docs
Project-URL: Issues, https://github.com/aldanedev-create/FlaxonPlusplus/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Go
Classifier: Framework :: AsyncIO
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flaxon<0.2.0,>=0.1.9
Requires-Dist: msgpack>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Provides-Extra: demo
Requires-Dist: uvicorn>=0.22.0; extra == "demo"
Dynamic: license-file

# Flaxon++


 <p align="center">
  <img src="https://raw.githubusercontent.com/aldanedev-create/Flaxon-Backend-Framework/main/assets/flaxon.png" alt="flaxon Logo"
   width="200"/>
</p>


  
  <p align="center">
  <a href="https://pypi.org/project/flaxon/"><img src="https://img.shields.io/pypi/v/flaxon.svg" alt="PyPI version"></a>
  <a href="https://github.com/aldanedev-create/Flaxon-Backend-Framework/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
  <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/badge/code%20style-ruff-000000.svg" alt="Code style: ruff"></a>
</p>

Flaxon++ is a Go HTTP sidecar for [Flaxon](https://pypi.org/project/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](https://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.

```bash
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.

```bash
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`:

```python
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](https://github.com/aldanedev-create/FlaxonPlusplus/tree/main/examples/amazon_clone).

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

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

Build the sidecar:

```bash
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.

```python
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](https://github.com/aldanedev-create/FlaxonPlusplus/blob/main/docs/production.md).

## 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](examples/amazon_clone).
It demonstrates catalog search, carts, and checkout while loading this plugin
in editable-install development mode.

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

See its [usage guide](examples/amazon_clone/README.md) 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](https://github.com/aldanedev-create/FlaxonPlusplus/blob/main/docs/production.md)
for the supported platform, hardened configuration, release gate, and
operational checklist.

## Development and verification

```bash
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](LICENSE).
