flvx/plans/032-issue-291-tunnel-traffic-quota.md

Issue 291 Tunnel Traffic Quota Plan

• Confirm quota semantics with issue owner: use existing billed traffic accounting (traffic_ratio * tunnel.flow), overage disables the tunnel and pauses active forwards, reset re-enables the tunnel and auto-resumes affected forwards.
• Extend backend schema in go-backend/internal/store/model/model.go with a dedicated tunnel quota persistence model that stores per-tunnel daily/monthly limits, current billed usage, rollover keys, and quota-disable metadata in a SQLite/PostgreSQL-safe shape.
• Add repository support in go-backend/internal/store/repo/ for reading quota settings, atomically rolling day/month windows forward, incrementing billed tunnel usage from flow uploads, checking overage state, marking quota-triggered disable state, clearing usage on manual reset, and listing quota data alongside tunnels.
• Wire billed tunnel usage accumulation into go-backend/internal/http/handler/flow_policy.go so each node-reported flow item updates both existing user/user_tunnel counters and the tunnel quota counters using the current billed flow scaling path.
• Implement quota enforcement in backend handlers: when a tunnel crosses quota, set tunnel.status = 0, mark it as quota-disabled, pause all active forwards under that tunnel, and persist enough state to distinguish quota shutdown from manual disable.
• Block forward lifecycle operations against quota-disabled or already-over-quota tunnels in go-backend/internal/http/handler/mutations.go and related flow-policy checks so create/resume paths fail fast with explicit quota messages.
• Extend the maintenance/reset job in go-backend/internal/http/handler/jobs.go to perform daily and monthly quota rollover resets, clear quota-disable flags when limits reset, and auto-resume forwards that were paused by quota enforcement.
• Add manual quota reset API support under go-backend/internal/http/handler/handler.go and go-backend/internal/http/handler/mutations.go for daily/monthly/all reset scopes, with backend logic to clear counters, re-enable the tunnel, and auto-resume forwards.
• Extend tunnel API payloads in go-backend/internal/store/repo/repository.go and handler responses so tunnel/list and tunnel/get expose quota configuration, usage, reset window state, and quota-disable reason without conflicting with existing flow semantics.
• Update backup/import-export structs and repository export/import helpers in go-backend/internal/store/model/model.go and go-backend/internal/store/repo/repository.go so tunnel quota configuration is preserved across backup/restore; only persist configuration and disable metadata, not stale rolling usage, unless implementation proves current-period restoration is necessary.
• Update frontend tunnel types and API helpers in vite-frontend/src/api/types.ts, vite-frontend/src/types/index.ts, and vite-frontend/src/api/index.ts to accept and submit tunnel quota fields with safe defaults for older payloads.
• Add quota management UI to vite-frontend/src/pages/tunnel.tsx for daily/monthly quota inputs, billed usage display, over-quota status, reset actions, and clear tunnel-disabled messaging while preserving existing layout and form conventions.
• Verify behavior with backend contract coverage in go-backend/tests/contract/ for over-quota disable, create/resume blocking, scheduled reset rollover, manual reset, and auto-resume after reset; run targeted backend tests plus a frontend build validation after implementation. (go test ./internal/http/handler/... ./tests/contract/... passed; frontend npm run build is currently blocked by missing local dependencies/types in this environment.)