Add cowboy_bstr:capitalize_token/1

For optional header name capitalization. See the guide section about it.

2 files changed, 25 insertions, 0 deletions

diff --git a/guide/internals.md b/guide/internals.md
index 431ca01..8acf75b 100644
--- a/guide/internals.md
+++ b/guide/internals.md
@@ -6,6 +6,30 @@ Architecture
 
 @todo Describe.
 
+Lowercase header names
+----------------------
+
+For consistency reasons it has been chosen to convert all header names
+to lowercase binary strings. This prevents the programmer from making
+case mistakes, and is possible because header names are case insensitive.
+
+This works fine for the large majority of clients. However, some badly
+implemented clients, especially ones found in corporate code or closed
+source products, may not handle header names in a case insensitive manner.
+This means that when Cowboy returns lowercase header names, these clients
+will not find the headers they are looking for.
+
+A simple way to solve this is to create an `onresponse` hook that will
+format the header names with the expected case.
+
+``` erlang
+capitalize_hook(Status, Headers, Body, Req) ->
+    Headers2 = [{cowboy_bstr:capitalize_token(N), V}
+        || {N, V} <- Headers],
+    {ok, Req2} = cowboy_req:reply(State, Headers2, Body, Req),
+    Req2.
+```
+
 Efficiency considerations
 -------------------------
 
diff --git a/guide/toc.md b/guide/toc.md
index 2498b4d..18c16e6 100644
--- a/guide/toc.md
+++ b/guide/toc.md
@@ -51,4 +51,5 @@ Cowboy User Guide
    *  Handler middleware
  *  [Internals](internals.md)
    *  Architecture
+   *  Lowercase header names
    *  Efficiency considerations