Web Budget API

3.1. Applicability

Applicability of the Budget API is limited to potentially resource consuming background operations— operations that are not sufficiently privacy sensitive to need express user permission for basic usage.

User agents MUST NOT use the Budget API as an alternative to obtaining express user permission for privacy-sensitive operations such as accurate location access [GEOLOCATION-API] and access to the user’s camera and/or microphone [WEBRTC].

Examples include Web Background Sync [WEB-BACKGROUND-SYNC], which may have execution time and retry limitations applied by the user agent, and the Push API [PUSH-API] in situations where the effects of a push message are not immediately visible to the user.

3.2. Permissions

The Budget API provides an alternative to obtaining express user permission where the user agent believes it can appropriately protect the user for strictly resource consuming background operations.

Both the APIs described in this document, as well as the specifications that depend on this document, MUST NOT limit the user agent’s ability to require express user permission in addition to budget requirements.

User agents that require express user permission for certain background operations MAY lower or eliminate the background operation cost of such an operation, because the user has explicitly allowed the Web Application to engage on their behalf.

4.1. Navigator and WorkerNavigator extensions

[Exposed=Window]
partial interface Navigator {
    [SameObject] readonly attribute BudgetService budget;
};

[Exposed=Worker]
partial interface WorkerNavigator {
    [SameObject] readonly attribute BudgetService budget;
};

The budget attribute’s getter must return a BudgetService scoped to the entry settings object’s origin.

4.2. The BudgetService interface

The BudgetService interface represents the programmatic interface to the user agent’s budget service. It is available in both document and worker environments.

[Exposed=(Window,Worker)]
interface BudgetService {
    Promise<double> getCost(OperationType operation);
    Promise<sequence<BudgetState>> getBudget();

    Promise<boolean> reserve(OperationType operation);
};

The getCost() method returns a promise that will be resolved with the worst-case background operation cost of the indicated background operation.

When invoked, it MUST run the following steps:

1. Let promise be a new promise.
2. Let origin be the entry settings object’s origin.
3. If the origin is not a secure context, reject promise with a SecurityError and terminate these steps.
4. Return promise and run the following step in parallel:
   1. Resolve the promise with the worst-case background operation cost associated with the given operation.

The getBudget() method returns a promise that will be resolved with a sequence of BudgetState objects indicating the expected state of the budget at given times in the future.

When invoked, it MUST run the following steps:

1. Let promise be a new promise.
2. Let origin be the entry settings object’s origin.
3. If the origin is not a secure context, reject promise with a SecurityError and terminate these steps.
4. Return promise and run the following step in parallel:
   1. Let details be a new sequence.
   2. If there are entries in origin’s list of budget expectations, for each entry:
      1. Let state be a new BudgetState instance.
      2. Set state’s budgetAt attribute to entry’s budget value.
      3. Set state’s time attribute to the DOMTimeStamp representing the final date of entry’s validity in milliseconds since 00:00:00 UTC on 1 January 1970.
      4. Add state to details.

      Otherwise:

      1. Let state be a new BudgetState instance.
      2. Set state’s budgetAt attribute to 0.
      3. Set state’s time attribute to the DOMTimeStamp representing the current time in milliseconds since 00:00:00 UTC on 1 January 1970.
      4. Add state to details.
   3. Resolve the promise with details.

The reserve() method returns a promise that will be resolved with a boolean indicating whether the requested budget for operation could be reserved.

When invoked, it MUST run the following steps:

1. Let promise be a new promise.
2. Let origin be the entry settings object’s origin.
3. If the origin is not a secure context, reject promise with a SecurityError and terminate these steps.
4. Return promise and run the following step in parallel:
   1. Let budget be the amount of budget available to origin.
   2. Let cost be the background operation cost associated with operation.
   3. If cost is greater than budget, resolve the promise with the boolean false and abort these steps.
   4. Reserve the cost from origin’s budget and resolve the promise with the boolean true.

4.3. The BudgetState interface

The BudgetState interface represents the amount of budget available at a specific point in time. This enables authors to make near-term decisions about how to spend their budget.

[Exposed=(Window,Worker)]
interface BudgetState {
  readonly attribute double budgetAt;
  readonly attribute DOMTimeStamp time;
};

The budgetAt attribute’s getter must return the budget at the associated time.

The time attribute’s getter must return the timestamp representing the time, in milliseconds since 00:00:00 UTC on 1 January 1970, at which the budgetAt will be valid.

4.4. The OperationType enum

The OperationType enumeration describes the known set of background operations that the Web Budget API caters for. Authors can use this in combination with getCost() to interpret their available budget as a quantifiable set of background operations it can be used for.

enum OperationType {
  "silent-push"
};

The following OperationType values are defined:

• The silent-push value represents a background operation in response to an incoming push message through the Push API that does not result in a user visible action. [PUSH-API]

Specifications are encouraged to extend the OperationType enumeration with their own values. Naming consistency with the Permission API [PERMISSIONS], where applicable, is recommended.