Skip to content

Commit

Permalink
Merge pull request #23 from w3c/cleanup
Browse files Browse the repository at this point in the history 
Cleanup processing and security & privacy
  • Loading branch information
@toddreifsteck
toddreifsteck committed Jan 20, 2016
2 parents 16ac769 + bf05242 commit fd52175
Showing 1 changed file with 18 additions and 57 deletions.
75 changes: 18 additions & 57 deletions index.html
View file
Expand Up @@ -357,8 +357,7 @@ <h2><code>sendBeacon</code> Method</h2>
<p>The <dfn id="dom-navigator-sendbeacon"><code>sendBeacon</code></dfn>
method transmits data provided by the <a href=
"#data-parameter"><code>data</code></a> parameter to the URL provided by
the <a href="#url-parameter"><code>url</code></a> parameter, according to
the following rules:</p>
the <a href="#url-parameter"><code>url</code></a> parameter:</p>
<ul>
<li>The user agent SHOULD restrict the maximum <code>data</code> size
to ensure that beacon requests are able to complete quickly and in a
Expand All @@ -372,17 +371,16 @@ <h2><code>sendBeacon</code> Method</h2>
agent SHOULD NOT delay transmission indefinitely and ensure that
pending transmissions are periodically flushed even if there is no
other network activity.</li>
<div class="note">See Fetch API + request coalescing discussion: <a href="https://github.com/whatwg/fetch/issues/184">https://github.com/whatwg/fetch/issues/184</a></div>
<li>The user agent MUST schedule immediate transmission of all beacon
requests when the document <code>visiblityState</code>
([[!PAGE-VISIBILITY]]) transitions to <code>hidden</code>, and must
allow all such requests to run to completion without blocking other
time-critical and high-priority work.</li>
<li>The user agent MUST NOT skip or throttle processing of beacon
requests, as it may contain critical application state, events, and
analytics data.</li>
<li>The user agent MUST process the response headers, and if provided,
MUST ignore any entity bodies in the response.</li>
</ul>

<div class="note">Beacon API does not provide a response callback. The server is encouraged to omit returning a response body for such requests (e.g. respond with <code>204 No Content</code>), and the client can terminate responses that contain a body - e.g. cancel the HTTP/2 stream, or abort the HTTP/1 connection.</div>

<div class="parameters">
<h4 id="parameters">Parameters</h4>
<h4 id="url-parameter"><code>url</code></h4>
Expand Down Expand Up @@ -412,9 +410,6 @@ <h2>Processing Model</h2>
"#dom-navigator-sendbeacon"><code>sendBeacon</code></a> method, the
following steps must be run:</p>
<ol>
<li>
<p>Set <var>requestTime</var> to current time.</p>
</li>
<li>
<p>Set <var>base</var> to the <a>entry settings object</a>'s <a>API
base URL</a>.</p>
Expand Down Expand Up @@ -503,61 +498,27 @@ <h2>Processing Model</h2>
<dd><i>include</i></dd>
</dl>
</li>
<li>
<p>Set <var>age</var> to current time minus <var>requestTime</var>
expressed in seconds. If <var>age</var> is non-zero, append a
<dfn><code>Beacon-Age</code></dfn> header with value <var>age</var>
to <a>header list</a> field of <var>req</var>.</p>
</li>
<li>
<a>Fetch</a> <var>req</var>.
</li>
</ol>
<p>The <dfn>Beacon-Age header field</dfn> is used to communicate the time
delay, measured in seconds, between the time when the request is sent and
the <i>requestTime</i> set when <a>sendBeacon</a> method is called. The
ABNF (Augmented Backus-Naur Form) syntax for the <a>Beacon-Age header
field</a> is as follows:</p>
<pre>
Beacon-Age = "Beacon-Age" ":" 1*DIGIT
</pre>
</section>
<section id="privacy" class='informative'>
<section id="privacy" class="informative">
<h2>Privacy and Security</h2>
<p>The <code>sendBeacon</code> interface provides an asynchronous and
non-blocking mechanism for delivery of data. It is designed to eliminate
the need for the widespread use of expensive anti-patterns that block
user interaction, and to enable more efficient scheduling and use of
system resources. The same functionality is possible today, albeit with
high performance costs and degraged user experience.</p>
<p><code>sendBeacon</code> does not add new privacy considerations. However, implementers should take the following precautions:</p>
<p>The <code>sendBeacon</code> interface provides an asynchronous and non-blocking mechanism for delivery of data. This API can be used to:</p>
<ul>
<li>The user agent should not skip or throttle delivery of beacon data,
as it may lead to loss of critical application data.</li>
<li>The user agent should not store or defer delivery of beacon data indefinitely, as that may expose additional data when delivered - e.g. user's location via new IP address of the device.</li>
<li>Report client-side events to the server. The delivery is prioritized and scheduled by the user agent such that it does not block other interactive work and makes efficient use of system resources.</li>
<li>Report session data when the page transitions to background state or is being unloaded, without blocking the user agent.</li>
<li>Other use cases that require delivery of small payloads and do not expect a response callback.</li>
</ul>
</section>
<section>
<h2>IANA Considerations</h2>
<p>The permanent message header field registry should be updated with the
following registrations ([[RFC3864]]):</p>
<section>
<h2>Beacon-Age</h2>
<dl>
<dt>Header field name</dt>
<dd>Beacon-Age</dd>
<dt>Applicable protocol</dt>
<dd>http</dd>
<dt>Status</dt>
<dd>standard</dd>
<dt>Author/Change controller</dt>
<dd>W3C</dd>
<dt>Specification document</dt>
<dd>
This specification (see <a>Beacon-Age Header Field</a>)
</dd>
</dl>
</section>
<p>Existing methods, such as scripted form-submit, image beacons, and XHR/fetch requests provide similar capabilities, but come with various and costly performance tradeoffs: the requests may be aborted by the user agent unless the developer blocks the user agent from processing other events (e.g. by invoking a synchronous request, or spinning in an empty loop), and the user agent is unable to prioritize and coalesce such requests to optimize use of system resources.</p>
<p>A request initiated by sendBeacon is subject to following properties:</p>
<ul>
<li>If the payload is one of <code>application/x-www-form-urlencoded</code>, <code>multipart/form-data</code>, or <code>text/plain</code>, then the request is a simple request that does not require an additional CORS-preflight; same as scripted form-post or XHR/fetch.</li>
<li>Otherwise, if the payload is a <code>Blob</code> and the resulting <code>Content-Type</code> is not a <a href="https://fetch.spec.whatwg.org/#simple-header">simple header</a>, then a CORS preflight is made and the server must first allow such requests by returning the appropriate set of CORS headers (<code>Access-Control-Allow-Credentials</code>, <code>Access-Control-Allow-Origin</code>, <code>Access-Control-Allow-Headers</code>); same as XHR/fetch.</li>
</ul>
<p>As such, from a privacy and security perspective, the Beacon API is subject to all the same security policies as the current methods in use by developers.</p>
<p>Compared to the alternatives, the sendBeacon does apply two restrictions: there is no callback method, and the payload size may be restricted by the user agent. Otherwise, the sendBeacon API is not subject to any additional restrictions. The user agent should not skip or throttle processing of sendBeacon calls, as they may contain critical application state, events, and analytics data. Similarly, the user agent should not disable sendBeacon when in "incognito" or equivalent mode, both to avoid breaking the application and to avoid leaking that the user is in such mode.</p>
</section>
<section class="appendix">
<h2>Acknowledgments</h2>
Expand Down

0 comments on commit fd52175

Please sign in to comment.