Skip to content

Commit 2666784

Browse files
author
Marcos Cáceres
committed
Editorial: fix some ReSpec issues
1 parent 5d10109 commit 2666784

File tree

1 file changed

+21
-27
lines changed

1 file changed

+21
-27
lines changed

index.html

Lines changed: 21 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ <h2>Introduction</h2>
9696

9797
<p>Existing methods (such as synthetic monitoring) provide a partial solution by placing monitoring nodes in predetermined geographic locations, but require additional infrastructure investments, and cannot provide truly global and near real-time availability data for real end users.</p>
9898

99-
<p>Network Error Logging (NEL) addresses this need by defining a mechanism enabling web applications to declare a reporting policy that can be used by the user agent to report network errors for a given origin. A web application opts into using NEL by supplying a <a>NEL</a> HTTP response header field that describes the desired <a>NEL policy</a>. This policy instructs the user agent to log information about requests to that origin, and to attempt to deliver that information to a group of endpoints previously configured using the Reporting API [[!REPORTING]]. As the name implies, NEL reports are primarily used to describe <em>errors</em>. However, in order to determine <em>rates</em> of errors across different client populations, we must also know how many <em>successful</em> requests are occurring; these successful requests can also be reported via the NEL mechanism.</p>
99+
<p>Network Error Logging (NEL) addresses this need by defining a mechanism enabling web applications to declare a reporting policy that can be used by the user agent to report network errors for a given origin. A web application opts into using NEL by supplying a <a>NEL</a> HTTP response header field that describes the desired <a>NEL policy</a>. This policy instructs the user agent to log information about requests to that origin, and to attempt to deliver that information to a group of endpoints previously configured using the [[[REPORTING]]. As the name implies, NEL reports are primarily used to describe <em>errors</em>. However, in order to determine <em>rates</em> of errors across different client populations, we must also know how many <em>successful</em> requests are occurring; these successful requests can also be reported via the NEL mechanism.</p>
100100

101101
<p>For example, if the user agent fails to fetch a resource from <code>https://www.example.com</code> due to an aborted TCP connection, the user agent would queue the following report via the Reporting API:</p>
102102

@@ -129,10 +129,7 @@ <h2>Introduction</h2>
129129
</p>
130130
</section>
131131

132-
<section>
133-
<h2>Conformance requirements</h2>
134-
<p>All diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked non-normative. Everything else in this specification is normative.</p>
135-
<p>The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative parts of this document are to be interpreted as described in [[!RFC2119]].</p>
132+
<section id="conformance">
136133
<p>Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.</p>
137134
<p>Some conformance requirements are phrased as requirements on attributes, methods or objects. Such requirements are to be interpreted as requirements on the user agent.</p>
138135
<p>Conformance requirements phrased as algorithms or specific steps may be implemented in any manner, so long as the end result is equivalent. (In particular, the algorithms defined in this specification are intended to be easy to follow, and not intended to be performant.)</p>
@@ -141,7 +138,7 @@ <h2>Dependencies</h2>
141138
<dl>
142139
<dt>DNS</dt>
143140
<dd>
144-
<p>The following terms are defined in the DNS specification: [[!RFC1034]]</p>
141+
<p>The following terms are defined in the DNS specification: [[RFC1034]]</p>
145142
<ul>
146143
<li><dfn data-cite="!RFC1034#section-3.1">domain name</dfn></li>
147144
<li><dfn data-cite="!RFC1034#section-3.1">domain namespace tree</dfn></li>
@@ -150,7 +147,7 @@ <h2>Dependencies</h2>
150147
</dd>
151148
<dt>Fetch</dt>
152149
<dd>
153-
<p>The following terms are defined in the Fetch specification: [[!FETCH]]</p>
150+
<p>The following terms are defined in the Fetch specification: [[FETCH]]</p>
154151
<ul>
155152
<li><dfn data-cite="!FETCH#concept-request-client">client</dfn></li>
156153
<li><dfn data-cite="!FETCH#cors-preflight-request">CORS-preflight request</dfn></li>
@@ -169,14 +166,14 @@ <h2>Dependencies</h2>
169166
</dd>
170167
<dt>HSTS</dt>
171168
<dd>
172-
<p>The following terms are defined in the HSTS specification: [[!RFC6797]]</p>
169+
<p>The following terms are defined in the HSTS specification: [[RFC6797]]</p>
173170
<ul>
174171
<li><dfn data-cite="!RFC6797#section-8.2">superdomain match</dfn></li>
175172
</ul>
176173
</dd>
177174
<dt>HTML</dt>
178175
<dd>
179-
<p>The following terms are defined in the HTML specification: [[!HTML]]</p>
176+
<p>The following terms are defined in the HTML specification: [[HTML]]</p>
180177
<ul>
181178
<li><dfn data-cite="!HTML#navigate" data-lt="navigation">navigate</dfn></li>
182179
<li><dfn data-cite="!HTML#navigator.online"><code>navigator.onLine</code></dfn></li>
@@ -185,14 +182,13 @@ <h2>Dependencies</h2>
185182
</dd>
186183
<dt>HTTP</dt>
187184
<dd>
188-
<p>The following terms are defined in the HTTP specification: [[!RFC7230]], [[!RFC7231]], [[RFC7232]], [[!RFC7234]]</p>
185+
<p>The following terms are defined in the HTTP specification: [[RFC7230]], [[RFC7231]], [[RFC7232]], [[RFC7234]]</p>
189186
<ul>
190187
<li><dfn data-cite="!RFC7231#section-6.3.1" data-lt="200 response">200 status code</dfn></li>
191188
<li><dfn data-cite="!RFC7231#section-6.5" data-lt="4xx">4xx status code</dfn></li>
192189
<li><dfn data-cite="!RFC7231#section-6.6" data-lt="5xx">5xx status code</dfn></li>
193190
<li><dfn data-cite="RFC7232#section-2.3"><code>ETag</code></dfn></li>
194191
<li><dfn data-cite="RFC7232#section-3.2"><code>If-None-Match</code></dfn></li>
195-
<li><dfn data-cite="!RFC7234">local cache</dfn></li>
196192
<li><dfn data-cite="!RFC7230#section-6.3">persistent connections</dfn></li>
197193
<li><dfn data-cite="!RFC7230#section-2.1" data-lt="requests">request</dfn></li>
198194
<li><dfn data-cite="!RFC7231#section-4">request method</dfn></li>
@@ -204,28 +200,28 @@ <h2>Dependencies</h2>
204200
</dd>
205201
<dt>HTTP JSON field values</dt>
206202
<dd>
207-
<p>The following terms are defined in the HTTP-JFV specification: [[!HTTP-JFV]]</p>
203+
<p>The following terms are defined in the HTTP-JFV specification: [[HTTP-JFV]]</p>
208204
<ul>
209205
<li><dfn data-cite="!HTTP-JFV#json-field-value">json-field-value</dfn></li>
210206
</ul>
211207
</dd>
212208
<dt>JSON</dt>
213209
<dd>
214-
<p>The following terms are defined in the JSON specification: [[!RFC7159]]</p>
210+
<p>The following terms are defined in the JSON specification: [[RFC7159]]</p>
215211
<ul>
216212
<li><dfn data-cite="!RFC7159#section-4">JSON object</dfn></li>
217213
</ul>
218214
</dd>
219215
<dt>Referrer Policy</dt>
220216
<dd>
221-
<p>The following terms are defined in the Referrer Policy specification: [[!REFERRER-POLICY]]</p>
217+
<p>The following terms are defined in the Referrer Policy specification: [[REFERRER-POLICY]]</p>
222218
<ul>
223219
<li><dfn data-cite="!REFERRER-POLICY#referrer-policy">referrer policy</dfn></li>
224220
</ul>
225221
</dd>
226222
<dt>Reporting API</dt>
227223
<dd>
228-
<p>The following terms are defined in the Reporting API specification: [[!REPORTING]]</p>
224+
<p>The following terms are defined in the Reporting API specification: [[REPORTING]]</p>
229225
<ul>
230226
<li><dfn data-cite="!REPORTING#endpoint-group">endpoint group</dfn></li>
231227
<li><dfn data-cite="!REPORTING#report" data-lt="reports">report</dfn></li>
@@ -236,14 +232,14 @@ <h2>Dependencies</h2>
236232
</dd>
237233
<dt>Resource Timing</dt>
238234
<dd>
239-
<p>The following terms are defined in the Resource Timing specification: [[!RESOURCE-TIMING-2]]</p>
235+
<p>The following terms are defined in the Resource Timing specification: [[RESOURCE-TIMING-2]]</p>
240236
<ul>
241237
<li><dfn data-cite="!RESOURCE-TIMING-2#dom-performanceresourcetiming-nexthopprotocol">network protocol</dfn></li>
242238
</ul>
243239
</dd>
244240
<dt>Secure Contexts</dt>
245241
<dd>
246-
<p>The following terms are defined in the Secure Contexts specification: [[!SECURE-CONTEXTS]]</p>
242+
<p>The following terms are defined in the Secure Contexts specification: [[SECURE-CONTEXTS]]</p>
247243
<ul>
248244
<li>the <dfn data-cite="!SECURE-CONTEXTS#is-origin-trustworthy">"Is
249245
origin potentially trustworthy?"</dfn> algorithm</li>
@@ -252,7 +248,7 @@ <h2>Dependencies</h2>
252248
</dd>
253249
<dt>URL</dt>
254250
<dd>
255-
<p>The following terms are defined in the URL specification: [[!URL]]</p>
251+
<p>The following terms are defined in the URL specification: [[URL]]</p>
256252
<ul>
257253
<li><dfn data-cite="!URL#concept-url-fragment">fragment</dfn></li>
258254
<li><dfn data-cite="!URL#concept-host">host</dfn></li>
@@ -275,8 +271,8 @@ <h2>Network requests</h2>
275271
</p>
276272

277273
<p>
278-
If the user agent can service a <a>request</a> out of a <a>local
279-
cache</a>, that <a>request</a> MUST NOT result in a <a>network
274+
If the user agent can service a <a>request</a> out of a local
275+
cache, that <a>request</a> MUST NOT result in a <a>network
280276
request</a>.
281277
</p>
282278

@@ -411,8 +407,7 @@ <h2>Network errors</h2>
411407
<h2>Network error reports</h2>
412408

413409
<p>
414-
A <dfn data-lt="network error reports">network error report</dfn> is a <a
415-
data-cite="!REPORTING">Reporting API</a> <a>report</a> that describes a
410+
A <dfn data-lt="network error reports">network error report</dfn> is a [[[REPORTING]]] <a>report</a> that describes a
416411
<a>network error</a>.
417412
</p>
418413

@@ -1217,7 +1212,7 @@ <h2>Extract response headers</h2>
12171212

12181213
<ol class="algorithm">
12191214
<li>
1220-
<p><a data-cite="!REPORTING#queue-report">Queue the report for delivery</a> via the Reporting API. [[!REPORTING]]</p>
1215+
<p><a data-cite="!REPORTING#queue-report">Queue the report for delivery</a> via the Reporting API. [[REPORTING]]</p>
12211216

12221217
<dl>
12231218
<dt>type</dt>
@@ -1433,7 +1428,7 @@ <h2>Sample Network Error Reports</h2>
14331428
This section contains example <a>network error</a> <a>reports</a> the
14341429
user agent might queue when a network error is encountered for an
14351430
<a>origin</a> with a registered <a>NEL policy</a>. We show the full
1436-
report payload that would be created by the [[!REPORTING]] API when
1431+
report payload that would be created by the [[REPORTING]] API when
14371432
uploading the report; the payload's <code>body</code> field contains the
14381433
<a>network error</a> <a>report body</a>.
14391434
</p>
@@ -1632,7 +1627,7 @@ <h2>Monitoring cache validation</h2>
16321627
original resource in its local cache, and includes its version in a
16331628
<a><code>If-None-Match</code></a> request header. The server checks
16341629
this version, notices that it is still current, and sends a
1635-
<a>304</a> response informing the user agent that its cached copy of
1630+
`304` response informing the user agent that its cached copy of
16361631
the resource is still valid. The user agent will generate the
16371632
following report:
16381633
</p>
@@ -1991,7 +1986,7 @@ <h2>Privacy Considerations</h2>
19911986
<li>Refuse to process Set-Cookie response headers when delivering network error reports.</li>
19921987
</ul>
19931988

1994-
<p>When deploying NEL the developer SHOULD consider privacy implications of NEL reports delivered to the specified collectors. For example, reports may contain URLs with sensitive data (e.g. "Capability URLs") that may need special precautions (see [[!CAPABILITY-URLS]]), and may require the developer to operate their own NEL collectors to prevent reporting of such URLs to third parties.</p>
1989+
<p>When deploying NEL the developer SHOULD consider privacy implications of NEL reports delivered to the specified collectors. For example, reports may contain URLs with sensitive data (e.g. "Capability URLs") that may need special precautions (see [[CAPABILITY-URLS]]), and may require the developer to operate their own NEL collectors to prevent reporting of such URLs to third parties.</p>
19951990
</section>
19961991

19971992
<section>
@@ -2014,7 +2009,6 @@ <h2><code>NEL</code></h2>
20142009
</dl>
20152010
</section>
20162011
</section>
2017-
20182012
<section class="appendix">
20192013
<h2>Acknowledgments</h2>
20202014
<p>This document reuses text from the [[CSP]] and [[RFC6797]] specification, as permitted by the licenses of those specifications. Additionally, sincere thanks to Julia Tuttle, Chris Bentzel, Todd Reifsteck, Aaron Heady, and Mark Nottingham for their helpful comments and contributions to this work.</p>

0 commit comments

Comments
 (0)