From 07ebfd4a647580ad9e3d18cb2e2b245ce22121a9 Mon Sep 17 00:00:00 2001 From: codex Date: Sat, 31 Oct 2026 23:09:06 +0800 Subject: [PATCH] docs(traffic): define shared pool accounting contract --- docs/TRAFFIC_POOL.md | 138 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 docs/TRAFFIC_POOL.md diff --git a/docs/TRAFFIC_POOL.md b/docs/TRAFFIC_POOL.md new file mode 100644 index 00000000..f03aa69e --- /dev/null +++ b/docs/TRAFFIC_POOL.md @@ -0,0 +1,138 @@ +# Shared traffic-pool contract + +## Scope + +The traffic pool is a prepaid accounting projection. It does not replace +orders or service periods. Every purchase or renewal still creates one +independent `cloud_service_periods` row, and that period is the only source of +traffic entitlement. + +A pool is identified by `(user_id, traffic_pool_group_id)`. A traffic-pool +group is a stable commercial line identity. Different groups never share +quota, even when their hosts or public bridges are technically interchangeable. +Orders and service periods freeze the group identity at purchase time. + +The first release does not support moving an active service period between +traffic-pool groups. Host maintenance migration is permitted only when the +source and target remain in the same group. + +## Entitlements + +Each service period materializes at most one entitlement. + +- A future period is `scheduled` and contributes no usable bytes. +- At `starts_at`, its complete finite quota becomes active exactly once. +- A paid upgrade may only increase the active entitlement. The positive + difference keeps the original `ends_at` and is idempotent by upgrade source. +- At `ends_at`, only that entitlement's unused bytes are forfeited. Previously + consumed bytes remain immutable history. +- Deleting an instance early does not erase its paid entitlement. Other + instances in the same pool may consume it until the original `ends_at`. +- An unlimited period is excluded from the finite pool: its instance neither + contributes infinite quota nor consumes finite entitlements. +- A maintenance migration or an in-place restore never creates another + entitlement. A backup copy receives quota only through a new paid service + period. + +## Usage allocation + +Only the Agent's durable cumulative public-interface RX and TX counters are +billable. VPC-interface traffic is outside this contract. PHP persists those +counters monotonically before traffic-pool settlement. + +New usage is allocated across active finite entitlements in strict FEFO order: + +```text +ends_at ASC, entitlement_id ASC +``` + +The instance that generated the traffic does not own the consumed +entitlement. Entitlement origin remains audit metadata only. + +All mutations for one pool serialize under a single pool row lock. The lock +order is always: + +```text +pool -> instance cursor -> entitlements -> network restrictions +``` + +The accounting transaction advances the instance cursor, appends immutable +ledger events, updates entitlement and pool projections, and updates desired +network restrictions atomically. It never calls an Agent while holding a +database transaction. + +Repeated observations and repeated lifecycle finalization must have no new +effect. A counter regression is an attention condition; it must not refund +traffic or charge the observed total from zero. + +## Sampling overage and expiry boundaries + +Polling cannot stop traffic at an exact byte. If an observation exceeds the +available pool balance, the remaining entitlements are consumed, the excess is +recorded as `overage_bytes`, and the pool becomes exhausted. A later finite +entitlement first settles that debt before exposing usable bytes. Overage is +never silently discarded. + +At `ends_at`, an entitlement immediately stops contributing visible or +allocatable balance. A bounded `closing` interval may settle observations +whose trusted `observed_at` is not later than `ends_at`. Closing must end after +at most two normal collection intervals; a missing host cannot keep a paid +period or pool permanently locked. + +## Network policy + +Traffic accounting owns only the `traffic_pool_exhausted` network restriction. +Service expiry and administrator policy have independent reasons. Public +network access is desired only when no active restriction exists. + +When a pool is exhausted, all active finite instances in that user and group +receive the traffic restriction. When usable balance returns, accounting +removes only its own restriction. It must never clear `service_expired`, +`admin_hold`, or another module's restriction. + +Remote network mutations use the existing durable job and operation-identity +contracts. A timeout or malformed receipt has unknown effect: retain the +original operation identifier for reconciliation and never automatically +replay it. + +## Read model + +User and administrator pages read a pool snapshot produced by the accounting +module. They do not sum entitlements themselves. + +The primary user values are: + +- currently active finite quota; +- consumption from currently active entitlements; +- usable balance; +- unsettled sampling overage; +- the next expiry time and the unused bytes that will be forfeited then; +- last trusted observation and network-restriction state. + +Lifetime or calendar-month usage is a separate statistic. It must not be +divided by the currently active quota because expired entitlements legitimately +make historical usage greater than the quota still active today. + +## Conservation and recovery invariants + +For every entitlement: + +```text +granted_bytes = consumed_bytes + remaining_bytes + forfeited_bytes +``` + +For accepted traffic observations: + +```text +observed_delta = allocated_consumption + overage_delta +``` + +No projection may become negative. Immutable ledger events are the audit +source; pool, entitlement and cursor projections must be verifiable from them. +Projection mismatch fences automatic network restoration for that pool but +does not delete the ledger or issue another remote mutation. + +Before enforcement, the feature may run in shadow mode. After traffic has +been shared across instances, rolling back to per-instance balances is not +safe; recovery must pause new network mutations, retain the ledger and repair +or rebuild the projection forward.