From 427a276ef2f2042ad312e0260535cbb4696f9072 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Tue, 23 Jan 2024 13:15:55 +0100
Subject: Update the guide with range requests support

Also update the list of headers cowboy_rest might set
and tweak a small number of other items.
---
 doc/src/guide/rest_handlers.asciidoc | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

(limited to 'doc/src/guide/rest_handlers.asciidoc')

diff --git a/doc/src/guide/rest_handlers.asciidoc b/doc/src/guide/rest_handlers.asciidoc
index baf8e6a..19a9859 100644
--- a/doc/src/guide/rest_handlers.asciidoc
+++ b/doc/src/guide/rest_handlers.asciidoc
@@ -84,6 +84,8 @@ if it is undefined, moving directly to the next step. Similarly,
 | multiple_choices       | `false`
 | options                | `ok`
 | previously_existed     | `false`
+| ranges_provided        | skip
+| range_satisfiable      | `true`
 | rate_limited           | `false`
 | resource_exists        | `true`
 | service_available      | `true`
@@ -97,8 +99,9 @@ As you can see, Cowboy tries to move on with the request whenever
 possible by using well thought out default values.
 
 In addition to these, there can be any number of user-defined
-callbacks that are specified through `content_types_accepted/2`
-and `content_types_provided/2`. They can take any name, however
+callbacks that are specified through `content_types_accepted/2`,
+`content_types_provided/2` or `ranges_provided/2`. They can take
+any name (except `auto` for range callbacks), however
 it is recommended to use a separate prefix for the callbacks of
 each function. For example, `from_html` and `to_html` indicate
 in the first case that we're accepting a resource given as HTML,
@@ -113,9 +116,10 @@ Req object directly. The values are defined in the following table:
 [cols="<,<",options="header"]
 |===
 | Key        | Details
-| media_type | The content-type negotiated for the response entity.
-| language   | The language negotiated for the response entity.
-| charset    | The charset negotiated for the response entity.
+| media_type | The content-type negotiated for the response entity
+| language   | The language negotiated for the response entity
+| charset    | The charset negotiated for the response entity
+| range      | The range selected for the ranged response
 |===
 
 They can be used to send a proper body with the response to a
@@ -129,11 +133,16 @@ of the REST code. They are listed in the following table.
 [cols="<,<",options="header"]
 |===
 | Header name      | Details
+| accept-ranges    | Range units accepted by the resource
+| allow            | HTTP methods allowed by the resource
 | content-language | Language used in the response body
+| content-range    | Range of the content found in the response
 | content-type     | Media type and charset of the response body
 | etag             | Etag of the resource
 | expires          | Expiration date of the resource
 | last-modified    | Last modification date for the resource
 | location         | Relative or absolute URI to the requested resource
+| retry-after      | Delay or time the client should wait before accessing the resource
 | vary             | List of headers that may change the representation of the resource
+| www-authenticate | Authentication information to access the resource
 |===
-- 
cgit v1.2.3

