From a63fa963b7bd01f1b470bea7c5a2ed326ff760e6 Mon Sep 17 00:00:00 2001
From: Thijs Schreijer <thijs@thijsschreijer.nl>
Date: Sat, 29 Aug 2026 19:39:35 +0200
Subject: feat(headers): dynamically create cononicalized headers

Instead of a static list dynamically add entries in proper casing.
Also allowing to add non-standard ones through `setcanonic`.

closes #442
fixes #440
---
 docs/socket.html | 26 +++++++++++++++++++++++---
 1 file changed, 23 insertions(+), 3 deletions(-)

(limited to 'docs')

diff --git a/docs/socket.html b/docs/socket.html
index 983f1c9..570f6d5 100644
--- a/docs/socket.html
+++ b/docs/socket.html
@@ -65,13 +65,33 @@ whenever the field name is sent out.
 </p>
 
 <p>
-You can obtain the <tt>headers</tt> namespace if case run-time
-modifications are required by running:
+If a lowercase field name is not present as a key,
+<tt>socket.headers.canonic</tt> automatically derives a
+capitalization by uppercasing the first letter of each
+hyphen-separated word (e.g. <tt>x-request-id</tt> becomes
+<tt>X-Request-Id</tt>), and caches the result for later lookups.
+A small set of headers whose canonic capitalization is
+irregular (such as <tt>ETag</tt>, <tt>Content-MD5</tt>,
+<tt>MIME-Version</tt> and <tt>WWW-Authenticate</tt>) are kept as
+explicit entries in the table and are not affected by this rule.
+Because of this, <tt>pairs(socket.headers.canonic)</tt> only
+shows the irregular entries plus any field name already looked
+up or added &mdash; it is not an exhaustive list of every header
+name the library knows how to capitalize.
+</p>
+
+<p>
+You can register a custom canonic capitalization &mdash; for a
+header the automatic rule would not reproduce, such as a custom
+all-caps acronym &mdash; with <tt>socket.headers.setcanonic</tt>:
 </p>
 
 <pre class="example">
 -- loads the headers module
-local headers = require("headers")
+local headers = require("socket.headers")
+
+-- register a custom capitalization
+headers.setcanonic("X-Request-ID")
 </pre>
 
 
-- 
cgit v1.2.3-55-g6feb