89 lines
3.6 KiB
Markdown
89 lines
3.6 KiB
Markdown
# Bandwidth Usage Display
|
|
|
|
For entitlements with a limited monthly data allowance, the panel shows how much
|
|
VPN data the user has left. This page documents the rules that decide **which
|
|
unit** the remaining amount is shown in (GB vs. MB) and **how it is rounded**
|
|
(whole number vs. one decimal place).
|
|
|
|
> Bandwidth usage is displayed when `browser.ipProtection.bandwidth.enabled` is set to `true`.
|
|
|
|
The formatting logic lives in `formatRemainingBandwidth` in
|
|
`browser/components/ipprotection/content/ipprotection-utils.mjs`. The
|
|
`bandwidth-usage` custom element
|
|
(`browser/components/ipprotection/content/bandwidth-usage.mjs`) consumes it to
|
|
build the progress bar and numeric strings. Unit conversions rely on the
|
|
`BANDWIDTH` constants in
|
|
`browser/components/ipprotection/content/ipprotection-constants.mjs`.
|
|
|
|
## Units are binary
|
|
|
|
Conversions use binary (power-of-two) multiples, even though the UI labels them
|
|
`GB` and `MB`:
|
|
|
|
- `BANDWIDTH.BYTES_IN_GB` is `2^30` (1 GiB).
|
|
- `BANDWIDTH.BYTES_IN_MB` is `2^20` (1 MiB).
|
|
|
|
All raw bandwidth values (`remaining`, `max`) are handled as `BigInt`
|
|
byte counts sourced from the usage payload.
|
|
|
|
## Remaining data: GB vs. MB
|
|
|
|
`formatRemainingBandwidth(remainingBytes)` returns `{ value, useGB }`. The
|
|
unit is chosen from the remaining amount alone:
|
|
|
|
- **1 GB or more remaining** → `useGB: true`. The value is shown in GB,
|
|
rounded to **one decimal place** and formatted with `Intl.NumberFormat`
|
|
(`maximumFractionDigits: 1`), so it is locale-aware and drops trailing
|
|
zeros (`30`, not `30.0`; `12.5` stays `12.5`).
|
|
- **Less than 1 GB remaining** → `useGB: false`. The value switches to MB and
|
|
is shown as a **floored whole number** of MB
|
|
(`Math.floor(remainingBytes / BYTES_IN_MB)`), with no decimals.
|
|
|
|
The `useGB` flag selects the localized string, so the unit in the text always
|
|
matches the unit of the value:
|
|
|
|
| Context | `useGB: true` (GB) | `useGB: false` (MB) |
|
|
| --- | --- | --- |
|
|
| Progress bar description | `ip-protection-bandwidth-left-gb-1` | `ip-protection-bandwidth-left-mb-1` |
|
|
| Numeric-only view | `ip-protection-bandwidth-left-this-month-gb` | `ip-protection-bandwidth-left-this-month-mb` |
|
|
|
|
### Examples
|
|
|
|
- `12.5 GB` remaining → `"12.5"` GB.
|
|
- `30 GB` remaining → `"30"` GB (no decimal, because the fractional part is
|
|
zero).
|
|
- `0.9 GB` remaining → `921` MB (floored: `floor(0.9 * 1024)`).
|
|
|
|
## The monthly limit is always in GB
|
|
|
|
The maximum (`maxUsage`) shown alongside the remaining amount — and in the
|
|
header, help text, "limit reached", and reset strings — is **always expressed in
|
|
GB**, regardless of how much data is left. It is computed as
|
|
`maxGB = max / BYTES_IN_GB` and passed straight through without rounding. The
|
|
default monthly limit is `browser.ipProtection.bandwidth.maxInGb` (50 GB).
|
|
|
|
This is why a user near the end of their allowance sees a mixed-unit string such
|
|
as `500 MB of 50 GB left this month`: the remaining amount has dropped below
|
|
1 GB and switched to MB, but the limit stays in GB.
|
|
|
|
When the allowance is exhausted (`remaining <= 0`), the numeric text is
|
|
replaced by `ip-protection-bandwidth-hit-for-the-month`, which reports only
|
|
the limit (in GB).
|
|
|
|
## Progress bar value
|
|
|
|
The `<progress>` element measures **used** data, not remaining, and is always
|
|
expressed in GB:
|
|
|
|
- `max` is `maxGB`.
|
|
- `value` is `bandwidthUsedGB` (`(max - remaining) / BYTES_IN_GB`) rounded
|
|
to one decimal via `parseFloat(...toFixed(1))`.
|
|
|
|
The separate `percent` attribute is **bucketed** rather than exact, so styling
|
|
can react to thresholds without exposing precise usage. `bandwidthPercent`
|
|
returns:
|
|
|
|
- `90` when used is at or above 90%,
|
|
- `75` when used is at or above 75% (but below 90%),
|
|
- otherwise `Math.floor(percent)`.
|