└── README.md


/README.md:
--------------------------------------------------------------------------------
 1 | # Archive of "Transfer Size Policy"
 2 | 
 3 | **This incubation has been archived and no longer being persued (see [#19](https://github.com/WICG/transfer-size/issues/19)). It may restart if there is renewed insterest.**
 4 | 
 5 | Goal: enable developers to set and enforce limits on network usage by nested contexts (i.e. iframes).
 6 | 
 7 | Today the top-level frame is unable to audit or enforce size limits on resources used by a nested context. For example, the developer may take great care to optimize their assets to fit within a specific quota, but the moment they add a third party resource that uses (or injects) a nested context, they have no way to track or enforce limits on the resulting size.
 8 | 
 9 | In practice, this can result in mis{behaving, configured} parties fetching large amounts of data, which violate site owners expectations and harm the user experience. To address this, frames could trigger an event once they've consumed at least a specified number of bytes over the network. The page could then handle the event in any way it chooses, such as logging it, displaying a notice to the user, [pausing](https://github.com/jkarlin/pause-frame) it, unloading it, etc. There might even be a future API to cancel all current and future network requests for a frame as a response.
10 | 
11 | Here is an example which limits an iframe to 300KB total:
12 | 
13 | ```html
14 |   <script>
15 |     function onBigFrame(event) {
16 |       console.log("Frame id: " + event.target.id + " exceeded its threshold bytes in category: " + event.category);
17 |     }
18 |   </script>
19 | 
20 |   <iframe id="foo" ontransferexceeded="onBigFrame(event)" transfersize="300" src="...">
21 | ```
22 | 
23 | Here is an example that limits the total size of the page to 500KB, of which CSS can use 50KB max:
24 | ```
25 |   <iframe id="foo" ontransferexceeded="onBigFrame(event)" transfersize="style:50, total:500" src="...">
26 | ```
27 | 
28 | And here is an example that only limits the size of videos on the frame to 10MB:
29 | ```
30 |   <iframe id="foo" ontransferexceeded="onBigFrame(event)" transfersize="video:10240" src="...">
31 | ```
32 | 
33 | To see a list of resource types that can be limited, see the Fetch spec's [request-destination](https://fetch.spec.whatwg.org/#concept-request-destination) section.
34 | 
35 | Transfer Size Policy can also be configured via response headers. This is especially useful if third-party script creates the frame such that you can't add the attribute to the frame yourself. In this example, the default threshold for a frame is 100KB, the site's origin is unrestricted, and \*.example.com is limited to 500KB and 50KB of style:
36 | 
37 | ```http
38 |   transfersizes: {"default":"100", "self":"*", "*.example.com":"style:50, total:500"}
39 | ```
40 | 
41 | and in your script:
42 | ```javascript
43 | document.ontransferexceeded=onBigFrame;
44 | ```
45 | 
46 | 
47 | ## Use Cases
48 | * Enforcing size policies on content, such as AMP's 50,000 byte limit on CSS
49 | * Logging how often your own site grows larger than desired
50 | * Monitoring (or even enforcing policy upon) how often ads get too large
51 | 
52 | ## Details
53 | Each frame with a `transfersize` will count the number of over-the-wire bytes that it and its child frames (transitively) receive from requests that utilize the network (cached responses are not counted). Once a threshold is crossed, the bubbling `transferexceeded` event (a new event type which includes the exceeded threshold and resource category ) is fired on the frame element in the parent frame.
54 | 
55 | If any of the network bytes are from origins other than the embedding frame's origin, a random pad is added to `transfersize` so as not to reveal the exact size of the resources in the frame.
56 | 
57 | There will be a cap on the number of `transferexceeded` events that will be fired per top-level pageload in order to help [preserve privacy](#Privacy-&-Security).
58 | 
59 | ## Headers and IFrame Attribute Conflict Resolution
60 | If both headers a transfersize attribute apply to a frame, the policies are merged such that the most restrictive policy wins.
61 | 
62 | ## Response
63 | It is up to the event handler to determine what to do about the frame exceeding its set size. Examples include:
64 | 
65 |  * Logging that the frame exceeded its threshold
66 |  * [Pausing](https://github.com/jkarlin/pause-frame) the frame
67 |  * Unloading the frame
68 |  * Informing the user
69 | 
70 | ## Privacy & Security
71 | According to the [same origin policy](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy), it should not be possible to determine the response size of a cross-origin resource. It's impossible for this API to exist and not leak some amount of size information. In particular, it leaks information about the full size of a page. The best we can do is to limit the leak to as small amount as is practically possible. That is what is done for other APIs that leak size information. 
72 | 
73 | There are two mitigations to help minimize size leakage:
74 |  1. Frames with network responses that are cross-origin with respect to the embedding page have a random amount of bytes added to that component of their `transfersize`. The developer can be certain that the `transferexceeded` event will only fire if at least the threshold bytes were observed, but it may have been even more in a cross-origin situation.
75 |  1. There is a cap on the number of `transferexceeded` events that can be fired per top-level page load to stop adversaries from taking lots of samples in order to statistically defeat the random padding. (e.g., 10-100)
76 |  
77 | Specifics about the random pad distribution and the size of the event cap will be provided in the specification.
78 | 
79 | ---
80 | 
81 | - Discuss: https://github.com/WICG/content-size/issues
82 | 


--------------------------------------------------------------------------------