Skip to content

Commit

Permalink
Experimentally add problem reporting using piggy-backed Link header f…
Browse files Browse the repository at this point in the history 
…ields (#7)
  • Loading branch information
@reschke
reschke committed Sep 8, 2015
1 parent b280e68 commit b9ec036
Show file tree
Hide file tree
Showing 2 changed files with 181 additions and 13 deletions.
93 changes: 84 additions & 9 deletions draft-reschke-http-oob-encoding-latest.unpg.txt
View file
Expand Up @@ -73,9 +73,14 @@ Table of Contents
3. 'Out-Of-Band' Content Coding
3.1. Overview
3.2. Definitions
3.3. Examples
3.3.1. Basic Example
3.3.2. Example involving an encrypted resource
3.3. Problem Reporting
3.3.1. Server Not Reachable
3.3.2. Resource Not Found
3.3.3. Payload Unusable
3.4. Examples
3.4.1. Basic Example
3.4.2. Example involving an encrypted resource
3.4.3. Example For Problem Reporting
4. Feature Discovery
5. Security Considerations
5.1. Use in Requests
Expand Down Expand Up @@ -202,9 +207,12 @@ Table of Contents

If the client is unable to retrieve the secondary resource's
representation (host can't be reached, non 2xx response status code,
etc.), it can choose an alternate secondary resource (if specified),
or simply retry the request to the origin server without including
"out-of-band" in the Accept-Encoding request header field.
payload failing integrity check, etc.), it can choose an alternate
secondary resource (if specified), or simply retry the request to the
origin server without including "out-of-band" in the Accept-Encoding
request header field. In the latter case, it can be useful to inform
the origin server about what problems were encountered when trying to
access the secondary resource; see Section 3.3 for details.

Note that although this mechanism causes the inclusion of external
content, it will not affect the application-level security properties
Expand All @@ -219,9 +227,45 @@ Table of Contents
declared to vary on that. See Section 7.1.4 of [RFC7231] and Section
2.3 of [RFC7232] for details.

3.3. Examples
3.3. Problem Reporting

3.3.1. Basic Example
When the client fails to obtain the secondary resource, it can be
useful to inform the origin server about the condition. This can be
accomplished by adding a "Link" header field ([RFC5988]) to a
subsequent request to the origin server, detailing the URI of the
secondary resource and the failure reason.

The following link extension relations are defined:

3.3.1. Server Not Reachable

Used in case the server was not reachable.

Link relation:

http://purl.org/NET/linkrel/not-reachable

3.3.2. Resource Not Found

Used in case the server responded, but the object could not be
obtained.

Link relation:

http://purl.org/NET/linkrel/resource-not-found

3.3.3. Payload Unusable

Used in case the the payload could be obtained, but wasn't usable
(for instance, because integrity checks failed).

Link relation:

http://purl.org/NET/linkrel/payload-unusable

3.4. Examples

3.4.1. Basic Example

Client request of primary resource:

Expand Down Expand Up @@ -283,7 +327,7 @@ Table of Contents
In this example, Cache-Control, Content-Length, and Date have been
set/overwritten with data from the primary resource's representation.

3.3.2. Example involving an encrypted resource
3.4.2. Example involving an encrypted resource

Given the example HTTP message from Section 5.4 of [ENCRYPTENC], a
primary resource could use the "out-of-band" encoding to specify just
Expand Down Expand Up @@ -335,6 +379,30 @@ Table of Contents

I am the walrus

3.4.3. Example For Problem Reporting

Client requests primary resource as in Section 3.4.1, but the attempt
to access the secondary resource fails.

Response:

HTTP/1.1 404 Not Found
Date: Thu, 08 September 2015 16:49:00 GMT
Content-Type: text/plain
Content-Length: 20

Resource Not Found

Client retries with the origin server and includes Link header field
reporting the problem:

GET /test HTTP/1.1
Host: www.example.com
Accept-Encoding: gzip, out-of-band
Link: <http://example.net/bae27c36-fa6a-11e4-ae5d-00059a3c7a00>;
rel="http://purl.org/NET/linkrel/resource-not-found"


4. Feature Discovery

New content codings can be deployed easily, as the client can use the
Expand Down Expand Up @@ -381,6 +449,10 @@ Table of Contents
STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005,
<http://www.rfc-editor.org/info/rfc3986>.

[RFC5988] Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/
RFC5988, October 2010,
<http://www.rfc-editor.org/info/rfc5988>.

[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, DOI 10.17487/RFC7159,
March 2014, <http://www.rfc-editor.org/info/rfc7159>.
Expand Down Expand Up @@ -473,6 +545,9 @@ C.1. Changes since draft-reschke-http-oob-encoding-00
usually be needed
(<https://github.com/reschke/oobencoding/issues/6>).

Experimentally add problem reporting using piggy-backed Link header
fields (<https://github.com/reschke/oobencoding/issues/7>).

Appendix D. Acknowledgements

Thanks to Christer Holmberg, Goran Eriksson, John Mattsson, Kevin
Expand Down
101 changes: 97 additions & 4 deletions draft-reschke-http-oob-encoding-latest.xml
View file
Expand Up @@ -235,10 +235,14 @@
</t>
<t>
If the client is unable to retrieve the secondary resource's representation
(host can't be reached, non 2xx response status code, etc.), it can choose
(host can't be reached, non 2xx response status code, payload failing
integrity check, etc.), it can choose
an alternate secondary resource (if specified), or simply retry the
request to the origin server without including "out-of-band" in the
Accept-Encoding request header field.
Accept-Encoding request header field. In the latter case, it can be useful
to inform the origin server about what problems were encountered
when trying to access the secondary resource; see <xref target="problem.reporting"/>
for details.
</t>
<t>
Note that although this mechanism causes the inclusion of external
Expand All @@ -257,8 +261,56 @@
<xref target="RFC7232" x:fmt="of" x:rel="#header.etag"/> for details.
</t>
</section>

<section title="Problem Reporting" anchor="problem.reporting">
<t>
When the client fails to obtain the secondary resource, it can be useful
to inform the origin server about the condition. This can be accomplished
by adding a "Link" header field (<xref target="RFC5988"/>) to a subsequent request to the origin server,
detailing the URI of the secondary resource and the failure reason.
</t>
<t>
The following link extension relations are defined:
</t>

<section title="Server Not Reachable" anchor="rel-not-reachable">
<t>
Used in case the server was not reachable.
</t>
<figure>
<preamble>Link relation:</preamble>
<artwork type="example">
http://purl.org/NET/linkrel/not-reachable</artwork>
</figure>
</section>

<section title="Resource Not Found" anchor="rel-resource-not-found">
<t>
Used in case the server responded, but the object could not be obtained.
</t>
<figure>
<preamble>Link relation:</preamble>
<artwork type="example">
http://purl.org/NET/linkrel/resource-not-found</artwork>
</figure>
</section>

<section title="Payload Unusable" anchor="rel-payload-unusable">
<t>
Used in case the the payload could be obtained, but wasn't usable
(for instance, because integrity checks failed).
</t>
<figure>
<preamble>Link relation:</preamble>
<artwork type="example">
http://purl.org/NET/linkrel/payload-unusable</artwork>
</figure>
</section>

</section>

<section title="Examples">
<section title="Basic Example">
<section title="Basic Example" anchor="basic.example">
<figure>
<preamble>Client request of primary resource:</preamble>
<artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with=" ">
Expand Down Expand Up @@ -385,8 +437,36 @@ Content-Type: text/plain
<x:span anchor="exbody8">I am the walrus</x:span></artwork>
</figure>
</section>
</section>

<section title="Example For Problem Reporting">
<t>
Client requests primary resource as in <xref target="basic.example"/>, but the
attempt to access the secondary resource fails.
</t>
<figure>
<preamble>Response:</preamble>
<artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with=" ">
HTTP/1.1 404 Not Found
Date: Thu, 08 September 2015 16:49:00 GMT
Content-Type: text/plain
Content-Length: <x:length-of target="exbody404"/>

<x:span anchor="exbody404">Resource Not Found
</x:span></artwork>
</figure>
<figure>
<preamble>Client retries with the origin server and includes Link
header field reporting the problem:</preamble>
<artwork type="message/http; msgtype=&#34;request&#34;" x:indent-with=" ">
GET /test HTTP/1.1
Host: www.example.com
Accept-Encoding: gzip, out-of-band
Link: &lt;http://example.net/bae27c36-fa6a-11e4-ae5d-00059a3c7a00>;
rel="http://purl.org/NET/linkrel/resource-not-found"

</artwork></figure>
</section>
</section>
</section>

<section title="Feature Discovery" anchor="feature.discovery">
Expand Down Expand Up @@ -453,6 +533,15 @@ Content-Type: text/plain
<seriesInfo name="RFC" value="3986"/>
</reference>

<reference anchor='RFC5988'>
<front>
<title>Web Linking</title>
<author initials='M.' surname='Nottingham' fullname='M. Nottingham'/>
<date year='2010' month='October' />
</front>
<seriesInfo name='RFC' value='5988'/>
</reference>

<reference anchor='RFC7159'>
<front>
<title>The JavaScript Object Notation (JSON) Data Interchange Format</title>
Expand Down Expand Up @@ -589,6 +678,10 @@ Content-Type: text/plain
usually be needed
(<eref target="https://github.com/reschke/oobencoding/issues/6"/>).
</t>
<t>
Experimentally add problem reporting using piggy-backed Link header fields
(<eref target="https://github.com/reschke/oobencoding/issues/7"/>).
</t>
</section>
</section>

Expand Down

0 comments on commit b9ec036

Please sign in to comment.