Skip to content

Commit 66a69ac

Browse files
noamrnoamr
committed
Add detailed example for iframe quota
1 parent b72c664 commit 66a69ac

File tree

1 file changed

+124
-17
lines changed

1 file changed

+124
-17
lines changed

‎fetch.bs

Lines changed: 124 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -6857,13 +6857,13 @@ cross-origin or cross-agent subframes, each reserving 8 kibibytes.
68576857

68586858
<p>The top-level {{Document}}, and subsequently its subframes, can control how much of their quota
68596859
is delegates to cross-origin/cross-agent subframes, by using {{PermissionsPolicy}}.
6860-
By default, {{PermissionPolicy/"deferred-fetch-minimal"}} is enabled for any origin, while
6861-
{{PermissionPolicy/"deferred-fetch"}} is enabled for the top-level document's origin only.
6862-
By relaxing the {{PermissionPolicy/"deferred-fetch"}} policy for particular origins and subframes,
6860+
By default, {{PermissionsPolicy/"deferred-fetch-minimal"}} is enabled for any origin, while
6861+
{{PermissionsPolicy/"deferred-fetch"}} is enabled for the top-level document's origin only.
6862+
By relaxing the {{PermissionsPolicy/"deferred-fetch"}} policy for particular origins and subframes,
68636863
the top-level document can allocate 64 kibibytes to those subframes. Similarly, by restricting the
6864-
{{PermissionPolicy/"deferred-fetch-minimal"}} policy for a particular origin or subframe, the
6864+
{{PermissionsPolicy/"deferred-fetch-minimal"}} policy for a particular origin or subframe, the
68656865
document can prevent the iframe from reserving the 8 kibibytes it would receive by default. By
6866-
disabling {{PermissionPolicy/"deferred-fetch-minimal"}} for the top-level document itself, the
6866+
disabling {{PermissionsPolicy/"deferred-fetch-minimal"}} for the top-level document itself, the
68676867
entire 128 kibibytes delegated quota is collected back into the main pool of 640 kibibytes.
68686868

68696869
<p>Out of the allocated quota for a {{Document}}, only 64 kibibytes can be used concurrently for the
@@ -6907,19 +6907,126 @@ calls would succeed and the last one would throw.
69076907
fetchLater("https://a.example.com", {body: a_12kb_body});
69086908
</code></pre>
69096909

6910-
<p>To make the previous example not throw, the top-level {{Document}} needs to delegate some of its
6911-
quota to <code>https://frame.example.com</code>, for example by serving the following header:
6912-
<pre><code>Permissions-Policy: deferred-fetch=(self "https://frame.example.com")</code></pre>
6910+
<p>To make the previous example not throw, the top-level {{Document}} can delegate some of its quota
6911+
to <code>https://frame.example.com</code>, for example by serving the following header:
6912+
<pre><code class=lang-http>Permissions-Policy: deferred-fetch=(self "https://frame.example.com")</code></pre>
6913+
6914+
<p>The following tables illustrates how quota is distributed to different iframes, each table
6915+
representing a different <a for=/>top-level traversable</a> ("tab").
6916+
6917+
<p>For a tree with its top-level <code>Permissions-Policy</code> header set to
6918+
<code class=lang-http>deferred-fetch=(self "https://ok.example.com")</code>:
6919+
6920+
<table>
6921+
<tr>
6922+
<th>Window name
6923+
<th>Parent
6924+
<th>Initial origin
6925+
<th>Current origin
6926+
<th>Quota
6927+
<tr>
6928+
<td><code>top</code>
6929+
<td><code>null</code>
6930+
<td><code>https://me.example.com</code>
6931+
<td><code>https://me.example.com</code>
6932+
<td>384kb (512kb - 64kb - 64kb). <code>d</code> and frame <code>g</code> were granted
6933+
64kb each, even though for <code>g</code> this quota ended up being unavilable.
6934+
<tr>
6935+
<td><code>a</code>
6936+
<td><code>top</code>
6937+
<td><code>https://me.example.com</code>
6938+
<td><code>https://me.example.com</code>
6939+
<td>Shared with <code>top</code>'s quota.
6940+
<tr>
6941+
<td><code>b</code>
6942+
<td><code>a</code>
6943+
<td><code>https://x.example.com</code>
6944+
<td><code>https://x.example.com</code>
6945+
<td>8kb, due to the default {{PermissionsPolicy/"deferred-fetch-minimal"}} policy.
6946+
<tr>
6947+
<td><code>c</code>
6948+
<td><code>top</code>
6949+
<td><code>https://x.example.com</code>
6950+
<td><code>https://x.example.com</code>
6951+
<td>8kb, due to the default {{PermissionsPolicy/"deferred-fetch-minimal"}} policy.
6952+
<tr>
6953+
<td><code>d</code>
6954+
<td><code>top</code>
6955+
<td><code>https://ok.example.com</code>
6956+
<td><code>https://ok.example.com</code>
6957+
<td>64kb, due to the {{PermissionsPolicy/"deferred-fetch"}} policy.
6958+
<tr>
6959+
<td><code>e</code>
6960+
<td><code>d</code>
6961+
<td><code>https://x.example.com</code>
6962+
<td><code>https://x.example.com</code>
6963+
<td>0, as its parent doesn't share the quota with the top-level document.
6964+
<tr>
6965+
<td><code>f</code>
6966+
<td><code>d</code>
6967+
<td><code>https://me.example.com</code>
6968+
<td><code>https://me.example.com</code>
6969+
<td>Shared with <code>top</code>'s quota.
6970+
<tr>
6971+
<td><code>g</code>
6972+
<td><code>top</code>
6973+
<td><code>https://ok.example.com</code>
6974+
<td><code>https://x.example.com</code>
6975+
<td>0, as the reserved quota when navigating doesn't match the current {{PermissionsPolicy}}.
6976+
<tr>
6977+
<td><code>h</code>
6978+
<td><code>top</code>
6979+
<td><code>https://ok.example.com</code>
6980+
<td><code>https://me.example.com</code>
6981+
<td>Shared with <code>top</code>'s quota.
6982+
</table>
6983+
6984+
<p>For a tree with its top-level <code>Permissions-Policy</code> header set to
6985+
<code class=lang-http>deferred-fetch-minimal=(); deferred-fetch=(self https://ok.example.com)</code>:
6986+
6987+
<table>
6988+
<tr>
6989+
<th>Window name
6990+
<th>Parent
6991+
<th>Initial origin
6992+
<th>Current origin
6993+
<th>Quota
6994+
<tr>
6995+
<td><code>top</code>
6996+
<td><code>null</code>
6997+
<td><code>https://me.example.com</code>
6998+
<td><code>https://me.example.com</code>
6999+
<td>576kb (640kb - 64kb). <code>c</code> was granted 64kb. Since {{PermissionsPolicy/"deferred-fetch-minimal"}}
7000+
was explicitly disabled, the initial top-level quota is 640kb instead of 512kb.
7001+
<tr>
7002+
<td><code>a</code>
7003+
<td><code>top</code>
7004+
<td><code>https://me.example.com</code>
7005+
<td><code>https://me.example.com</code>
7006+
<td>Shared with <code>top</code>'s quota.
7007+
<tr>
7008+
<td><code>b</code>
7009+
<td><code>a</code>
7010+
<td><code>https://x.example.com</code>
7011+
<td><code>https://x.example.com</code>
7012+
<td>0, due to the {{PermissionsPolicy/"deferred-fetch-minimal"}} being explicitly disabled.
7013+
<tr>
7014+
<td><code>c</code>
7015+
<td><code>top</code>
7016+
<td><code>https://ok.example.com</code>
7017+
<td><code>https://ok.example.com</code>
7018+
<td>64kb, due to the {{PermissionsPolicy/"deferred-fetch"}} policy.
7019+
</table>
69137020

69147021
</div>
69157022

69167023

69177024
<p>This specification defined a <a>policy-controlled feature</a> identified by the string
6918-
<dfn for=PermissionPolicy enum-value>"deferred-fetch"</dfn>. Its
7025+
<dfn for=PermissionsPolicy enum-value>"deferred-fetch"</dfn>. Its
69197026
<a for="policy-controlled feature">default allowlist</a> is "<code>self</code>".
69207027

69217028
<p>This specification defined a <a>policy-controlled feature</a> identified by the string
6922-
<dfn for=PermissionPolicy enum-value>"deferred-fetch-minimal"</dfn>. Its
7029+
<dfn for=PermissionsPolicy enum-value>"deferred-fetch-minimal"</dfn>. Its
69237030
<a for="policy-controlled feature">default allowlist</a> is "<code>*</code>".
69247031

69257032
<p>The <dfn>optional subframe deferred-fetch quota</dfn> is 64 kibibytes.
@@ -6971,14 +7078,14 @@ quota to <code>https://frame.example.com</code>, for example by serving the foll
69717078

69727079
<li><p>If <var>otherDocument</var> is not
69737080
<a>allowed to use</a> the <a>policy-controlled feature</a>
6974-
{{PermissionPolicy/"deferred-fetch"}}, then return 0.
7081+
{{PermissionsPolicy/"deferred-fetch"}}, then return 0.
69757082

69767083
<li>
69777084
<p>Set <var>quota</var> be 640 kibibytes.
69787085
<p class="note allow-2119">640kb should be enough for everyone.
69797086

69807087
<li><p>If <var>otherDocument</var> is <a>allowed to use</a> the
6981-
<a>policy-controlled feature</a> {{PermissionPolicy/"deferred-fetch-minimal"}}, then
7088+
<a>policy-controlled feature</a> {{PermissionsPolicy/"deferred-fetch-minimal"}}, then
69827089
decrement <var>quota</var> by <a>deferred-fetch delegated quota</a>.
69837090
</ol>
69847091

@@ -7001,14 +7108,14 @@ quota to <code>https://frame.example.com</code>, for example by serving the foll
70017108
<li><p>If <var>otherContainer</var>'s <a>subframe reserved deferred-fetch quota</a> is
70027109
<a>optional subframe deferred-fetch quota</a>, and <var>otherDocument</var> is
70037110
<a>allowed to use</a> the <a>policy-controlled feature</a>
7004-
{{PermissionPolicy/"deferred-fetch"}}, then increment <var>quota</var> by
7111+
{{PermissionsPolicy/"deferred-fetch"}}, then increment <var>quota</var> by
70057112
<a>optional subframe deferred-fetch quota</a>.
70067113

70077114
<li><p>Otherwise, if <var>otherContainer</var>'s
70087115
<a>subframe reserved deferred-fetch quota</a> is
70097116
<a>minimal subframe deferred-fetch quota</a> and <var>otherDocument</var>
70107117
is <a>allowed to use</a> the <a>policy-controlled feature</a>
7011-
{{PermissionPolicy/"deferred-fetch-minimal"}}, then increment <var>quota</var> by
7118+
{{PermissionsPolicy/"deferred-fetch-minimal"}}, then increment <var>quota</var> by
70127119
<a>minimal subframe deferred-fetch quota</a>.
70137120
</ol>
70147121
</ol>
@@ -7052,7 +7159,7 @@ quota to <code>https://frame.example.com</code>, for example by serving the foll
70527159
<p>To <dfn export>reserve deferred-fetch quota</dfn> for a <a>navigable container</a>
70537160
<var>container</var> given an <a for=/>origin</a> <var>originToNavigateTo</var>:
70547161

7055-
<p class=note>This is called when the container document and the document that initiated the
7162+
<p class=note>This is called when <var>container</var> and the document that initiated the
70567163
navigation (the "source document") <a>share deferred-fetch quota</a>. It potentially
70577164
reserves either 64kb or 8kb of quota for the frame, if it doesn't <a>share deferred-fetch quota</a>
70587165
with its parent and the permissions policy allow. It is not observable to the cotnainer document
@@ -7063,7 +7170,7 @@ shared.
70637170

70647171
<ol>
70657172
<li><p>If the <a data-lt="define an inherited policy for feature in container">inherited policy</a>
7066-
for {{PermissionPolicy/"deferred-fetch"}}, <var>container</var> and <var>originToNavigateTo</var>
7173+
for {{PermissionsPolicy/"deferred-fetch"}}, <var>container</var> and <var>originToNavigateTo</var>
70677174
is <code>Enabled</code>, and the <a>available deferred-fetch quota</a> for
70687175
<var>container</var>'s <a>container document</a> is equal or greater than
70697176
<a>optional subframe deferred-fetch quota</a>, then set <var>container</var>'s
@@ -7072,7 +7179,7 @@ shared.
70727179
<li>
70737180
<p>Otherwise, if the
70747181
<a data-lt="define an inherited policy for feature in container">inherited policy</a> for
7075-
{{PermissionPolicy/"deferred-fetch-minimal"}}, <var>container</var> and
7182+
{{PermissionsPolicy/"deferred-fetch-minimal"}}, <var>container</var> and
70767183
<var>originToNavigateTo</var> is <code>Enabled</code>, and <var>container</var>'s
70777184
<a>node document</a> and <var>container</var>'s <a>node navigable</a>'s
70787185
<a for=navigable>top-level traversable</a>'s <a>active document</a>

0 commit comments

Comments
 (0)