Skip to content

ServerKit is a lightweight, modern server control panel for managing web applications, databases, and services on your VPS or dedicated server. Built with Python/Flask backend and React frontend.

feat(hosting): per-domain bandwidth accounting

Juan Denis3cbbcb5e6bec
diff --git a/backend/app/api/bandwidth.py b/backend/app/api/bandwidth.py
new file mode 100644
index 00000000..e4bdab1b
--- /dev/null
+++ b/backend/app/api/bandwidth.py
@@ -0,0 +1,54 @@
+"""REST surface for per-domain bandwidth accounting.
+
+Mounted at /api/v1/bandwidth (registered in app/__init__.py).
+"""
+from flask import Blueprint, jsonify, request
+
+from ..middleware.rbac import admin_required, viewer_required
+from ..services.bandwidth_service import BandwidthService
+
+bandwidth_bp = Blueprint('bandwidth', __name__)
+
+
+@bandwidth_bp.route('/apps', methods=['GET'])
+@viewer_required
+def get_apps_bandwidth():
+ """Month totals + 30-day sparkline series for every app with traffic —
+ one call for the Services list."""
+ try:
+ data = BandwidthService.overview(days=30)
+ # JSON object keys must be strings.
+ return jsonify({'apps': {str(k): v for k, v in data.items()}})
+ except Exception as exc: # noqa: BLE001 — surface as a clean JSON error
+ return jsonify({'error': str(exc)}), 500
+
+
+@bandwidth_bp.route('/apps/<int:app_id>', methods=['GET'])
+@viewer_required
+def get_app_bandwidth(app_id):
+ """Full daily series (default 90 days) + current-month total for one app."""
+ try:
+ days = request.args.get('days', 90, type=int)
+ series = BandwidthService.series(app_id=app_id, days=days)
+ return jsonify({
+ 'app_id': app_id,
+ 'days': len(series),
+ 'series': series,
+ 'month_bytes': BandwidthService.monthly_total(app_id),
+ })
+ except Exception as exc: # noqa: BLE001
+ return jsonify({'error': str(exc)}), 500
+
+
+@bandwidth_bp.route('/aggregate', methods=['POST'])
+@admin_required
+def run_aggregate():
+ """Run the daily aggregation now (optionally for a specific day)."""
+ try:
+ payload = request.get_json(silent=True) or {}
+ result = BandwidthService.aggregate(day=payload.get('day'))
+ return jsonify(result)
+ except ValueError:
+ return jsonify({'error': 'day must be YYYY-MM-DD'}), 400
+ except Exception as exc: # noqa: BLE001
+ return jsonify({'error': str(exc)}), 500
diff --git a/backend/app/models/site_bandwidth.py b/backend/app/models/site_bandwidth.py
new file mode 100644
index 00000000..9347df07
--- /dev/null
+++ b/backend/app/models/site_bandwidth.py
@@ -0,0 +1,43 @@
+"""Per-domain daily bandwidth rollups.
+
+One row per (domain, day) aggregated from the nginx access logs by
+``BandwidthService.aggregate`` (job kind ``bandwidth.aggregate``). ``app_id``
+is a best-effort attribution via the Domain/Application tables and is
+nullable so traffic to domains the panel no longer manages is still recorded.
+"""
+from datetime import datetime
+
+from app import db
+
+
+class SiteBandwidthDaily(db.Model):
+ __tablename__ = 'site_bandwidth_daily'
+ __table_args__ = (
+ db.UniqueConstraint('domain', 'day', name='uq_site_bandwidth_domain_day'),
+ )
+
+ id = db.Column(db.Integer, primary_key=True)
+ app_id = db.Column(
+ db.Integer,
+ db.ForeignKey('applications.id', ondelete='CASCADE'),
+ nullable=True,
+ )
+ domain = db.Column(db.String(255), nullable=False, index=True)
+ day = db.Column(db.Date, nullable=False, index=True)
+ bytes_sent = db.Column(db.BigInteger, nullable=False, default=0)
+ requests = db.Column(db.Integer, nullable=False, default=0)
+ created_at = db.Column(db.DateTime, default=datetime.utcnow)
+
+ def to_dict(self):
+ return {
+ 'id': self.id,
+ 'app_id': self.app_id,
+ 'domain': self.domain,
+ 'day': self.day.isoformat() if self.day else None,
+ 'bytes_sent': int(self.bytes_sent or 0),
+ 'requests': int(self.requests or 0),
+ 'created_at': self.created_at.isoformat() if self.created_at else None,
+ }
+
+ def __repr__(self):
+ return f'<SiteBandwidthDaily {self.domain} {self.day}>'
diff --git a/backend/app/services/bandwidth_service.py b/backend/app/services/bandwidth_service.py
new file mode 100644
index 00000000..59f9e44c
--- /dev/null
+++ b/backend/app/services/bandwidth_service.py
@@ -0,0 +1,337 @@
+"""Per-domain bandwidth accounting from nginx access logs.
+
+A daily job (kind ``bandwidth.aggregate``) streams each site's nginx access
+log — the ``/var/log/nginx/{name}.access.log`` files the vhost templates
+write (see ``NginxService.site_access_log_path``) — plus the server-wide
+``access.log`` catch-all, sums ``$body_bytes_sent`` and request counts per
+domain for one calendar day, and upserts :class:`SiteBandwidthDaily` rows.
+
+Log format handling:
+ * standard "combined" lines are attributed to the owning app's primary
+ domain (per-site logs don't record ``$host``);
+ * vhost-prefixed lines (``$host[:$port] `` before the combined fields, as
+ produced by ``vcombined``-style formats) are split by that host — the
+ only way lines in the shared default ``access.log`` can be attributed.
+
+Re-running a day replaces that day's rows (incremental-safe). On dev boxes
+with no nginx logs (e.g. Windows) the job is a clean no-op.
+"""
+import logging
+import os
+import re
+from datetime import date, datetime, timedelta
+
+from app import db
+
+logger = logging.getLogger(__name__)
+
+BANDWIDTH_JOB_KIND = 'bandwidth.aggregate'
+BANDWIDTH_SCHEDULE_NAME = 'bandwidth-aggregate'
+
+# Keep a little over a year of daily rows.
+RETENTION_DAYS = 400
+
+# nginx "combined" format:
+# $remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent ...
+_COMBINED_RE = re.compile(
+ r'^(?P<ip>\S+) \S+ \S+ \[(?P<time>[^\]]+)\] '
+ r'"(?P<request>[^"]*)" (?P<status>\d{3}) (?P<bytes>\d+|-)'
+)
+# Same fields with a leading $host[:$port] (Apache "vcombined"-style, also a
+# common custom nginx log_format for shared logs).
+_VHOST_RE = re.compile(
+ r'^(?P<host>[^\s:]+)(?::\d+)? (?P<ip>\S+) \S+ \S+ \[(?P<time>[^\]]+)\] '
+ r'"(?P<request>[^"]*)" (?P<status>\d{3}) (?P<bytes>\d+|-)'
+)
+
+# nginx writes $time_local with English month abbreviations regardless of
+# locale; build the day prefix by hand so we never depend on the C runtime's.
+_MONTHS = ('Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+ 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec')
+
+
+def _day_prefix(day):
+ """``date(2026, 7, 3)`` → ``'03/Jul/2026'`` (start of ``$time_local``)."""
+ return f'{day.day:02d}/{_MONTHS[day.month - 1]}/{day.year}'
+
+
+def _normalize_host(host):
+ """Lowercase a logged $host and strip a trailing dot. Returns None for
+ values that clearly aren't a domain ('-', '_', empty)."""
+ host = (host or '').strip().rstrip('.').lower()
+ if not host or host in ('-', '_'):
+ return None
+ return host
+
+
+class BandwidthService:
+
+ # ------------------------------------------------------------------ #
+ # Log parsing
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def parse_log_file(cls, path, day):
+ """Stream one access log, keeping only ``day``'s lines.
+
+ Returns ``(per_host, plain, skipped)``:
+ * ``per_host`` — {host: [bytes, requests]} from vhost-prefixed lines
+ * ``plain`` — [bytes, requests] from standard combined lines
+ * ``skipped`` — count of unparsable lines
+ Missing/unreadable files count as empty (best-effort by design).
+ """
+ per_host = {}
+ plain = [0, 0]
+ skipped = 0
+ prefix = _day_prefix(day)
+ try:
+ with open(path, 'r', encoding='utf-8', errors='replace') as fh:
+ for line in fh:
+ line = line.strip()
+ if not line:
+ continue
+ match = _COMBINED_RE.match(line)
+ host = None
+ if not match:
+ match = _VHOST_RE.match(line)
+ if match:
+ host = _normalize_host(match.group('host'))
+ if not match:
+ skipped += 1
+ continue
+ if not match.group('time').startswith(prefix):
+ continue
+ raw = match.group('bytes')
+ nbytes = int(raw) if raw.isdigit() else 0
+ if host:
+ bucket = per_host.setdefault(host, [0, 0])
+ bucket[0] += nbytes
+ bucket[1] += 1
+ else:
+ plain[0] += nbytes
+ plain[1] += 1
+ except OSError:
+ pass # no log on this box (dev) or unreadable — clean zero result
+ return per_host, plain, skipped
+
+ # ------------------------------------------------------------------ #
+ # Aggregation job
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def aggregate(cls, day=None, log_dir=None):
+ """Aggregate one day's nginx access logs into SiteBandwidthDaily.
+
+ ``day`` defaults to yesterday (accepts a ``date`` or 'YYYY-MM-DD').
+ ``log_dir`` overrides the nginx log directory (tests). Re-running a
+ day replaces that day's rows. Also prunes rows older than
+ ``RETENTION_DAYS``.
+ """
+ from app.models.application import Application
+ from app.models.domain import Domain
+ from app.models.site_bandwidth import SiteBandwidthDaily
+ from app.services.nginx_service import NginxService
+
+ if day is None:
+ day = date.today() - timedelta(days=1)
+ elif isinstance(day, str):
+ day = datetime.strptime(day, '%Y-%m-%d').date()
+
+ if log_dir is None:
+ log_dir = NginxService.LOG_DIR
+
+ # domain (lowercased) -> app_id, for attributing vhost-split lines.
+ domain_app = {
+ d.name.lower(): d.application_id
+ for d in Domain.query.all() if d.name
+ }
+
+ # domain -> {'app_id': ..., 'bytes': ..., 'requests': ...}
+ totals = {}
+ skipped = 0
+ files_read = 0
+
+ def _add(domain, app_id, nbytes, nreqs):
+ if nreqs == 0 and nbytes == 0:
+ return
+ entry = totals.setdefault(
+ domain, {'app_id': app_id, 'bytes': 0, 'requests': 0})
+ if entry['app_id'] is None:
+ entry['app_id'] = app_id
+ entry['bytes'] += nbytes
+ entry['requests'] += nreqs
+
+ def _parse_with_rotation(base_path):
+ """Parse a log plus its ``.1`` rotation (day spillover)."""
+ nonlocal skipped, files_read
+ merged_hosts = {}
+ merged_plain = [0, 0]
+ for path in (base_path, base_path + '.1'):
+ if not os.path.isfile(path):
+ continue
+ per_host, plain, bad = cls.parse_log_file(path, day)
+ files_read += 1
+ skipped += bad
+ merged_plain[0] += plain[0]
+ merged_plain[1] += plain[1]
+ for host, (b, r) in per_host.items():
+ bucket = merged_hosts.setdefault(host, [0, 0])
+ bucket[0] += b
+ bucket[1] += r
+ return merged_hosts, merged_plain
+
+ # Per-site logs: /var/log/nginx/{app.name}.access.log
+ for app_row in Application.query.all():
+ base = os.path.join(log_dir, f'{app_row.name}.access.log')
+ per_host, plain = _parse_with_rotation(base)
+ primary = None
+ for d in (app_row.domains or []):
+ if d.is_primary:
+ primary = d.name
+ break
+ if primary is None and app_row.domains:
+ primary = app_row.domains[0].name
+ default_domain = (primary or app_row.name or '').lower()
+ if default_domain:
+ _add(default_domain, app_row.id, plain[0], plain[1])
+ for host, (b, r) in per_host.items():
+ _add(host, domain_app.get(host, app_row.id), b, r)
+
+ # Server-wide catch-all: only vhost-prefixed lines are attributable.
+ default_hosts, _default_plain = _parse_with_rotation(
+ os.path.join(log_dir, 'access.log'))
+ for host, (b, r) in default_hosts.items():
+ _add(host, domain_app.get(host), b, r)
+
+ # Replace the day's rows (idempotent re-runs).
+ SiteBandwidthDaily.query.filter_by(day=day).delete(
+ synchronize_session=False)
+ for domain, entry in totals.items():
+ db.session.add(SiteBandwidthDaily(
+ app_id=entry['app_id'],
+ domain=domain,
+ day=day,
+ bytes_sent=entry['bytes'],
+ requests=entry['requests'],
+ ))
+
+ # Retention prune.
+ cutoff = date.today() - timedelta(days=RETENTION_DAYS)
+ pruned = SiteBandwidthDaily.query.filter(
+ SiteBandwidthDaily.day < cutoff).delete(synchronize_session=False)
+ db.session.commit()
+
+ return {
+ 'day': day.isoformat(),
+ 'domains': len(totals),
+ 'bytes_sent': sum(e['bytes'] for e in totals.values()),
+ 'requests': sum(e['requests'] for e in totals.values()),
+ 'files_read': files_read,
+ 'skipped_lines': skipped,
+ 'pruned': int(pruned or 0),
+ }
+
+ # ------------------------------------------------------------------ #
+ # Read side
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def series(cls, app_id=None, domain=None, days=30):
+ """Daily series for one app (all its domains summed) or one domain,
+ newest last, zero-filled: [{day, bytes_sent, requests}, ...]."""
+ from app.models.site_bandwidth import SiteBandwidthDaily
+
+ days = max(1, min(int(days), RETENTION_DAYS))
+ end = date.today()
+ start = end - timedelta(days=days - 1)
+
+ query = SiteBandwidthDaily.query.filter(
+ SiteBandwidthDaily.day >= start, SiteBandwidthDaily.day <= end)
+ if app_id is not None:
+ query = query.filter(SiteBandwidthDaily.app_id == int(app_id))
+ if domain is not None:
+ query = query.filter(SiteBandwidthDaily.domain == domain.lower())
+
+ by_day = {}
+ for row in query.all():
+ bucket = by_day.setdefault(row.day, [0, 0])
+ bucket[0] += int(row.bytes_sent or 0)
+ bucket[1] += int(row.requests or 0)
+
+ out = []
+ for offset in range(days):
+ d = start + timedelta(days=offset)
+ b, r = by_day.get(d, (0, 0))
+ out.append({'day': d.isoformat(), 'bytes_sent': b, 'requests': r})
+ return out
+
+ @classmethod
+ def monthly_total(cls, app_id):
+ """Total bytes_sent for the app in the current calendar month."""
+ from app.models.site_bandwidth import SiteBandwidthDaily
+
+ today = date.today()
+ first = today.replace(day=1)
+ total = (db.session.query(
+ db.func.coalesce(db.func.sum(SiteBandwidthDaily.bytes_sent), 0))
+ .filter(SiteBandwidthDaily.app_id == int(app_id),
+ SiteBandwidthDaily.day >= first,
+ SiteBandwidthDaily.day <= today)
+ .scalar())
+ return int(total or 0)
+
+ @classmethod
+ def overview(cls, days=30):
+ """One-call payload for the Services list:
+ {app_id: {'month_bytes': int, 'series30': [bytes...]}} — only apps
+ that have any recorded traffic."""
+ from app.models.site_bandwidth import SiteBandwidthDaily
+
+ days = max(1, min(int(days), RETENTION_DAYS))
+ end = date.today()
+ start = end - timedelta(days=days - 1)
+ month_first = end.replace(day=1)
+ window_start = min(start, month_first)
+
+ rows = (SiteBandwidthDaily.query
+ .filter(SiteBandwidthDaily.day >= window_start,
+ SiteBandwidthDaily.day <= end,
+ SiteBandwidthDaily.app_id.isnot(None))
+ .all())
+
+ per_app = {}
+ for row in rows:
+ entry = per_app.setdefault(row.app_id, {'month': 0, 'by_day': {}})
+ b = int(row.bytes_sent or 0)
+ if row.day >= month_first:
+ entry['month'] += b
+ if row.day >= start:
+ entry['by_day'][row.day] = entry['by_day'].get(row.day, 0) + b
+
+ out = {}
+ for app_id, entry in per_app.items():
+ series = [
+ entry['by_day'].get(start + timedelta(days=i), 0)
+ for i in range(days)
+ ]
+ out[app_id] = {'month_bytes': entry['month'], 'series30': series}
+ return out
+
+ # ------------------------------------------------------------------ #
+ # Job plumbing
+ # ------------------------------------------------------------------ #
+
+ @classmethod
+ def run_aggregate_job(cls, job):
+ """Job handler for ``bandwidth.aggregate`` (payload may pin a day)."""
+ payload = job.get_payload() if job is not None else {}
+ return cls.aggregate(day=payload.get('day'))
+
+ @classmethod
+ def register_jobs(cls):
+ """Register the aggregation handler. Called once at app startup
+ (see app/__init__.py); the daily schedule row is seeded with the
+ other builtins in seed_builtin_schedules()."""
+ from app.jobs import registry
+ registry.register(BANDWIDTH_JOB_KIND, cls.run_aggregate_job,
+ replace=True)
diff --git a/backend/migrations/versions/052_site_bandwidth.py b/backend/migrations/versions/052_site_bandwidth.py
new file mode 100644
index 00000000..74ea3a89
--- /dev/null
+++ b/backend/migrations/versions/052_site_bandwidth.py
@@ -0,0 +1,54 @@
+"""Per-domain bandwidth accounting.
+
+Adds the site_bandwidth_daily table: one row per (domain, day) rolled up
+from the nginx access logs by the daily bandwidth.aggregate job.
+
+Idempotent: MigrationService runs _fix_missing_columns() + db.create_all() on
+boot before Alembic, so guard on the live schema.
+
+Revision ID: 052_site_bandwidth
+Revises: 051_site_imports
+Create Date: 2026-07-03
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = '052_site_bandwidth'
+down_revision = '051_site_imports'
+branch_labels = None
+depends_on = None
+
+TABLE = 'site_bandwidth_daily'
+
+
+def upgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ if TABLE in set(inspector.get_table_names()):
+ return
+ op.create_table(
+ TABLE,
+ sa.Column('id', sa.Integer(), primary_key=True),
+ sa.Column('app_id', sa.Integer(),
+ sa.ForeignKey('applications.id', ondelete='CASCADE'),
+ nullable=True),
+ sa.Column('domain', sa.String(255), nullable=False),
+ sa.Column('day', sa.Date(), nullable=False),
+ sa.Column('bytes_sent', sa.BigInteger(), nullable=False,
+ server_default='0'),
+ sa.Column('requests', sa.Integer(), nullable=False,
+ server_default='0'),
+ sa.Column('created_at', sa.DateTime(), nullable=True),
+ sa.UniqueConstraint('domain', 'day',
+ name='uq_site_bandwidth_domain_day'),
+ )
+ op.create_index('ix_site_bandwidth_daily_domain', TABLE, ['domain'])
+ op.create_index('ix_site_bandwidth_daily_day', TABLE, ['day'])
+
+
+def downgrade():
+ conn = op.get_bind()
+ inspector = sa.inspect(conn)
+ if TABLE not in set(inspector.get_table_names()):
+ return
+ op.drop_table(TABLE)
diff --git a/backend/tests/test_bandwidth.py b/backend/tests/test_bandwidth.py
new file mode 100644
index 00000000..ccaa33c6
--- /dev/null
+++ b/backend/tests/test_bandwidth.py
@@ -0,0 +1,377 @@
+"""Tests for per-domain bandwidth accounting (BandwidthService + API).
+
+Covers: access-log parsing (combined + vhost-prefixed, bad lines skipped),
+per-domain sums with app attribution via Domain rows, upsert idempotency,
+rotated-file spillover, series/monthly math across a month boundary,
+retention pruning, and the /api/v1/bandwidth surface.
+"""
+from datetime import date, timedelta
+
+import pytest
+
+from app import db
+# Ensure the table is on db.Model metadata before the app fixture's
+# create_all() (production wiring imports it in app/models/__init__.py).
+import app.models.site_bandwidth # noqa: F401
+from app.services.bandwidth_service import (
+ BandwidthService,
+ RETENTION_DAYS,
+ _day_prefix,
+)
+
+
+# ── helpers ──────────────────────────────────────────────────────────────────
+
+def _tl(day):
+ """$time_local for noon of ``day``."""
+ return f'{_day_prefix(day)}:12:00:00 +0000'
+
+
+def _combined(day, nbytes, path='/index.html', ip='203.0.113.7'):
+ return (f'{ip} - - [{_tl(day)}] "GET {path} HTTP/1.1" 200 {nbytes} '
+ f'"-" "Mozilla/5.0"')
+
+
+def _vhost(day, host, nbytes, path='/index.html'):
+ return (f'{host}:443 198.51.100.9 - - [{_tl(day)}] '
+ f'"GET {path} HTTP/1.1" 200 {nbytes} "-" "curl/8"')
+
+
+def _owner_id():
+ from app.models import User
+ from werkzeug.security import generate_password_hash
+ user = User.query.filter_by(username='bwowner').first()
+ if user is None:
+ user = User(
+ email='[email protected]', username='bwowner',
+ password_hash=generate_password_hash('x'),
+ role=User.ROLE_ADMIN, is_active=True,
+ )
+ db.session.add(user)
+ db.session.flush()
+ return user.id
+
+
+def _make_app(name, domains=(), primary=None):
+ from app.models.application import Application
+ from app.models.domain import Domain
+ app_row = Application(name=name, app_type='php', user_id=_owner_id())
+ db.session.add(app_row)
+ db.session.flush()
+ for dom in domains:
+ db.session.add(Domain(
+ name=dom, application_id=app_row.id,
+ is_primary=(dom == (primary or (domains[0] if domains else None))),
+ ))
+ db.session.commit()
+ return app_row
+
+
+def day():
+ return date.today() - timedelta(days=1)
+
+
+# ── log parsing ──────────────────────────────────────────────────────────────
+
+def test_parse_combined_lines_sums_and_day_filter(tmp_path, day):
+ other_day = day - timedelta(days=1)
+ log = tmp_path / 'a.access.log'
+ log.write_text('\n'.join([
+ _combined(day, 1000),
+ _combined(day, 250),
+ _combined(other_day, 999999), # wrong day: excluded
+ ]) + '\n')
+ per_host, plain, skipped = BandwidthService.parse_log_file(str(log), day)
+ assert per_host == {}
+ assert plain == [1250, 2]
+ assert skipped == 0
+
+
+def test_parse_vhost_prefixed_lines_split_by_host(tmp_path, day):
+ log = tmp_path / 'access.log'
+ log.write_text('\n'.join([
+ _vhost(day, 'alpha.test', 100),
+ _vhost(day, 'ALPHA.test', 50), # case-normalized
+ _vhost(day, 'beta.test', 7),
+ ]) + '\n')
+ per_host, plain, skipped = BandwidthService.parse_log_file(str(log), day)
+ assert per_host == {'alpha.test': [150, 2], 'beta.test': [7, 1]}
+ assert plain == [0, 0]
+ assert skipped == 0
+
+
+def test_parse_skips_and_counts_bad_lines(tmp_path, day):
+ log = tmp_path / 'a.access.log'
+ log.write_text('\n'.join([
+ 'utter garbage not a log line',
+ _combined(day, 10),
+ 'another bad one [nope',
+ ]) + '\n')
+ _hosts, plain, skipped = BandwidthService.parse_log_file(str(log), day)
+ assert plain == [10, 1]
+ assert skipped == 2
+
+
+def test_parse_missing_file_is_clean_zero(tmp_path, day):
+ per_host, plain, skipped = BandwidthService.parse_log_file(
+ str(tmp_path / 'nope.access.log'), day)
+ assert (per_host, plain, skipped) == ({}, [0, 0], 0)
+
+
+def test_parse_dash_bytes_counts_request_zero_bytes(tmp_path, day):
+ log = tmp_path / 'a.access.log'
+ line = _combined(day, 100).replace(' 200 100 ', ' 304 - ')
+ log.write_text(line + '\n')
+ _hosts, plain, skipped = BandwidthService.parse_log_file(str(log), day)
+ assert plain == [0, 1]
+ assert skipped == 0
+
+
+# ── aggregation ──────────────────────────────────────────────────────────────
+
+def test_aggregate_per_site_log_attributes_primary_domain(app, tmp_path, day):
+ from app.models.site_bandwidth import SiteBandwidthDaily
+ site = _make_app('mysite', domains=('mysite.com', 'www.mysite.com'),
+ primary='mysite.com')
+ (tmp_path / 'mysite.access.log').write_text('\n'.join([
+ _combined(day, 500),
+ _combined(day, 300),
+ ]) + '\n')
+
+ result = BandwidthService.aggregate(day=day, log_dir=str(tmp_path))
+ assert result['requests'] == 2
+ assert result['bytes_sent'] == 800
+
+ rows = SiteBandwidthDaily.query.all()
+ assert len(rows) == 1
+ assert rows[0].domain == 'mysite.com'
+ assert rows[0].app_id == site.id
+ assert rows[0].bytes_sent == 800
+ assert rows[0].requests == 2
+
+
+def test_aggregate_rerun_overwrites_not_duplicates(app, tmp_path, day):
+ from app.models.site_bandwidth import SiteBandwidthDaily
+ _make_app('mysite', domains=('mysite.com',))
+ log = tmp_path / 'mysite.access.log'
+ log.write_text(_combined(day, 100) + '\n')
+ BandwidthService.aggregate(day=day, log_dir=str(tmp_path))
+
+ # Log grew; re-run the same day.
+ log.write_text(_combined(day, 100) + '\n' + _combined(day, 60) + '\n')
+ BandwidthService.aggregate(day=day, log_dir=str(tmp_path))
+
+ rows = SiteBandwidthDaily.query.filter_by(day=day).all()
+ assert len(rows) == 1
+ assert rows[0].bytes_sent == 160
+ assert rows[0].requests == 2
+
+
+def test_aggregate_default_log_vhost_split_attributes_via_domain_rows(
+ app, tmp_path, day):
+ from app.models.site_bandwidth import SiteBandwidthDaily
+ site = _make_app('alpha', domains=('alpha.test',))
+ (tmp_path / 'access.log').write_text('\n'.join([
+ _vhost(day, 'alpha.test', 400),
+ _vhost(day, 'unknown.example', 9), # no Domain row: app_id None
+ _combined(day, 12345), # unattributable: dropped
+ ]) + '\n')
+
+ BandwidthService.aggregate(day=day, log_dir=str(tmp_path))
+
+ known = SiteBandwidthDaily.query.filter_by(domain='alpha.test').one()
+ assert known.app_id == site.id
+ assert known.bytes_sent == 400
+ unknown = SiteBandwidthDaily.query.filter_by(domain='unknown.example').one()
+ assert unknown.app_id is None
+ assert unknown.bytes_sent == 9
+ # The plain (host-less) default-log line must not create a row.
+ assert SiteBandwidthDaily.query.count() == 2
+
+
+def test_aggregate_reads_rotated_file_spillover(app, tmp_path, day):
+ from app.models.site_bandwidth import SiteBandwidthDaily
+ _make_app('mysite', domains=('mysite.com',))
+ # Target day's traffic split across the live log and its rotation.
+ (tmp_path / 'mysite.access.log').write_text(_combined(day, 70) + '\n')
+ (tmp_path / 'mysite.access.log.1').write_text(_combined(day, 30) + '\n')
+
+ BandwidthService.aggregate(day=day, log_dir=str(tmp_path))
+ row = SiteBandwidthDaily.query.filter_by(domain='mysite.com').one()
+ assert row.bytes_sent == 100
+ assert row.requests == 2
+
+
+def test_aggregate_no_logs_clean_zero(app, tmp_path, day):
+ """Windows/dev boxes with no nginx logs: clean empty result, no rows."""
+ from app.models.site_bandwidth import SiteBandwidthDaily
+ _make_app('mysite', domains=('mysite.com',))
+ result = BandwidthService.aggregate(day=day, log_dir=str(tmp_path))
+ assert result['domains'] == 0
+ assert result['bytes_sent'] == 0
+ assert SiteBandwidthDaily.query.count() == 0
+
+
+def test_aggregate_app_without_domains_uses_app_name(app, tmp_path, day):
+ from app.models.site_bandwidth import SiteBandwidthDaily
+ site = _make_app('barebones')
+ (tmp_path / 'barebones.access.log').write_text(_combined(day, 42) + '\n')
+ BandwidthService.aggregate(day=day, log_dir=str(tmp_path))
+ row = SiteBandwidthDaily.query.one()
+ assert row.domain == 'barebones'
+ assert row.app_id == site.id
+
+
+def test_aggregate_prunes_beyond_retention(app, tmp_path, day):
+ from app.models.site_bandwidth import SiteBandwidthDaily
+ old_day = date.today() - timedelta(days=RETENTION_DAYS + 5)
+ keep_day = date.today() - timedelta(days=RETENTION_DAYS - 5)
+ db.session.add(SiteBandwidthDaily(domain='old.test', day=old_day,
+ bytes_sent=1, requests=1))
+ db.session.add(SiteBandwidthDaily(domain='keep.test', day=keep_day,
+ bytes_sent=1, requests=1))
+ db.session.commit()
+
+ result = BandwidthService.aggregate(day=day, log_dir=str(tmp_path))
+ assert result['pruned'] == 1
+ domains = {r.domain for r in SiteBandwidthDaily.query.all()}
+ assert domains == {'keep.test'}
+
+
+def test_aggregate_accepts_iso_day_string(app, tmp_path):
+ day = date.today() - timedelta(days=3)
+ result = BandwidthService.aggregate(day=day.isoformat(),
+ log_dir=str(tmp_path))
+ assert result['day'] == day.isoformat()
+
+
+# ── read side: series / monthly_total ────────────────────────────────────────
+
+def _seed_row(domain, day, nbytes, requests=1, app_id=None):
+ from app.models.site_bandwidth import SiteBandwidthDaily
+ db.session.add(SiteBandwidthDaily(
+ app_id=app_id, domain=domain, day=day,
+ bytes_sent=nbytes, requests=requests))
+ db.session.commit()
+
+
+def test_series_zero_fills_and_sums_domains(app):
+ site = _make_app('mysite', domains=('a.test', 'b.test'))
+ today = date.today()
+ _seed_row('a.test', today, 100, requests=2, app_id=site.id)
+ _seed_row('b.test', today, 50, requests=1, app_id=site.id)
+ _seed_row('a.test', today - timedelta(days=2), 30, app_id=site.id)
+
+ series = BandwidthService.series(app_id=site.id, days=7)
+ assert len(series) == 7
+ assert series[-1] == {'day': today.isoformat(),
+ 'bytes_sent': 150, 'requests': 3}
+ assert series[-3]['bytes_sent'] == 30
+ assert series[0] == {'day': (today - timedelta(days=6)).isoformat(),
+ 'bytes_sent': 0, 'requests': 0}
+
+
+def test_monthly_total_excludes_previous_month(app):
+ site = _make_app('mysite', domains=('a.test',))
+ today = date.today()
+ first = today.replace(day=1)
+ prev_month_day = first - timedelta(days=1)
+ _seed_row('a.test', first, 500, app_id=site.id)
+ if today != first:
+ _seed_row('a.test', today, 250, app_id=site.id)
+ expected = 750
+ else:
+ expected = 500
+ _seed_row('a.test', prev_month_day, 100000, app_id=site.id)
+
+ assert BandwidthService.monthly_total(site.id) == expected
+ # The series across the boundary still sees both months.
+ days_span = (today - prev_month_day).days + 1
+ series = BandwidthService.series(app_id=site.id, days=days_span)
+ assert series[0]['bytes_sent'] == 100000
+
+
+def test_overview_shapes_per_app(app):
+ site = _make_app('mysite', domains=('a.test',))
+ other = _make_app('quiet', domains=('q.test',))
+ today = date.today()
+ _seed_row('a.test', today, 900, requests=4, app_id=site.id)
+
+ data = BandwidthService.overview(days=30)
+ assert site.id in data
+ assert other.id not in data # no traffic → omitted
+ entry = data[site.id]
+ assert entry['month_bytes'] == 900
+ assert len(entry['series30']) == 30
+ assert entry['series30'][-1] == 900
+ assert sum(entry['series30'][:-1]) == 0
+
+
+# ── job plumbing ─────────────────────────────────────────────────────────────
+
+def test_register_jobs_registers_handler(app):
+ from app.jobs import registry
+ BandwidthService.register_jobs()
+ from app.services.bandwidth_service import BANDWIDTH_JOB_KIND
+ assert BANDWIDTH_JOB_KIND in registry.registered_kinds()
+
+
+# ── API ──────────────────────────────────────────────────────────────────────
+
+def _register_bp(app):
+ from app.api.bandwidth import bandwidth_bp
+ if 'bandwidth' not in app.blueprints:
+ app.register_blueprint(bandwidth_bp, url_prefix='/api/v1/bandwidth')
+
+
+def test_api_requires_auth(app, client):
+ _register_bp(app)
+ resp = client.get('/api/v1/bandwidth/apps')
+ assert resp.status_code == 401
+
+
+def test_api_apps_overview_shape(app, client, auth_headers):
+ _register_bp(app)
+ site = _make_app('mysite', domains=('a.test',))
+ _seed_row('a.test', date.today(), 1234, requests=3, app_id=site.id)
+
+ resp = client.get('/api/v1/bandwidth/apps', headers=auth_headers)
+ assert resp.status_code == 200
+ payload = resp.get_json()
+ entry = payload['apps'][str(site.id)]
+ assert entry['month_bytes'] == 1234
+ assert len(entry['series30']) == 30
+
+
+def test_api_single_app_series(app, client, auth_headers):
+ _register_bp(app)
+ site = _make_app('mysite', domains=('a.test',))
+ _seed_row('a.test', date.today(), 77, app_id=site.id)
+
+ resp = client.get(f'/api/v1/bandwidth/apps/{site.id}?days=14',
+ headers=auth_headers)
+ assert resp.status_code == 200
+ payload = resp.get_json()
+ assert payload['app_id'] == site.id
+ assert payload['days'] == 14
+ assert len(payload['series']) == 14
+ assert payload['series'][-1]['bytes_sent'] == 77
+ assert payload['month_bytes'] == 77
+
+
+def test_api_aggregate_runs_and_rejects_bad_day(app, client, auth_headers,
+ tmp_path, monkeypatch):
+ _register_bp(app)
+ from app.services.nginx_service import NginxService
+ monkeypatch.setattr(NginxService, 'LOG_DIR', str(tmp_path))
+
+ resp = client.post('/api/v1/bandwidth/aggregate', headers=auth_headers,
+ json={})
+ assert resp.status_code == 200
+ assert 'bytes_sent' in resp.get_json()
+
+ bad = client.post('/api/v1/bandwidth/aggregate', headers=auth_headers,
+ json={'day': 'not-a-date'})
+ assert bad.status_code == 400
+ assert 'error' in bad.get_json()
diff --git a/frontend/src/components/BandwidthSparkline.jsx b/frontend/src/components/BandwidthSparkline.jsx
new file mode 100644
index 00000000..6b82ee4f
--- /dev/null
+++ b/frontend/src/components/BandwidthSparkline.jsx
@@ -0,0 +1,42 @@
+// Tiny dependency-free SVG sparkline for daily bandwidth series.
+// Plain <polyline> — deliberately no chart library.
+
+const BandwidthSparkline = ({ data, width = 96, height = 24, className = '' }) => {
+ if (!Array.isArray(data) || data.length === 0) return null;
+
+ const max = Math.max(...data, 1);
+ const stepX = data.length > 1 ? width / (data.length - 1) : width;
+ const pad = 2; // keep the stroke inside the viewBox
+
+ const points = data
+ .map((value, i) => {
+ const x = data.length > 1 ? i * stepX : width / 2;
+ const y = pad + (1 - value / max) * (height - pad * 2);
+ return `${x.toFixed(1)},${y.toFixed(1)}`;
+ })
+ .join(' ');
+
+ return (
+ <svg
+ className={`bw-spark ${className}`.trim()}
+ width={width}
+ height={height}
+ viewBox={`0 0 ${width} ${height}`}
+ preserveAspectRatio="none"
+ role="img"
+ aria-label="Daily transfer sparkline"
+ >
+ <polyline
+ points={points}
+ fill="none"
+ stroke="currentColor"
+ strokeWidth="1.5"
+ strokeLinejoin="round"
+ strokeLinecap="round"
+ vectorEffect="non-scaling-stroke"
+ />
+ </svg>
+ );
+};
+
+export default BandwidthSparkline;
diff --git a/frontend/src/components/service-detail/OverviewTab.jsx b/frontend/src/components/service-detail/OverviewTab.jsx
index d138b4df..f8efc995 100644
--- a/frontend/src/components/service-detail/OverviewTab.jsx
+++ b/frontend/src/components/service-detail/OverviewTab.jsx
@@ -3,6 +3,8 @@ import { Activity, Rocket, CheckCircle2, XCircle } from 'lucide-react';
import api from '../../services/api';
import { useDeployments } from '../../hooks/useDeployments';
import { getDeployStatus, formatRelativeTime, formatDuration } from '../../utils/serviceTypes';
+import { formatBytes } from '../../utils/formatBytes';
+import BandwidthSparkline from '../BandwidthSparkline';
import { MetricCard, Pill, Gauge, EnvTag } from '@/components/ds';
// Deployment status → semantic tone (ds Pill kind / dot modifier)
@@ -24,6 +26,7 @@ const ENV_LABEL = {
const OverviewTab = ({ app, deployConfig }) => {
const [metrics, setMetrics] = useState(null);
const [metricsLoading, setMetricsLoading] = useState(true);
+ const [bandwidth, setBandwidth] = useState(null);
const { deployments, loading: deploymentsLoading } = useDeployments(app.id);
const isDocker = app.app_type === 'docker';
@@ -35,6 +38,15 @@ const OverviewTab = ({ app, deployConfig }) => {
return () => clearInterval(interval);
}, [app.id]);
+ useEffect(() => {
+ // Best-effort daily rollups; hide the card when there is no data.
+ let cancelled = false;
+ api.getAppBandwidth(app.id, 90)
+ .then((data) => { if (!cancelled) setBandwidth(data); })
+ .catch(() => {});
+ return () => { cancelled = true; };
+ }, [app.id]);
+
async function loadMetrics() {
try {
if (isDocker) {
@@ -253,6 +265,25 @@ const OverviewTab = ({ app, deployConfig }) => {
</div>
</div>
+ {/* Bandwidth (daily nginx rollups; hidden until data exists) */}
+ {bandwidth?.series?.some(p => p.bytes_sent > 0) && (
+ <div className="overview-tab__card overview-tab__card--full overview-tab__bandwidth">
+ <div className="overview-tab__card-header-row">
+ <h3 className="overview-tab__card-title">Bandwidth</h3>
+ <span className="overview-tab__bandwidth-month">
+ {formatBytes(bandwidth.month_bytes)} this month
+ </span>
+ </div>
+ <BandwidthSparkline
+ data={bandwidth.series.map(p => p.bytes_sent)}
+ width={600}
+ height={48}
+ className="bw-spark--wide"
+ />
+ <span className="overview-tab__bandwidth-caption">Last 90 days</span>
+ </div>
+ )}
+
{/* Recent Deployments */}
<div className="overview-tab__card overview-tab__card--full">
<div className="overview-tab__card-header-row">
diff --git a/frontend/src/pages/Services.jsx b/frontend/src/pages/Services.jsx
index 10bce687..4878b928 100644
--- a/frontend/src/pages/Services.jsx
+++ b/frontend/src/pages/Services.jsx
@@ -5,6 +5,8 @@ import api from '../services/api';
import { useToast } from '../contexts/ToastContext';
import { getServiceType, getStatusConfig, formatRelativeTime } from '../utils/serviceTypes';
import ResourceListPage from '../components/layouts/ResourceListPage';
+import BandwidthSparkline from '../components/BandwidthSparkline';
+import { formatBytes } from '../utils/formatBytes';
import { Pill, ServiceTile, EnvTag } from '@/components/ds';
import { useTopbarActions } from '@/hooks/useTopbarActions';
import { Button } from '@/components/ui/button';
@@ -43,9 +45,14 @@ const Services = () => {
const [selectedIds, setSelectedIds] = useState(new Set());
const [bulkLoading, setBulkLoading] = useState(false);
const [showMoveDialog, setShowMoveDialog] = useState(false);
+ const [bandwidth, setBandwidth] = useState({});
useEffect(() => {
loadApps();
+ // Best-effort: one call for every row's sparkline; absence is fine.
+ api.getBandwidthApps()
+ .then((data) => setBandwidth(data?.apps || {}))
+ .catch(() => {});
}, []);
async function loadApps() {
@@ -242,6 +249,22 @@ const Services = () => {
return primaryDomain || <span className="wp-list__dash">—</span>;
},
},
+ {
+ key: 'bandwidth',
+ header: 'Transfer',
+ render: (app) => {
+ const bw = bandwidth[String(app.id)];
+ if (!bw || !bw.series30?.some(v => v > 0)) {
+ return <span className="wp-list__dash">—</span>;
+ }
+ return (
+ <span className="bw-cell" title="Transfer — last 30 days">
+ <BandwidthSparkline data={bw.series30} width={72} height={20} />
+ <span className="bw-cell__month">{formatBytes(bw.month_bytes)}/mo</span>
+ </span>
+ );
+ },
+ },
{
key: 'status',
header: 'Status',
diff --git a/frontend/src/services/api/bandwidth.js b/frontend/src/services/api/bandwidth.js
new file mode 100644
index 00000000..1ddc2681
--- /dev/null
+++ b/frontend/src/services/api/bandwidth.js
@@ -0,0 +1,17 @@
+// Per-domain bandwidth accounting — backs the Services list sparklines and
+// the service detail "Bandwidth this month" stat.
+
+export async function getBandwidthApps() {
+ return this.request('/bandwidth/apps');
+}
+
+export async function getAppBandwidth(appId, days = 90) {
+ return this.request(`/bandwidth/apps/${appId}?days=${days}`);
+}
+
+export async function runBandwidthAggregate(day = null) {
+ return this.request('/bandwidth/aggregate', {
+ method: 'POST',
+ body: JSON.stringify(day ? { day } : {}),
+ });
+}
diff --git a/frontend/src/styles/pages/_bandwidth.scss b/frontend/src/styles/pages/_bandwidth.scss
new file mode 100644
index 00000000..a9518107
--- /dev/null
+++ b/frontend/src/styles/pages/_bandwidth.scss
@@ -0,0 +1,50 @@
+// ============================================
+// PER-DOMAIN BANDWIDTH
+// Sparkline cell on the Services list + the Bandwidth card on the
+// service detail Overview tab. The <svg> itself is BandwidthSparkline.jsx.
+// ============================================
+
+// Shared sparkline styling (stroke inherits currentColor).
+.bw-spark {
+ display: block;
+ color: var(--accent, #4f8ef7);
+ opacity: 0.9;
+
+ &--wide {
+ width: 100%;
+ max-width: 640px;
+ height: 48px;
+ }
+}
+
+// Services list cell: sparkline + month total side by side.
+.bw-cell {
+ display: inline-flex;
+ align-items: center;
+ gap: 8px;
+
+ .bw-spark { flex-shrink: 0; }
+
+ &__month {
+ font-family: var(--mono);
+ font-size: 11.5px;
+ color: var(--text-dim);
+ white-space: nowrap;
+ }
+}
+
+// Service detail Overview: full-width bandwidth card additions.
+.overview-tab__bandwidth {
+ &-month {
+ font-family: var(--mono);
+ font-size: 12.5px;
+ color: var(--text-dim);
+ }
+
+ &-caption {
+ display: block;
+ margin-top: 6px;
+ font-size: 11px;
+ color: var(--text-faint);
+ }
+}