ufaflow 1.0.6__tar.gz

ufaflow-1.0.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 halif
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ufaflow-1.0.6/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: ufaflow
+Version: 1.0.6
+Summary: UfaFlow
+Author: halif
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Dynamic: author
+Dynamic: license-file
+
+<h1 align="center">UfaFlow</h1>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Version-1.0.6-7c3aed?style=for-the-badge" alt="version" />
+  <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="license" />
+  <img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="python" />
+  <img src="https://img.shields.io/badge/Release-1.0.6-10b981?style=for-the-badge" alt="release" />
+  <img src="https://img.shields.io/badge/FastAPI-✓-009688?style=for-the-badge&logo=fastapi&logoColor=white" alt="fastapi" />
+</p>
+
+<p align="center">
+  <a href="https://github.com/halif/ufaflow/actions">
+    <img src="https://img.shields.io/github/actions/workflow/status/halif/ufaflow/ci.yml?branch=main&label=CI&style=flat-square" alt="CI status" />
+  </a>
+  <img src="https://img.shields.io/badge/security-audits-passing-16a34a?style=flat-square" alt="security audits" />
+  <img src="https://img.shields.io/badge/status-stable-22c55e?style=flat-square" alt="status" />
+  <img src="https://img.shields.io/github/stars/halif/ufaflow?style=flat-square&logo=github&label=stars" alt="stars" />
+  <img src="https://img.shields.io/github/issues/halif/ufaflow?style=flat-square&logo=github&label=issues" alt="issues" />
+  <img src="https://img.shields.io/github/last-commit/halif/ufaflow?style=flat-square&logo=github&label=last%20commit" alt="last commit" />
+</p>
+
+## Overview
+
+UfaFlow is a lightweight asynchronous worker manager and load balancer for Python services. It distributes traffic across worker processes with predictable lifecycle control, simple configuration, and async-first execution.
+
+The project is designed for teams that need:
+- a simple worker runtime
+- process-level isolation
+- async-first execution
+- predictable startup and shutdown behavior
+- easy deployment in development and production-like environments
+
+## Why UfaFlow
+
+Many applications need more than a single process, but do not require the complexity of a full orchestration platform. UfaFlow acts as a lightweight execution layer that helps you:
+- manage multiple workers with a single runtime
+- balance traffic or task distribution across processes
+- keep lifecycle management explicit and controllable
+- reduce operational overhead for small-to-medium service deployments
+
+## Key Features
+
+- Async-first worker orchestration
+- Configurable worker pool and process management
+- Lightweight request balancing across workers
+- Support for FastAPI and Python service integration
+- YAML-based configuration
+- Clean startup and shutdown lifecycle behavior
+- Simple deployment model for local and cloud environments
+
+## Installation
+
+```bash
+pip install ufaflow
+```
+
+## Quick start
+
+Create a YAML config file:
+
+```yaml
+health_interval: 5
+health_timeout: 2
+frontends:
+  - listen_host: "0.0.0.0"
+    listen_port: 8080
+    algorithm: round_robin
+    backends:
+      - host: "127.0.0.1"
+        port: 8001
+      - host: "127.0.0.1"
+        port: 8002
+```
+
+Run the load balancer:
+
+```bash
+python -m ufaflow.cli config.yaml
+```
+
+To run with multiple worker processes:
+
+```bash
+python -m ufaflow.cli config.yaml --workers 4
+```
+
+## License
+
+MIT

ufaflow-1.0.6/README.md

@@ -0,0 +1,89 @@
+<h1 align="center">UfaFlow</h1>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Version-1.0.6-7c3aed?style=for-the-badge" alt="version" />
+  <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="license" />
+  <img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="python" />
+  <img src="https://img.shields.io/badge/Release-1.0.6-10b981?style=for-the-badge" alt="release" />
+  <img src="https://img.shields.io/badge/FastAPI-✓-009688?style=for-the-badge&logo=fastapi&logoColor=white" alt="fastapi" />
+</p>
+
+<p align="center">
+  <a href="https://github.com/halif/ufaflow/actions">
+    <img src="https://img.shields.io/github/actions/workflow/status/halif/ufaflow/ci.yml?branch=main&label=CI&style=flat-square" alt="CI status" />
+  </a>
+  <img src="https://img.shields.io/badge/security-audits-passing-16a34a?style=flat-square" alt="security audits" />
+  <img src="https://img.shields.io/badge/status-stable-22c55e?style=flat-square" alt="status" />
+  <img src="https://img.shields.io/github/stars/halif/ufaflow?style=flat-square&logo=github&label=stars" alt="stars" />
+  <img src="https://img.shields.io/github/issues/halif/ufaflow?style=flat-square&logo=github&label=issues" alt="issues" />
+  <img src="https://img.shields.io/github/last-commit/halif/ufaflow?style=flat-square&logo=github&label=last%20commit" alt="last commit" />
+</p>
+
+## Overview
+
+UfaFlow is a lightweight asynchronous worker manager and load balancer for Python services. It distributes traffic across worker processes with predictable lifecycle control, simple configuration, and async-first execution.
+
+The project is designed for teams that need:
+- a simple worker runtime
+- process-level isolation
+- async-first execution
+- predictable startup and shutdown behavior
+- easy deployment in development and production-like environments
+
+## Why UfaFlow
+
+Many applications need more than a single process, but do not require the complexity of a full orchestration platform. UfaFlow acts as a lightweight execution layer that helps you:
+- manage multiple workers with a single runtime
+- balance traffic or task distribution across processes
+- keep lifecycle management explicit and controllable
+- reduce operational overhead for small-to-medium service deployments
+
+## Key Features
+
+- Async-first worker orchestration
+- Configurable worker pool and process management
+- Lightweight request balancing across workers
+- Support for FastAPI and Python service integration
+- YAML-based configuration
+- Clean startup and shutdown lifecycle behavior
+- Simple deployment model for local and cloud environments
+
+## Installation
+
+```bash
+pip install ufaflow
+```
+
+## Quick start
+
+Create a YAML config file:
+
+```yaml
+health_interval: 5
+health_timeout: 2
+frontends:
+  - listen_host: "0.0.0.0"
+    listen_port: 8080
+    algorithm: round_robin
+    backends:
+      - host: "127.0.0.1"
+        port: 8001
+      - host: "127.0.0.1"
+        port: 8002
+```
+
+Run the load balancer:
+
+```bash
+python -m ufaflow.cli config.yaml
+```
+
+To run with multiple worker processes:
+
+```bash
+python -m ufaflow.cli config.yaml --workers 4
+```
+
+## License
+
+MIT

ufaflow-1.0.6/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ufaflow"
+version = "1.0.6"
+description = "UfaFlow"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "PyYAML>=6.0",
+]
+
+[tool.setuptools]
+packages = ["ufaflow"]
+
+[tool.black]
+line-length = 88
+target-version = ["py311"]
+
+[tool.isort]
+profile = "black"
+line_length = 88
+
+[tool.ruff]
+line-length = 88
+fix = true
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "C90"]
+ignore = ["C901"]

ufaflow-1.0.6/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ufaflow-1.0.6/setup.py

@@ -0,0 +1,15 @@
+from setuptools import find_packages, setup
+
+setup(
+    name="ufaflow",
+    version="0.1.0",
+    description="UfaFlow — lightweight L4/L7 load balancer (MVP)",
+    packages=find_packages(),
+    install_requires=[
+        "PyYAML",
+        # optional: uvloop improves async performance if installed
+    ],
+    entry_points={"console_scripts": ["ufaflow=ufaflow.cli:main"]},
+    author="halif",
+    license="MIT",
+)

ufaflow-1.0.6/tests/test_backend_pool.py

@@ -0,0 +1,19 @@
+from ufaflow.server import Backend, BackendPool
+
+
+def test_round_robin_simple():
+    b1 = Backend("127.0.0.1", 8001)
+    b2 = Backend("127.0.0.1", 8002)
+    pool = BackendPool([b1, b2], algorithm="round_robin")
+    seq = [pool.choose().name for _ in range(4)]
+    assert seq[0] != seq[1]
+    assert len(set(seq)) == 2
+
+
+def test_least_conn():
+    b1 = Backend("127.0.0.1", 8001)
+    b2 = Backend("127.0.0.1", 8002)
+    b2.current_conns = 5
+    pool = BackendPool([b1, b2], algorithm="least_conn")
+    chosen = pool.choose()
+    assert chosen is b1

ufaflow-1.0.6/tests/test_cli_smoke.py

@@ -0,0 +1,45 @@
+from pathlib import Path
+import subprocess
+import sys
+
+from ufaflow import __version__
+from ufaflow.cli import validate_config
+
+
+def test_package_version_is_exposed():
+    assert __version__
+    assert isinstance(__version__, str)
+    assert __version__.count(".") >= 1
+
+
+def test_validate_config_accepts_valid_config():
+    config = {
+        "frontends": [
+            {
+                "listen_host": "0.0.0.0",
+                "listen_port": 8080,
+                "backends": [
+                    {"host": "127.0.0.1", "port": 8001},
+                    {"host": "127.0.0.1", "port": 8002},
+                ],
+            }
+        ]
+    }
+
+    validated = validate_config(config)
+
+    assert validated["frontends"][0]["listen_port"] == 8080
+    assert len(validated["frontends"][0]["backends"]) == 2
+
+
+def test_cli_help_runs_successfully():
+    result = subprocess.run(
+        [sys.executable, "-m", "ufaflow.cli", "--help"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+
+    assert result.returncode == 0
+    assert "usage:" in result.stdout.lower()
+    assert "UfaFlow" in result.stdout

ufaflow-1.0.6/ufaflow/__init__.py

@@ -0,0 +1,5 @@
+"""
+UfaFlow package
+"""
+
+__version__ = "1.0.5"

ufaflow-1.0.6/ufaflow/cli.py

@@ -0,0 +1,395 @@
+#!/usr/bin/env python3
+"""
+CLI / process manager for UfaFlow
+
+Supports:
+- single-process run: python -m ufaflow.cli config.yaml
+- worker-mode: python -m ufaflow.cli config.yaml --workers N
+
+Manager will spawn N workers; each worker binds sockets with SO_REUSEPORT
+(if available). SIGHUP on manager -> restart workers (reload config).
+SIGTERM/SIGINT -> graceful shutdown.
+"""
+
+import argparse
+import logging
+import multiprocessing as mp
+import os
+import signal
+import socket
+import sys
+import time
+from typing import Any, List
+
+import yaml
+
+# try to use uvloop in workers
+try:
+    import uvloop  # type: ignore
+except Exception:
+    uvloop = None
+
+from . import server as server_mod
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s %(levelname)s %(message)s",
+)
+
+
+def validate_backend(
+    backend: Any,
+    frontend_index: int,
+    backend_index: int,
+) -> None:
+    if not isinstance(backend, dict):
+        raise ValueError(
+            f"Invalid frontend[{frontend_index}] backend[{backend_index}]: "
+            "expected a mapping with host and port."
+        )
+
+    if "host" not in backend or "port" not in backend:
+        raise ValueError(
+            f"Invalid frontend[{frontend_index}] backend[{backend_index}]: "
+            "must include 'host' and 'port'."
+        )
+
+    if not isinstance(backend["host"], str) or not backend["host"].strip():
+        raise ValueError(
+            f"Invalid frontend[{frontend_index}] backend[{backend_index}]: "
+            "'host' must be a non-empty string."
+        )
+
+    port = backend["port"]
+    if not isinstance(port, int) or port <= 0 or port > 65535:
+        raise ValueError(
+            f"Invalid frontend[{frontend_index}] backend[{backend_index}]: "
+            "'port' must be an integer between 1 and 65535."
+        )
+
+
+def validate_frontend(frontend: Any, index: int) -> None:
+    if not isinstance(frontend, dict):
+        raise ValueError(f"Invalid frontend[{index}]: expected a mapping.")
+
+    if "listen_port" not in frontend:
+        raise ValueError(f"Invalid frontend[{index}]: missing 'listen_port'.")
+
+    port = frontend["listen_port"]
+    if not isinstance(port, int) or port <= 0 or port > 65535:
+        raise ValueError(
+            f"Invalid frontend[{index}]: 'listen_port' must be an integer "
+            "between 1 and 65535."
+        )
+
+    backends = frontend.get("backends", [])
+    if not isinstance(backends, list) or not backends:
+        raise ValueError(
+            f"Invalid frontend[{index}]: 'backends' must be a non-empty list."
+        )
+
+    for backend_index, backend in enumerate(backends):
+        validate_backend(backend, index, backend_index)
+
+
+def validate_config(config: Any) -> dict:
+    if not isinstance(config, dict):
+        raise ValueError("Configuration must be a mapping/object.")
+
+    frontends = config.get("frontends")
+    if not isinstance(frontends, list) or not frontends:
+        raise ValueError("Configuration error: 'frontends' must be a non-empty list.")
+
+    for index, frontend in enumerate(frontends):
+        validate_frontend(frontend, index)
+
+    return config
+
+
+def load_config(path: str):
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            config = yaml.safe_load(f)
+    except FileNotFoundError as exc:
+        raise ValueError(f"Config file not found: {path}") from exc
+    except yaml.YAMLError as exc:
+        raise ValueError(f"Invalid YAML in config file '{path}': {exc}") from exc
+
+    return validate_config(config)
+
+
+def create_listen_sockets(frontends: list) -> List[socket.socket]:
+    socks = []
+    for fe in frontends:
+        host = fe.get("listen_host", "0.0.0.0")
+        port = fe["listen_port"]
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        # try to set SO_REUSEPORT; may raise AttributeError on some platforms
+        try:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEPORT, 1)
+            logging.info("Using SO_REUSEPORT on %s:%d", host, port)
+        except AttributeError:
+            logging.warning(
+                "SO_REUSEPORT not supported on this platform; multi-process "
+                "gain limited"
+            )
+        except OSError:
+            logging.warning(
+                "SO_REUSEPORT not available / permission denied; continuing "
+                "without it"
+            )
+        sock.bind((host, port))
+        sock.listen(1000)
+        sock.setblocking(False)
+        socks.append(sock)
+    return socks
+
+
+def worker_main(config_path: str):
+    # Worker process entrypoint
+    if uvloop:
+        asyncio_policy = uvloop.EventLoopPolicy()
+        import asyncio as _asyncio
+
+        _asyncio.set_event_loop_policy(asyncio_policy)
+
+    import asyncio
+
+    config = load_config(config_path)
+    frontends = config.get("frontends", [])
+
+    # In worker mode we create sockets independently (each worker must set
+    # SO_REUSEPORT before bind), but manager may also create sockets and
+    # pass FDs via environment variable.
+    fds_env = os.environ.get("UFAFLOW_LISTEN_FDS")
+    if fds_env:
+        fds = [int(x) for x in fds_env.split(",") if x.strip()]
+        socks = [socket.fromfd(fd, socket.AF_INET, socket.SOCK_STREAM) for fd in fds]
+        # set non-blocking
+        for s in socks:
+            s.setblocking(False)
+    else:
+        # fallback: each worker creates its own sockets (SO_REUSEPORT set by
+        # manager earlier)
+        socks = create_listen_sockets(frontends)
+
+    async def _run():
+        try:
+            await server_mod.run_worker_with_sockets(config, socks)
+        except Exception as ex:
+            logging.exception("Worker encountered exception: %s", ex)
+            raise
+
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+
+    # graceful shutdown handler
+    stop = False
+
+    def _on_term(signum, frame):
+        nonlocal stop
+        logging.info("Worker got signal %s, stopping...", signum)
+        stop = True
+        for task in asyncio.all_tasks(loop):
+            task.cancel()
+
+    signal.signal(signal.SIGINT, _on_term)
+    signal.signal(signal.SIGTERM, _on_term)
+
+    try:
+        loop.run_until_complete(_run())
+    except KeyboardInterrupt:
+        pass
+    finally:
+        loop.run_until_complete(loop.shutdown_asyncgens())
+        loop.close()
+        logging.info("Worker exiting")
+
+
+def run_manager(config_path: str, workers: int):  # noqa: C901
+    """
+    Manager: spawn `workers` worker processes. On SIGHUP restart workers
+    (reload config).
+    """
+    config = load_config(config_path)
+    frontends = config.get("frontends", [])
+    # Manager will set env UFAFLOW_LISTEN_FDS with fds of created sockets
+    # (so workers can inherit).
+    socks = create_listen_sockets(frontends)
+    fds = [s.fileno() for s in socks]
+    fds_str = ",".join(str(fd) for fd in fds)
+
+    # children: mapping pid -> Process
+    children = {}
+
+    def spawn_workers():
+        logging.info("Spawning %d workers...", workers)
+        for _ in range(workers):
+            env = os.environ.copy()
+            env["UFAFLOW_LISTEN_FDS"] = fds_str
+            p = mp.Process(
+                target=_worker_process_wrapper,
+                args=(config_path,),
+                env=env,
+            )
+            p.start()
+            children[p.pid] = p
+            logging.info("Spawned worker pid=%d", p.pid)
+
+    def stop_workers():
+        logging.info("Stopping workers...")
+        for pid, p in list(children.items()):
+            logging.info("Terminating worker pid=%d", pid)
+            p.terminate()
+        # join/ensure termination
+        for pid, p in list(children.items()):
+            p.join(timeout=5)
+            if p.is_alive():
+                logging.info("Killing worker pid=%d", pid)
+                p.kill()
+            children.pop(pid, None)
+
+    def restart_workers():
+        logging.info("Restarting workers (SIGHUP)...")
+        stop_workers()
+        spawn_workers()
+
+    # SIGHUP -> restart
+    def _on_sighup(signum, frame):
+        logging.info("Manager received SIGHUP")
+        restart_workers()
+
+    def _on_term(signum, frame):
+        logging.info("Manager received SIGTERM/SIGINT, shutting down")
+        stop_workers()
+        sys.exit(0)
+
+    signal.signal(signal.SIGHUP, _on_sighup)
+    signal.signal(signal.SIGINT, _on_term)
+    signal.signal(signal.SIGTERM, _on_term)
+
+    spawn_workers()
+    # Wait for children; respawn workers if they exit unexpectedly
+    try:
+        while True:
+            time.sleep(1)
+            # reap dead children and respawn
+            for pid, p in list(children.items()):
+                if not p.is_alive():
+                    logging.warning(
+                        "Worker pid=%d exited unexpectedly; restarting", pid
+                    )
+                    children.pop(pid, None)
+                    p.join()
+                    env = os.environ.copy()
+                    env["UFAFLOW_LISTEN_FDS"] = fds_str
+                    p2 = mp.Process(
+                        target=_worker_process_wrapper,
+                        args=(config_path,),
+                        env=env,
+                    )
+                    p2.start()
+                    children[p2.pid] = p2
+                    logging.info("Respawned worker pid=%d", p2.pid)
+    except KeyboardInterrupt:
+        logging.info("Manager got KeyboardInterrupt, stopping workers")
+        stop_workers()
+
+
+def _worker_process_wrapper(config_path: str):
+    # Runs in child process created by multiprocessing.Process. Child reads
+    # UFAFLOW_LISTEN_FDS from os.environ (safer across platforms).
+    worker_main(config_path)
+
+
+def run_single(config_path: str):  # noqa: C901
+    # single-process run (no manager)
+    if uvloop:
+        import asyncio as _asyncio
+
+        _asyncio.set_event_loop_policy(uvloop.EventLoopPolicy())
+    import asyncio
+
+    config = load_config(config_path)
+
+    async def _run():
+        servers, tasks = await server_mod.start_servers_from_config(config)
+        active_servers = []
+        # start servers normally (no external sockets)
+        for host, port, pool in servers:
+            srv = await asyncio.start_server(
+                lambda r, w, p=pool: server_mod.handle_client(r, w, p),
+                host=host,
+                port=port,
+            )
+            logging.info("Listening on %s:%d", host, port)
+            active_servers.append(srv)
+        try:
+            await asyncio.gather(
+                *[s.serve_forever() for s in active_servers],
+                *tasks,
+            )
+        except asyncio.CancelledError:
+            logging.info("Shutting down single-process server")
+        finally:
+            for s in active_servers:
+                s.close()
+                await s.wait_closed()
+            for t in tasks:
+                t.cancel()
+                try:
+                    await t
+                except Exception:
+                    pass
+
+    loop = asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+
+    def _on_term(signum, frame):
+        logging.info("Single-process received term, cancelling tasks")
+        for task in asyncio.all_tasks(loop):
+            task.cancel()
+
+    signal.signal(signal.SIGINT, _on_term)
+    signal.signal(signal.SIGTERM, _on_term)
+
+    try:
+        loop.run_until_complete(_run())
+    except KeyboardInterrupt:
+        pass
+    finally:
+        loop.run_until_complete(loop.shutdown_asyncgens())
+        loop.close()
+
+
+def main():
+    parser = argparse.ArgumentParser(description="UfaFlow load balancer")
+    parser.add_argument("config", help="Path to YAML config")
+    parser.add_argument(
+        "--workers",
+        "-w",
+        type=int,
+        default=1,
+        help="Number of worker processes (default 1)",
+    )
+    args = parser.parse_args()
+
+    if args.workers < 1:
+        parser.error("--workers must be greater than or equal to 1")
+
+    try:
+        if args.workers <= 1:
+            run_single(args.config)
+        else:
+            run_manager(args.config, args.workers)
+    except ValueError as exc:
+        print(f"Configuration error: {exc}", file=sys.stderr)
+        raise SystemExit(1) from exc
+    except FileNotFoundError as exc:
+        print(f"Configuration file not found: {exc.filename}", file=sys.stderr)
+        raise SystemExit(1) from exc
+
+
+if __name__ == "__main__":
+    main()

ufaflow-1.0.6/ufaflow/server.py

@@ -0,0 +1,260 @@
+import asyncio
+import logging
+import socket
+import time
+from dataclasses import dataclass
+from typing import List, Optional
+
+logging.getLogger().setLevel(logging.INFO)
+
+
+@dataclass
+class Backend:
+    host: str
+    port: int
+    weight: int = 1
+    name: Optional[str] = None
+    up: bool = True
+    current_conns: int = 0
+    last_checked: float = 0.0
+
+    def __post_init__(self):
+        if not self.name:
+            self.name = f"{self.host}:{self.port}"
+
+    def addr(self):
+        return (self.host, self.port)
+
+
+class BackendPool:
+    def __init__(self, backends: List[Backend], algorithm: str = "round_robin"):
+        self.backends = backends
+        self.algorithm = algorithm
+        self._rr_state = 0
+
+    def available(self) -> List[Backend]:
+        return [b for b in self.backends if b.up]
+
+    def choose(self, client_ip: Optional[str] = None) -> Optional[Backend]:
+        av = self.available()
+        if not av:
+            return None
+        if self.algorithm == "least_conn":
+            return min(av, key=lambda b: b.current_conns)
+        # simple weighted round-robin
+        choices = []
+        for b in av:
+            choices.extend([b] * max(1, b.weight))
+        self._rr_state = (self._rr_state + 1) % len(choices)
+        return choices[self._rr_state]
+
+
+async def relay_stream(
+    reader: asyncio.StreamReader,
+    writer: asyncio.StreamWriter,
+):
+    try:
+        while True:
+            data = await reader.read(64 * 1024)
+            if not data:
+                break
+            writer.write(data)
+            await writer.drain()
+    except (asyncio.CancelledError, ConnectionResetError, BrokenPipeError):
+        pass
+    finally:
+        try:
+            writer.close()
+            await writer.wait_closed()
+        except Exception:
+            pass
+
+
+async def handle_client(
+    client_reader: asyncio.StreamReader,
+    client_writer: asyncio.StreamWriter,
+    pool: BackendPool,
+    timeout: float = 10.0,
+):
+    peer = client_writer.get_extra_info("peername")
+    backend = pool.choose(client_ip=peer[0] if peer else None)
+    if not backend:
+        logging.warning("No available backend for connection from %s", peer)
+        try:
+            client_writer.close()
+            await client_writer.wait_closed()
+        except Exception:
+            pass
+        return
+
+    logging.info("Proxying %s -> %s", peer, backend.name)
+    backend.current_conns += 1
+    try:
+        try:
+            backend_reader, backend_writer = await asyncio.wait_for(
+                asyncio.open_connection(backend.host, backend.port),
+                timeout=timeout,
+            )
+        except Exception as e:
+            logging.warning("Failed to connect to backend %s: %s", backend.name, e)
+            backend.up = False
+            return
+
+        t1 = asyncio.create_task(relay_stream(client_reader, backend_writer))
+        t2 = asyncio.create_task(relay_stream(backend_reader, client_writer))
+        await asyncio.wait(
+            [t1, t2],
+            return_when=asyncio.FIRST_COMPLETED,
+        )
+        for t in (t1, t2):
+            if not t.done():
+                t.cancel()
+    finally:
+        backend.current_conns = max(0, backend.current_conns - 1)
+        try:
+            client_writer.close()
+            await client_writer.wait_closed()
+        except Exception:
+            pass
+
+
+async def tcp_health_check_periodic(
+    backends: List[Backend],
+    interval: int,
+    timeout: float,
+):
+    while True:
+        for b in backends:
+            try:
+                b.last_checked = time.time()
+                fut = asyncio.open_connection(b.host, b.port)
+                r, w = await asyncio.wait_for(fut, timeout=timeout)
+                try:
+                    w.close()
+                    await w.wait_closed()
+                except Exception:
+                    pass
+                if not b.up:
+                    logging.info("Backend %s is up", b.name)
+                b.up = True
+            except Exception:
+                if b.up:
+                    logging.warning("Backend %s is down", b.name)
+                b.up = False
+        await asyncio.sleep(interval)
+
+
+async def start_servers_from_config(config: dict):
+    frontends = config.get("frontends", [])
+    pools = []
+    tasks = []
+    for fe in frontends:
+        be_cfgs = fe.get("backends", [])
+        backends = [
+            Backend(
+                b["host"],
+                b["port"],
+                b.get("weight", 1),
+                name=b.get("name"),
+            )
+            for b in be_cfgs
+        ]
+        pool = BackendPool(
+            backends,
+            algorithm=fe.get("algorithm", "round_robin"),
+        )
+        pools.append((fe, pool))
+
+    all_backends = [b for _, p in pools for b in p.backends]
+    # healthcheck task
+    tasks.append(
+        asyncio.create_task(
+            tcp_health_check_periodic(
+                all_backends,
+                config.get("health_interval", 5),
+                config.get("health_timeout", 2),
+            )
+        )
+    )
+    # start frontends
+    servers = []
+    for fe, pool in pools:
+        host = fe.get("listen_host", "0.0.0.0")
+        port = fe["listen_port"]
+        # We'll create server sockets externally (in worker mode) and pass them
+        # into start_server via sock param.
+        # For single-process mode, use default start_server (no sock).
+        servers.append((host, port, pool))
+    return servers, tasks
+
+
+async def run_worker_with_sockets(config: dict, sockets: List[socket.socket]):
+    """
+    sockets: list of listening sockets (must correspond to config frontends order)
+    """
+    # set up uvloop already done by CLI
+    frontends = config.get("frontends", [])
+    pools = []
+    for fe in frontends:
+        be_cfgs = fe.get("backends", [])
+        backends = [
+            Backend(
+                b["host"],
+                b["port"],
+                b.get("weight", 1),
+                name=b.get("name"),
+            )
+            for b in be_cfgs
+        ]
+        pool = BackendPool(
+            backends,
+            algorithm=fe.get("algorithm", "round_robin"),
+        )
+        pools.append((fe, pool))
+
+    all_backends = [b for _, p in pools for b in p.backends]
+    tasks = []
+    tasks.append(
+        asyncio.create_task(
+            tcp_health_check_periodic(
+                all_backends,
+                config.get("health_interval", 5),
+                config.get("health_timeout", 2),
+            )
+        )
+    )
+
+    servers = []
+    # Create servers using provided sockets (SO_REUSEPORT case)
+    for (fe, pool), sock in zip(pools, sockets, strict=False):
+        server = await asyncio.start_server(
+            lambda r, w, p=pool: handle_client(r, w, p),
+            sock=sock,
+        )
+        addrs = ", ".join(str(s.getsockname()) for s in server.sockets)
+        logging.info(
+            "Worker listening on %s (frontend %s:%d)",
+            addrs,
+            fe.get("listen_host", "0.0.0.0"),
+            fe["listen_port"],
+        )
+        servers.append(server)
+
+    # Wait until cancelled
+    try:
+        await asyncio.gather(*[s.serve_forever() for s in servers], *tasks)
+    except asyncio.CancelledError:
+        logging.info("Worker cancelled, shutting down servers")
+    finally:
+        for s in servers:
+            s.close()
+            try:
+                await s.wait_closed()
+            except Exception:
+                pass
+        for t in tasks:
+            t.cancel()
+            try:
+                await t
+            except Exception:
+                pass

ufaflow-1.0.6/ufaflow/ufaflow_server.py

@@ -0,0 +1,232 @@
+import asyncio
+import logging
+import socket
+import time
+from dataclasses import dataclass
+from typing import List, Optional
+
+logging.getLogger().setLevel(logging.INFO)
+
+
+@dataclass
+class Backend:
+    host: str
+    port: int
+    weight: int = 1
+    name: Optional[str] = None
+    up: bool = True
+    current_conns: int = 0
+    last_checked: float = 0.0
+
+    def __post_init__(self):
+        if not self.name:
+            self.name = f"{self.host}:{self.port}"
+
+    def addr(self):
+        return (self.host, self.port)
+
+
+class BackendPool:
+    def __init__(self, backends: List[Backend], algorithm: str = "round_robin"):
+        self.backends = backends
+        self.algorithm = algorithm
+        self._rr_state = 0
+
+    def available(self) -> List[Backend]:
+        return [b for b in self.backends if b.up]
+
+    def choose(self, client_ip: Optional[str] = None) -> Optional[Backend]:
+        av = self.available()
+        if not av:
+            return None
+        if self.algorithm == "least_conn":
+            return min(av, key=lambda b: b.current_conns)
+        # simple weighted round-robin
+        choices = []
+        for b in av:
+            choices.extend([b] * max(1, b.weight))
+        self._rr_state = (self._rr_state + 1) % len(choices)
+        return choices[self._rr_state]
+
+
+async def relay_stream(reader: asyncio.StreamReader, writer: asyncio.StreamWriter):
+    try:
+        while True:
+            data = await reader.read(64 * 1024)
+            if not data:
+                break
+            writer.write(data)
+            await writer.drain()
+    except (asyncio.CancelledError, ConnectionResetError, BrokenPipeError):
+        pass
+    finally:
+        try:
+            writer.close()
+            await writer.wait_closed()
+        except Exception:
+            pass
+
+
+async def handle_client(
+    client_reader: asyncio.StreamReader,
+    client_writer: asyncio.StreamWriter,
+    pool: BackendPool,
+    timeout: float = 10.0,
+):
+    peer = client_writer.get_extra_info("peername")
+    backend = pool.choose(client_ip=peer[0] if peer else None)
+    if not backend:
+        logging.warning("No available backend for connection from %s", peer)
+        try:
+            client_writer.close()
+            await client_writer.wait_closed()
+        except Exception:
+            pass
+        return
+    logging.info("Proxying %s -> %s", peer, backend.name)
+    backend.current_conns += 1
+    try:
+        try:
+            backend_reader, backend_writer = await asyncio.wait_for(
+                asyncio.open_connection(backend.host, backend.port), timeout=timeout
+            )
+        except Exception as e:
+            logging.warning("Failed to connect to backend %s: %s", backend.name, e)
+            backend.up = False
+            return
+        t1 = asyncio.create_task(relay_stream(client_reader, backend_writer))
+        t2 = asyncio.create_task(relay_stream(backend_reader, client_writer))
+        await asyncio.wait([t1, t2], return_when=asyncio.FIRST_COMPLETED)
+        for t in (t1, t2):
+            if not t.done():
+                t.cancel()
+    finally:
+        backend.current_conns = max(0, backend.current_conns - 1)
+        try:
+            client_writer.close()
+            await client_writer.wait_closed()
+        except Exception:
+            pass
+
+
+async def tcp_health_check_periodic(
+    backends: List[Backend], interval: int, timeout: float
+):
+    while True:
+        for b in backends:
+            try:
+                b.last_checked = time.time()
+                fut = asyncio.open_connection(b.host, b.port)
+                r, w = await asyncio.wait_for(fut, timeout=timeout)
+                try:
+                    w.close()
+                    await w.wait_closed()
+                except Exception:
+                    pass
+                if not b.up:
+                    logging.info("Backend %s is up", b.name)
+                b.up = True
+            except Exception:
+                if b.up:
+                    logging.warning("Backend %s is down", b.name)
+                b.up = False
+        await asyncio.sleep(interval)
+
+
+async def start_servers_from_config(config: dict):
+    frontends = config.get("frontends", [])
+    pools = []
+    tasks = []
+    for fe in frontends:
+        be_cfgs = fe.get("backends", [])
+        backends = [
+            Backend(b["host"], b["port"], b.get("weight", 1), name=b.get("name"))
+            for b in be_cfgs
+        ]
+        pool = BackendPool(backends, algorithm=fe.get("algorithm", "round_robin"))
+        pools.append((fe, pool))
+
+    all_backends = [b for _, p in pools for b in p.backends]
+    # healthcheck task
+    tasks.append(
+        asyncio.create_task(
+            tcp_health_check_periodic(
+                all_backends,
+                config.get("health_interval", 5),
+                config.get("health_timeout", 2),
+            )
+        )
+    )
+    # start frontends
+    servers = []
+    for fe, pool in pools:
+        host = fe.get("listen_host", "0.0.0.0")
+        port = fe["listen_port"]
+        # We'll create server sockets externally (in worker mode) and pass them
+        # into start_server via sock param.
+        # For single-process mode, use default start_server (no sock).
+        servers.append((host, port, pool))
+    return servers, tasks
+
+
+async def run_worker_with_sockets(config: dict, sockets: List[socket.socket]):
+    """
+    sockets: list of listening sockets (must correspond to config frontends order)
+    """
+    # set up uvloop already done by CLI
+    frontends = config.get("frontends", [])
+    pools = []
+    for fe in frontends:
+        be_cfgs = fe.get("backends", [])
+        backends = [
+            Backend(b["host"], b["port"], b.get("weight", 1), name=b.get("name"))
+            for b in be_cfgs
+        ]
+        pool = BackendPool(backends, algorithm=fe.get("algorithm", "round_robin"))
+        pools.append((fe, pool))
+
+    all_backends = [b for _, p in pools for b in p.backends]
+    tasks = []
+    tasks.append(
+        asyncio.create_task(
+            tcp_health_check_periodic(
+                all_backends,
+                config.get("health_interval", 5),
+                config.get("health_timeout", 2),
+            )
+        )
+    )
+
+    servers = []
+    # Create servers using provided sockets (SO_REUSEPORT case)
+    for (fe, pool), sock in zip(pools, sockets, strict=False):
+        server = await asyncio.start_server(
+            lambda r, w, p=pool: handle_client(r, w, p), sock=sock
+        )
+        addrs = ", ".join(str(s.getsockname()) for s in server.sockets)
+        logging.info(
+            "Worker listening on %s (frontend %s:%d)",
+            addrs,
+            fe.get("listen_host", "0.0.0.0"),
+            fe["listen_port"],
+        )
+        servers.append(server)
+
+    # Wait until cancelled
+    try:
+        await asyncio.gather(*[s.serve_forever() for s in servers], *tasks)
+    except asyncio.CancelledError:
+        logging.info("Worker cancelled, shutting down servers")
+    finally:
+        for s in servers:
+            s.close()
+            try:
+                await s.wait_closed()
+            except Exception:
+                pass
+        for t in tasks:
+            t.cancel()
+            try:
+                await t
+            except Exception:
+                pass

ufaflow-1.0.6/ufaflow.egg-info/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: ufaflow
+Version: 1.0.6
+Summary: UfaFlow
+Author: halif
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Dynamic: author
+Dynamic: license-file
+
+<h1 align="center">UfaFlow</h1>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Version-1.0.6-7c3aed?style=for-the-badge" alt="version" />
+  <img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="license" />
+  <img src="https://img.shields.io/badge/Python-3.11%2B-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="python" />
+  <img src="https://img.shields.io/badge/Release-1.0.6-10b981?style=for-the-badge" alt="release" />
+  <img src="https://img.shields.io/badge/FastAPI-✓-009688?style=for-the-badge&logo=fastapi&logoColor=white" alt="fastapi" />
+</p>
+
+<p align="center">
+  <a href="https://github.com/halif/ufaflow/actions">
+    <img src="https://img.shields.io/github/actions/workflow/status/halif/ufaflow/ci.yml?branch=main&label=CI&style=flat-square" alt="CI status" />
+  </a>
+  <img src="https://img.shields.io/badge/security-audits-passing-16a34a?style=flat-square" alt="security audits" />
+  <img src="https://img.shields.io/badge/status-stable-22c55e?style=flat-square" alt="status" />
+  <img src="https://img.shields.io/github/stars/halif/ufaflow?style=flat-square&logo=github&label=stars" alt="stars" />
+  <img src="https://img.shields.io/github/issues/halif/ufaflow?style=flat-square&logo=github&label=issues" alt="issues" />
+  <img src="https://img.shields.io/github/last-commit/halif/ufaflow?style=flat-square&logo=github&label=last%20commit" alt="last commit" />
+</p>
+
+## Overview
+
+UfaFlow is a lightweight asynchronous worker manager and load balancer for Python services. It distributes traffic across worker processes with predictable lifecycle control, simple configuration, and async-first execution.
+
+The project is designed for teams that need:
+- a simple worker runtime
+- process-level isolation
+- async-first execution
+- predictable startup and shutdown behavior
+- easy deployment in development and production-like environments
+
+## Why UfaFlow
+
+Many applications need more than a single process, but do not require the complexity of a full orchestration platform. UfaFlow acts as a lightweight execution layer that helps you:
+- manage multiple workers with a single runtime
+- balance traffic or task distribution across processes
+- keep lifecycle management explicit and controllable
+- reduce operational overhead for small-to-medium service deployments
+
+## Key Features
+
+- Async-first worker orchestration
+- Configurable worker pool and process management
+- Lightweight request balancing across workers
+- Support for FastAPI and Python service integration
+- YAML-based configuration
+- Clean startup and shutdown lifecycle behavior
+- Simple deployment model for local and cloud environments
+
+## Installation
+
+```bash
+pip install ufaflow
+```
+
+## Quick start
+
+Create a YAML config file:
+
+```yaml
+health_interval: 5
+health_timeout: 2
+frontends:
+  - listen_host: "0.0.0.0"
+    listen_port: 8080
+    algorithm: round_robin
+    backends:
+      - host: "127.0.0.1"
+        port: 8001
+      - host: "127.0.0.1"
+        port: 8002
+```
+
+Run the load balancer:
+
+```bash
+python -m ufaflow.cli config.yaml
+```
+
+To run with multiple worker processes:
+
+```bash
+python -m ufaflow.cli config.yaml --workers 4
+```
+
+## License
+
+MIT

ufaflow-1.0.6/ufaflow.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+setup.py
+tests/test_backend_pool.py
+tests/test_cli_smoke.py
+ufaflow/__init__.py
+ufaflow/cli.py
+ufaflow/server.py
+ufaflow/ufaflow_server.py
+ufaflow.egg-info/PKG-INFO
+ufaflow.egg-info/SOURCES.txt
+ufaflow.egg-info/dependency_links.txt
+ufaflow.egg-info/requires.txt
+ufaflow.egg-info/top_level.txt

ufaflow-1.0.6/ufaflow.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ufaflow-1.0.6/ufaflow.egg-info/requires.txt

@@ -0,0 +1 @@
+PyYAML>=6.0

ufaflow-1.0.6/ufaflow.egg-info/top_level.txt

@@ -0,0 +1 @@
+ufaflow