docs(traffic): define shared pool accounting contract
parent
69f051a01a
commit
07ebfd4a64
@ -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.
|
||||
Loading…
Reference in New Issue