w3c / battery Goto Github PK

Battery Status API

Home Page: https://www.w3.org/TR/battery-status/

License: Other

HTML 100.00%

battery's Introduction

Battery Status API

This repository contains the Battery Status API specification that is being worked on in the W3C Device APIs Working Group.

battery's People

Stargazers

Watchers

Forkers

lknik riju foolip bhanditz honry domenic isabella232 rakuco igalia

battery's Issues

dark mode

Could you add a dark theme to https://www.w3.org/TR/battery-status?
it's currently very bright

Assess compatibility risk of using [SecureContext]

If we'd add [SecureContext] to partial interface Navigator and BatteryManager as is the current trend, we could drop the following prose:

If the current settings object is not a secure context, then reject this Navigator object's battery promise with a "SecurityError" DOMException and abort these steps.

However, this would break any feature detection code that relies on checking the existence of properties or objects, e.g.:

if ("getBattery" in navigator && "BatteryManager" in window)
  console.log('All your battery are belong to us');

I guess nearly everyone using this API must do some sort of feature detection.

My hunch is we want to close this issue as won't fix citing backward compatibility concerns.

Thoughts?

Checks on allowed usage are specced incorrectly

(This seems related to #10, but it's focused more on the details, so I opened a new issue.)

If the incumbent settings object is not a secure context, then reject this Navigator object's battery promise with a "SecurityError" DOMException, return this Navigator object's battery promise and abort these steps.

"incumbent settings object" should never be used by new specifications. I hope nobody implemented it this way. Instead, prefer the relevant settings object of this Navigator object.

See https://html.spec.whatwg.org/multipage/webappapis.html#realms-settings-objects-global-objects to learn about the (testable, observable) differences between these choices.

(Thanks @TimothyGu for spotting this.)

If the browsing context is not a top-level browsing context, then reject this Navigator object's battery promise with a "SecurityError" DOMException, return this Navigator object's battery promise and abort these steps.

What is "the browsing context"?

Probably you want, hmm, this Navigator object's relevant global object's associated Document's browsing context?

(If we see this pattern more, maybe we should make it easier to write... I'll file a tracking issue.)

Detect power saving mode

Some mobiles and laptop (even without batteries) have a power saving mode where they tune down on unnecessary stuff to save battery or reduce power consumption on stationary computers

I think it could be useful to detect this so we can disable some unnecessary stuff on the website

Allow use from within secure context and top-level browsing context only

(This issue is branched from a proposal made in #5 (comment) since there seemed to be adequate support for making such a spec update.)

Problem:

Malicious content such as framed tracker scripts using the API to fingerprint users.

Proposed solution:

Make the API available only within a secure context that is also a top-level browsing context. This disallows the use of the API within framed content, as well as from any content that is not a secure context.

See top-level documents and framed documents for illustrations.

Summary of changes:

There exists a hook in the spec to implement this change with no API surface changes in a backwards compatible manner:

if the API is invoked from within a browsing context that is not a secure context and not a top-level browsing context, then
leave the promise returned by getBattery() in a pending state

This means we won't break existing web content using the API.

@riju volunteered to look into updating the Chromium/Blink implementation accordingly after the spec changes have landed.

make privacy mitigations normative

Please either mark section 4 as normative (remove the non-normative mark) or move the mitigations from section 4 into normative parts of the document.

Use of "current global object" is confusing

It seems to me that all live BatteryManager objects should be updated when the battery state changes, rather than only the one connected to the "current global object" (if that is even well-defined here).

A promise/BatteryManager per browsing context!?

Is it really intentional that the same promise and battery manager are created per browsing context, instead of, say, per Document, or per Window?

This implies that the following will hold:

<!DOCTYPE html>

<iframe src="about:blank"></iframe>
<script>
"use strict";
const iframe = document.querySelector("iframe");

const originalNavigator = iframe.contentWindow.navigator;
const originalPromise = navigator.getBattery();

promise.then(originalManager => {
  iframe.onload = () => {
    // As expected, navigator changes:
    assert(iframe.contentWindow.navigator !== originalNavigator);

    // But the battery status promise does not!?!
    assert(iframe.contentWindow.navigator.getBattery() === originalPromise);

    // worse:
    iframe.contentWindow.navigator.getBattery().then(manager => {
      // the manager stays the same!!
      assert(manager === originalManager);

      // which means its prototype chain is broken!?
      assert(manager.__proto__ !== iframe.contentWindow.BatteryManager.prototype);
      assert(!(manager instanceof iframe.contentWindow.BatteryManager));
    });
  };
  iframe.src = "http://example.com";
});

// in fact, it's impossible to every have something be `instanceof BatteryManager`, even
// without iframe shenanigans, unless you are executing code in the initial about:blank document:
if (document.URL !== "about:blank" || document.history.length > 0) {
  navigator.getBattery().then(manager => {
    assert(!(manager instanceof BatteryManager));
  });
}

This seems very unlikely to be correct.

I notice this spec is going for PR. Is this behavior interoperable across multiple implementations?

add more discussion of sec and priv analysis; split sections

Section 4 is a little short on analysis and explanation of the risks of exposing this API. At the very least, since the mitigations it defines (well, see #27...) seem to be mostly about privacy, there should be a clear statement about security issues, if any.

Current best practice is to split security and privacy into separate sections. No fault for not having done that - we've only recently started asking for that - but please do that as you work on the section.

Johnson07Son's

Thanks for letting me share my feedback

BatteryManager: Describe instance creation in an algorithm

This came up in #46 (specifically, here). @marcoscaceres says:

yeah, let's do that as followup... fwiw, I'm imagining this prose need to go into some initializer steps... as an example:
https://w3c.github.io/geolocation-api/#constructing-a-geolocationposition

Right now it is not very clear what should happen when a new BatteryManager is created: when exactly do the internal slots have their initial values set (vs when do we start checking)? When do we send the first event?

Add an explicit use cases and requirements section

We should consider consolidating the use cases into its own section. Some of the use cases are discussed in the introduction, some in separate GitHub issues, some can be found from the group’s mailing list discussions.

Explore a high-level API

I believe these valid use-cases can be satisfied with onlowpower and maybe onfullpower events, rather than the current API. The existing API can have its precision reduced, likely without impacting valid use-cases. If absolutely necessary, we could imagine a 3rd, onverylowpower event, which sites could use to e.g. save current state to localStorage, attempt to flush the send buffers in any Service Workers, and otherwise prepare to shut down safely.

via https://bugs.chromium.org/p/chromium/issues/detail?id=661792#c49

private browsing mode: upgrade recommendation

First, it's not quite clear what "the user permission requirement" refers to in

The user agent MAY ask the user for battery status information access, or alternatively, enforce the user permission requirement in its private browsing modes.

Some clarity is needed, and I'm thinking this should be at least a SHOULD.

Update the reference to Feature Policy

The spec has been renamed: w3c/webappsec-permissions-policy#379

Expose getBattery to ServiceWorker

Sorry to be late to the party, but experimenting a bit with this feature on Chrome and Firefox I conclude that it is not available to ServiceWorkers. I think it could be useful there (e.g. the SW script checking if resources on the server have been updated, and download only if there is plenty of battery or the charger is connected).
Has this been discussed?

Status of this API

Hello,

Just wondering what the status of this API is? It is still currently in Chrome, although looking from Chromium bug reports there was discussion of removing it? It is under consideration for Edge, removed from Firefox and Safari.

I'm looking to alter behaviour based on:

Battery life ( battery saving mode)
Network connection speed and strength
Device capabilities
Data saving hints

This looked like it should have been potentially solved by the budgets api but that also looks like it has died and I expect will be removed from Chrome? https://wicg.github.io/budget-api/

Any ideas about Battery status or any other APIs that could be used to achieve this?

Respec warns about missing <dfn>'s in contiguous webidl

"No <dfn> for getBattery in Navigator" etc. The warnings probably started to appear after these changes to respec: w3c/respec#991

getBattery() spec doesn't make sense

It's supposed to return a Promise. In steps 1 and 2 it can "abort these steps" without returning anything...

Mitigating potential privacy-invasive usage

Starting with a concern raised in https://lists.w3.org/Archives/Public/public-device-apis/2016Jul/0000.html (see the full thread), we ended up discussing the permission model for the API, in particular why it is different from other APIs.

Let's use this issue to document proposed solutions that could be transformed into spec prose, while keeping compatibility with the existing shipping implementations.

[meta] Publish a revised Candidate Recommendation

On today's call we decided to publish a revised Candidate Recommendation.

I've staged a snapshot (work in progress):

Battery Status API W3C Candidate Recommendation 06 June 2017

Per the process for revising a CR, the group needs to address the following requirements:

must show that the revised specification meets all Working Group requirements, or explain why the requirements have changed or been deferred,
must specify the deadline for further comments, which must be at least four weeks after publication, and should be longer for complex documents,
must document the changes since the previous Candidate Recommendation,
must show that the proposed changes have received wide review, and
may identify features in the document as "at risk". These features may be removed before advancement to Proposed Recommendation without a requirement to publish a new Candidate Recommendation.

Other

update test results

@fhirsch @dontcallmedom, am I right in assuming we do not need a new wide review? I took an action to document the changes since the previous Candidate Recommendation to tick the last remaining box, after which @fhirsch you could issue a CfC to publish.

BatteryManager: Consider merging "multiple batteries" section into original attribute/internal slot definitions

This originally came up in #46. Rather than having a separate section about what should be done when more than one battery is present, the contents there should be merged into the section where we define how things work when there is only one battery available.

In @marcoscaceres' words:

As a followup, I wonder if this should be actually integrated into the definition of each slot. That way, it's all kept together.

Single battery, do x...

Multiple batteries, do y...

w3c / battery Goto Github PK

battery's Introduction

Battery Status API

battery's People

Stargazers

Watchers

Forkers

battery's Issues

Recommend Projects

Recommend Topics

Recommend Org