bwflow 0.1.0__tar.gz

bwflow-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.3
+Name: bwflow
+Version: 0.1.0
+Summary: Bandwidth manager for Linux
+Author: Blake Axon
+License: MIT
+Requires-Dist: typer>=0.24.1
+Requires-Dist: rich>=14.3.3
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# bwflow
+
+Egress bandwidth manager for Linux. Tracks monthly traffic via [vnstat](https://humdi.net/vnstat/) and enforces rate limits using `tc` when your budget runs out.
+
+## How it works
+
+At the start of each month, bwflow credits a configurable **burst allowance** (e.g. 50 GB) immediately. The remaining budget drips in continuously over the month. If egress exceeds the available tokens, a `tc` TBF rate limit is applied to your network interface. When the next month starts, the limit is lifted automatically.
+
+## Prerequisites
+
+| Package           | Purpose                              |
+| ----------------- | ------------------------------------ |
+| `vnstat ≥ 2.6`    | Traffic accounting (source of truth) |
+| `iproute2` (`tc`) | Applies rate limits to the interface |
+| Python ≥ 3.13     | Runtime                              |
+
+```bash
+# Ubuntu / Debian
+sudo apt install vnstat iproute2
+
+# Amazon Linux / RHEL
+sudo yum install vnstat iproute2
+
+# Alpine
+apk add vnstat iproute2
+```
+
+Enable the vnstat daemon:
+
+```bash
+sudo systemctl enable --now vnstat
+```
+
+## Installation
+
+```bash
+pip install bwflow
+```
+
+Verify:
+
+```bash
+bwflow --help
+```
+
+## Quick start
+
+**1. Initialise** (creates `/etc/bwflow/config.toml`, offers to patch `vnstat.conf`):
+
+```bash
+sudo bwflow init
+```
+
+**2. Review the config:**
+
+```toml
+# /etc/bwflow/config.toml
+
+[bandwidth]
+monthly_budget_gb = 100   # total monthly egress budget
+pre_charge_gb = 50        # burst tokens available from day 1
+billing_day = 1           # reset on the 1st of each month
+
+[network]
+interface = "eth0"        # interface to monitor and throttle
+
+[daemon]
+poll_interval_seconds = 15
+```
+
+**3. Install and start the systemd service:**
+
+```bash
+sudo cp /usr/local/lib/python3.x/site-packages/bwflow/contrib/bwflow.service \
+     /etc/systemd/system/
+# or from a source checkout:
+sudo cp contrib/bwflow.service /etc/systemd/system/
+
+sudo systemctl daemon-reload
+sudo systemctl enable --now bwflow
+```
+
+**4. Check logs:**
+
+```bash
+journalctl -u bwflow -f
+```
+
+## Commands
+
+| Command                     | Description                                  |
+| --------------------------- | -------------------------------------------- |
+| `sudo bwflow init`          | First-time setup: config + vnstat.conf patch |
+| `sudo bwflow run`           | Start the daemon (called by systemd)         |
+| `bwflow report`             | Show monthly traffic report                  |
+| `sudo bwflow run --verbose` | Debug logging (shows every 15 s tick)        |
+
+## Notes
+
+- `billing_day` must be `1` in v0.1 (calendar-month only). Arbitrary billing days are planned.
+- bwflow requires `UseUTC 1` in `/etc/vnstat.conf` on non-UTC systems. `bwflow init` offers to patch this automatically.
+- Rate limiting uses Linux `tc` TBF (Token Bucket Filter) and requires `CAP_NET_ADMIN`. The simplest setup is to run as root; see `contrib/bwflow.service` for a least-privilege alternative.

bwflow-0.1.0/README.md

@@ -0,0 +1,102 @@
+# bwflow
+
+Egress bandwidth manager for Linux. Tracks monthly traffic via [vnstat](https://humdi.net/vnstat/) and enforces rate limits using `tc` when your budget runs out.
+
+## How it works
+
+At the start of each month, bwflow credits a configurable **burst allowance** (e.g. 50 GB) immediately. The remaining budget drips in continuously over the month. If egress exceeds the available tokens, a `tc` TBF rate limit is applied to your network interface. When the next month starts, the limit is lifted automatically.
+
+## Prerequisites
+
+| Package           | Purpose                              |
+| ----------------- | ------------------------------------ |
+| `vnstat ≥ 2.6`    | Traffic accounting (source of truth) |
+| `iproute2` (`tc`) | Applies rate limits to the interface |
+| Python ≥ 3.13     | Runtime                              |
+
+```bash
+# Ubuntu / Debian
+sudo apt install vnstat iproute2
+
+# Amazon Linux / RHEL
+sudo yum install vnstat iproute2
+
+# Alpine
+apk add vnstat iproute2
+```
+
+Enable the vnstat daemon:
+
+```bash
+sudo systemctl enable --now vnstat
+```
+
+## Installation
+
+```bash
+pip install bwflow
+```
+
+Verify:
+
+```bash
+bwflow --help
+```
+
+## Quick start
+
+**1. Initialise** (creates `/etc/bwflow/config.toml`, offers to patch `vnstat.conf`):
+
+```bash
+sudo bwflow init
+```
+
+**2. Review the config:**
+
+```toml
+# /etc/bwflow/config.toml
+
+[bandwidth]
+monthly_budget_gb = 100   # total monthly egress budget
+pre_charge_gb = 50        # burst tokens available from day 1
+billing_day = 1           # reset on the 1st of each month
+
+[network]
+interface = "eth0"        # interface to monitor and throttle
+
+[daemon]
+poll_interval_seconds = 15
+```
+
+**3. Install and start the systemd service:**
+
+```bash
+sudo cp /usr/local/lib/python3.x/site-packages/bwflow/contrib/bwflow.service \
+     /etc/systemd/system/
+# or from a source checkout:
+sudo cp contrib/bwflow.service /etc/systemd/system/
+
+sudo systemctl daemon-reload
+sudo systemctl enable --now bwflow
+```
+
+**4. Check logs:**
+
+```bash
+journalctl -u bwflow -f
+```
+
+## Commands
+
+| Command                     | Description                                  |
+| --------------------------- | -------------------------------------------- |
+| `sudo bwflow init`          | First-time setup: config + vnstat.conf patch |
+| `sudo bwflow run`           | Start the daemon (called by systemd)         |
+| `bwflow report`             | Show monthly traffic report                  |
+| `sudo bwflow run --verbose` | Debug logging (shows every 15 s tick)        |
+
+## Notes
+
+- `billing_day` must be `1` in v0.1 (calendar-month only). Arbitrary billing days are planned.
+- bwflow requires `UseUTC 1` in `/etc/vnstat.conf` on non-UTC systems. `bwflow init` offers to patch this automatically.
+- Rate limiting uses Linux `tc` TBF (Token Bucket Filter) and requires `CAP_NET_ADMIN`. The simplest setup is to run as root; see `contrib/bwflow.service` for a least-privilege alternative.

bwflow-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["uv_build>=0.10.6"]
+build-backend = "uv_build"
+
+[project]
+name = "bwflow"
+version = "0.1.0"
+description = "Bandwidth manager for Linux"
+readme = "README.md"
+requires-python = ">=3.13"
+license = { text = "MIT" }
+authors = [
+    { name = "Blake Axon" },
+]
+dependencies = [
+    "typer>=0.24.1",
+    "rich>=14.3.3",
+]
+
+[project.scripts]
+bwflow = "bwflow.main:app"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-mock>=3.15.1",
+    "ruff>=0.15.4",
+    "ty>=0.0.19",
+]
+
+[tool.ruff]
+line-length = 79
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "D203",
+    "D213",
+    "E501",
+    "COM812",
+    "FBT001",
+    "FBT003",
+    "PLC0415",
+    "PLR0913",
+]
+fixable = ["ALL"]
+
+[tool.ruff.lint.per-file-ignores]
+# ignore unused imports in __init__.py files
+"__init__.py" = ["F401"]
+# Ignore missing type annotations in tests
+"tests/**/*.py" = [
+    "ANN",
+    "D103",
+    "INP001",
+    "PLR2004",
+    "S101",
+    "SLF001",
+]
+
+[tool.uv]
+package = true

bwflow-0.1.0/src/bwflow/__init__.py

@@ -0,0 +1,3 @@
+"""bwflow package."""
+
+from bwflow import config

bwflow-0.1.0/src/bwflow/budget.py

@@ -0,0 +1,92 @@
+"""Token bucket math: calculate remaining monthly egress budget."""
+
+from __future__ import annotations
+
+import calendar
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from bwflow.config import BwflowConfig
+
+# 1 GB = 10^9 bytes (SI units, matching CSP billing conventions).
+GB = 1_000_000_000
+
+
+@dataclass
+class BudgetState:
+    """Current budget calculation output for daemon decision making."""
+
+    tokens_bytes: int  # Remaining bytes (may be negative when over budget).
+    throttle_rate_kbps: (
+        int  # Rate cap to apply when throttled (kbits/sec for tc).
+    )
+    period_start: datetime  # UTC start of the current billing period.
+
+    @property
+    def is_exhausted(self) -> bool:
+        """True when the token bucket is empty (budget exceeded)."""
+        return self.tokens_bytes <= 0
+
+
+def calculate(
+    cfg: BwflowConfig,
+    monthly_tx_bytes: int,
+    now: datetime | None = None,
+) -> BudgetState:
+    """Calculate the current token bucket state.
+
+    Args:
+        cfg:               bwflow configuration.
+        monthly_tx_bytes:  Current billing period's egress in bytes (from vnstat).
+        now:               Current UTC time. Defaults to ``datetime.now(UTC)``.
+
+    Returns:
+        BudgetState with remaining tokens and throttle parameters.
+
+    """
+    if now is None:
+        now = datetime.now(UTC)
+
+    period_start = _period_start(cfg, now)
+    total_seconds = _seconds_in_month(period_start)
+    elapsed_seconds = (now - period_start).total_seconds()
+
+    pre_charge_bytes = cfg.pre_charge_gb * GB
+    drip_total_bytes = cfg.drip_gb * GB
+    drip_rate_bps = drip_total_bytes / total_seconds  # bytes / second
+
+    drip_accrued = min(drip_rate_bps * elapsed_seconds, drip_total_bytes)
+    tokens = int(pre_charge_bytes + drip_accrued - monthly_tx_bytes)
+
+    # Throttle rate: drip rate expressed in kbits/sec (tc's unit).
+    throttle_kbps = max(1, int(drip_rate_bps * 8 / 1000))
+
+    return BudgetState(
+        tokens_bytes=tokens,
+        throttle_rate_kbps=throttle_kbps,
+        period_start=period_start,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _period_start(cfg: BwflowConfig, now: datetime) -> datetime:
+    """Return the UTC datetime of the current billing period start."""
+    day = cfg.billing_day
+    if now.day >= day:
+        return datetime(now.year, now.month, day, tzinfo=UTC)
+    # billing started last month
+    if now.month == 1:
+        return datetime(now.year - 1, 12, day, tzinfo=UTC)
+    return datetime(now.year, now.month - 1, day, tzinfo=UTC)
+
+
+def _seconds_in_month(period_start: datetime) -> float:
+    """Total seconds in the calendar month that *period_start* falls in."""
+    days = calendar.monthrange(period_start.year, period_start.month)[1]
+    return float(days * 86400)

bwflow-0.1.0/src/bwflow/config.py

@@ -0,0 +1,189 @@
+"""bwflow configuration: schema, defaults, and /etc/bwflow/config.toml management."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+from bwflow import vnstat
+
+CONFIG_DIR = Path("/etc/bwflow")
+CONFIG_PATH = CONFIG_DIR / "config.toml"
+
+_CONFIG_TEMPLATE = """\
+[bandwidth]
+# Total monthly egress budget in GB.
+monthly_budget_gb = {monthly_budget_gb}
+
+# Pre-charged burst tokens credited at the start of each billing cycle.
+# The remainder ({drip_gb} GB) drips in continuously over the month.
+pre_charge_gb = {pre_charge_gb}
+
+# Day-of-month when the budget resets.
+# Note: only 1 is supported currently (calendar-month reset).
+billing_day = {billing_day}
+
+[network]
+# Network interface to monitor and throttle.
+# Run `ip link show` or `vnstat` to list available interfaces.
+interface = "{interface}"
+
+[daemon]
+# How often (in seconds) the daemon polls vnstat and adjusts tc rules.
+poll_interval_seconds = {poll_interval_seconds}
+"""
+
+
+# ---------------------------------------------------------------------------
+# Config dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class BwflowConfig:
+    """Runtime configuration loaded from /etc/bwflow/config.toml."""
+
+    monthly_budget_gb: int = 100
+    pre_charge_gb: int = 50
+    billing_day: int = 1
+    interface: str = "eth0"
+    poll_interval_seconds: int = 15
+
+    @property
+    def drip_gb(self) -> int:
+        """Return the monthly budget portion that accrues over time."""
+        return self.monthly_budget_gb - self.pre_charge_gb
+
+    def to_toml_str(self) -> str:
+        """Serialize this config to the bwflow TOML file format."""
+        return _CONFIG_TEMPLATE.format(
+            monthly_budget_gb=self.monthly_budget_gb,
+            pre_charge_gb=self.pre_charge_gb,
+            drip_gb=self.drip_gb,
+            billing_day=self.billing_day,
+            interface=self.interface,
+            poll_interval_seconds=self.poll_interval_seconds,
+        )
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def detect_default_interface() -> str:
+    """Return the first interface reported by vnstat, or 'eth0' as fallback."""
+    try:
+        stats = vnstat.get_monthly_stats(limit=1)
+        if stats:
+            return stats[0].name
+    except RuntimeError:
+        pass
+    return "eth0"
+
+
+def build_default_config() -> BwflowConfig:
+    """Build a BwflowConfig with sensible defaults, auto-detecting the interface."""
+    return BwflowConfig(interface=detect_default_interface())
+
+
+def check_root() -> None:
+    """Raise PermissionError if the process is not running as root."""
+    if os.geteuid() != 0:
+        msg = (
+            "bwflow init must be run as root to write to /etc/bwflow/.\n"
+            "Re-run with: sudo bwflow init"
+        )
+        raise PermissionError(
+            msg,
+        )
+
+
+def write_config(cfg: BwflowConfig, *, force: bool = False) -> None:
+    """Write cfg to /etc/bwflow/config.toml.
+
+    Args:
+        cfg:   Config to serialise.
+        force: Overwrite an existing config file without prompting.
+
+    Raises:
+        FileExistsError: If the config already exists and force is False.
+        PermissionError: Propagated from the OS if the process lacks write access.
+
+    """
+    CONFIG_DIR.mkdir(mode=0o755, parents=True, exist_ok=True)
+
+    if CONFIG_PATH.exists() and not force:
+        msg = (
+            f"{CONFIG_PATH} already exists.\n"
+            "Edit it manually, or re-run with --force to overwrite."
+        )
+        raise FileExistsError(
+            msg,
+        )
+
+    CONFIG_PATH.write_text(cfg.to_toml_str(), encoding="utf-8")
+    # Owner-readable/writable; group+other readable — same as typical /etc files.
+    CONFIG_PATH.chmod(0o644)
+
+
+def config_exists() -> bool:
+    """Return True when the default config file is present."""
+    return CONFIG_PATH.exists()
+
+
+def load_config(path: Path = CONFIG_PATH) -> BwflowConfig:
+    """Load and validate /etc/bwflow/config.toml into a BwflowConfig.
+
+    Raises:
+        FileNotFoundError: If the config file does not exist.
+        ValueError:        If required keys are missing or values are invalid.
+
+    """
+    if not path.exists():
+        msg = f"{path} not found. Run: sudo bwflow init"
+        raise FileNotFoundError(msg)
+
+    with path.open("rb") as f:
+        data = tomllib.load(f)
+
+    try:
+        bw = data["bandwidth"]
+        net = data["network"]
+        dm = data["daemon"]
+
+        cfg = BwflowConfig(
+            monthly_budget_gb=int(bw["monthly_budget_gb"]),
+            pre_charge_gb=int(bw["pre_charge_gb"]),
+            billing_day=int(bw["billing_day"]),
+            interface=str(net["interface"]),
+            poll_interval_seconds=int(dm["poll_interval_seconds"]),
+        )
+    except KeyError as exc:
+        msg = f"Missing required config key: {exc}"
+        raise ValueError(msg) from exc
+    except (TypeError, ValueError) as exc:
+        msg = f"Invalid config value: {exc}"
+        raise ValueError(msg) from exc
+
+    # Basic sanity checks.
+    if cfg.billing_day != 1:
+        msg = (
+            "billing_day != 1 is not yet supported.\n"
+            "vnstat only provides calendar-month totals, so any other value\n"
+            "would understate usage and delay throttling incorrectly.\n"
+            "Set billing_day = 1 for now."
+        )
+        raise ValueError(
+            msg,
+        )
+    if cfg.pre_charge_gb > cfg.monthly_budget_gb:
+        msg = "pre_charge_gb must be less or equal than monthly_budget_gb."
+        raise ValueError(msg)
+    if cfg.poll_interval_seconds < 1:
+        msg = "poll_interval_seconds must be >= 1."
+        raise ValueError(msg)
+
+    return cfg

bwflow-0.1.0/src/bwflow/contrib/bwflow.service

@@ -0,0 +1,42 @@
+[Unit]
+Description=bwflow bandwidth rate-limit daemon
+Documentation=https://github.com/blakeaxon/bwflow
+# Start after the network is up and vnstat has started.
+After=network.target vnstat.service
+Wants=vnstat.service
+
+[Service]
+Type=simple
+
+# Verify the binary path with: which bwflow
+# Common locations: /usr/local/bin/bwflow (pip/pipx) or /usr/bin/bwflow (distro package)
+ExecStart=/usr/local/bin/bwflow run
+
+# Restart automatically on unexpected exits (e.g. crash).
+# Does NOT restart on clean exit (SIGTERM from 'systemctl stop').
+Restart=on-failure
+RestartSec=10s
+
+# --- Privilege model ---
+# Option A (simple): run as root.
+User=root
+
+# Option B (recommended for production): dedicated system user with only
+# the capability needed to call tc. Uncomment after creating the user:
+#   useradd --system --no-create-home --shell /sbin/nologin bwflow
+#   setcap cap_net_admin+eip /usr/local/bin/bwflow
+#
+# User=bwflow
+# AmbientCapabilities=CAP_NET_ADMIN
+# CapabilityBoundingSet=CAP_NET_ADMIN
+# NoNewPrivileges=yes
+
+# --- Logging ---
+# Logs go to journald automatically. View with:
+#   journalctl -u bwflow -f
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=bwflow
+
+[Install]
+WantedBy=multi-user.target