HTTP::XSHeaders(3)

💖 HTTP::XSHeaders 💖

okay so bestie, buckle up — this is the Perl manual page for HTTP::XSHeaders, from the User Contributed Perl Documentation section (because obviously the community wrote this one, it's giving collaborative main character energy ✨).

Version: 1.000001 🎀

---

🌸 SYNOPSIS 🌸

# load once
use HTTP::XSHeaders;

# keep using HTTP::Headers or HTTP::Headers::Fast as you wish

literally that's it. one use line and you're slaying. 💅

---

🚨 ALPHA RELEASE 🚨

ngl bestie, this is a work in progress. Once everyone feels it's stable, the version gets bumped to 1.0. Until then? Feel free to use it, try it, and submit tickets — but you're doing this at your own risk. 🫶

---

✨ DESCRIPTION ✨

By loading HTTP::XSHeaders anywhere, you replace any usage of HTTP::Headers and HTTP::Headers::Fast with a fast C implementation. That's the whole trick — you don't have to change a thing. 😭

You can keep using HTTP::Headers and HTTP::Headers::Fast and any other module that depends on them exactly like you did before. It's just faster now. no cap. 🏎️

Since version 0.400000, HTTP::XSHeaders is considered Thread-Safe. 👑

---

🔥 WHY 🔥

Okay so storytime. 📖

First there was HTTP::Headers. It's good, stable, and ubiquitous. However — and I say this with love — it's slow. 💀

Along came HTTP::Headers::Fast. Gooder, stable, and used internally by Plack, so you know it means business. 💼

Not fast enough though, so they implemented an XS version of it, released under the name HTTP::Headers::Fast::XS. It was a successful experiment. But we thought we could do better. ✨

HTTP::XSHeaders provides a complete rework of the headers library with the intent of being fast, lean, and clear. It does not attempt to implement the original algorithm — instead it uses its own C-level implementation with an interface that's mostly compatible with both HTTP::Headers and HTTP::Headers::Fast.

This module attempts to replace HTTP::Headers, HTTP::Headers::Fast, and the XS implementation of it, HTTP::Headers::Fast::XS. We're trying to keep developing this module and perhaps deprecate HTTP::Headers::Fast::XS. 👀

---

🦋 COMPATIBILITY 🦋

So while we keep compatibility with the interfaces of HTTP::Headers and HTTP::Headers::Fast, we've taken the liberty to make several changes that were deemed reasonable and sane:

• Aligning in as_string method

The as_string method does weird stuff in order to keep the original indentation. This is unnecessary and unhelpful. We simply add one space as indentation after the first newline. 🎀

• Normalisation of header names

When a given header is one of the standard HTTP headers, we convert it to the standard casing; otherwise, we normalise it by:

• Converting each underscore to a hyphen.
• Converting the first letter of each word to uppercase.
• Converting the rest of the letters of each word to lowercase.

For example:

• Accept-Encoding => Accept-Encoding
• www-authenticate => WWW-Authenticate (notice the weird standard case for WWW 👀)
• my_header => My-Header

• Literal header names using leading colon are not supported

Following the previous item, we don't treat an initial colon character in any special way. 🙈

• $TRANSLATE_UNDERSCORE is not supported

$TRANSLATE_UNDERSCORE (which controls whether underscores are translated or not) is not supported. It's barely documented (or isn't at all), it isn't used by anything on CPAN, nor can we find any use-case other than the tests. So instead, we always convert underscores to dashes. 💅

• Storable is loaded but not used

Both HTTP::Headers and HTTP::Headers::Fast use Storable for cloning. While HTTP::Headers loads it automatically, HTTP::Headers::Fast loads it lazily.

Since we override both, we load Storable always. However, we do not use it for cloning — instead we implemented our own C-level struct cloning. 😤

---

⚡ BENCHMARKS ⚡

here's the receipts, bestie 📊 — HTTP::Headers 6.05, HTTP::Headers::Fast 0.19, HTTP::XSHeaders 0.200000:

-- as_string
Implementation  Time
xsheaders       0.00468778222396934
fast            0.0964434631535363
orig            0.105793242864311

-- as_string_without_sort
Implementation            Time
xsheaders_as_str          0.00475378949036912
xsheaders_as_str_wo       0.00484256407093758
fast_as_str               0.0954295831126767
fast_as_str_wo            0.0736790240349744
orig                      0.105823918835043

-- get_content_length
Implementation  Time
xsheaders       0.0105355231679
fast            0.0121647090348415
orig            0.0574727505777773

-- get_date
Implementation  Time
xsheaders       0.077750453123065
fast            0.0826203668485442
orig            0.101090469267193

-- get_header
Implementation  Time
xsheaders       0.00505807073565111
fast            0.0612525710276364
orig            0.0820842156588862

-- push_header
Implementation  Time
xsheaders       0.00271070907120684
fast            0.0178986201816726
orig            0.0242003530752845

-- push_header_many
Implementation  Time
xsheaders       0.00426636619488888
fast            0.0376390665501822
orig            0.0503843871625857

-- scan
Implementation  Time
xsheaders       0.0142865143596716
fast            0.061759048917916
orig            0.0667217048891246

-- set_date
Implementation  Time
xsheaders       0.114970609213125
fast            0.130542749562301
orig            0.168121156055091

-- set_header
Implementation  Time
xsheaders       0.0456117003715809
fast            0.0868535344701981
orig            0.135920422020881

like... look at those numbers. it ate. 🔥👑

---

💜 METHODS/ATTRIBUTES 💜

These match the API described in HTTP::Headers and HTTP::Headers::Fast, with the caveats described under COMPATIBILITY. ⚠️

Please see those modules for documentation on what these methods and attributes are — we're not re-explaining them here, iykyk. 🧚

🎀 new

🎀 as_string

🎀 as_string_without_sort

🎀 authorization

🎀 authorization_basic

🎀 clear

🎀 clone

🎀 content_encoding

🎀 content_is_html

🎀 content_is_xhtml

🎀 content_is_xml

🎀 content_language

🎀 content_length

🎀 content_type

🎀 content_type_charset

🎀 date

🎀 expires

🎀 from

🎀 header

🎀 header_field_names

🎀 if_modified_since

🎀 if_unmodified_since

🎀 init_header

🎀 last_modified

🎀 proxy_authenticate

🎀 proxy_authorization

🎀 proxy_authorization_basic

🎀 push_header

🎀 referer

🎀 referrer

🎀 remove_content_headers

🎀 remove_header

🎀 scan

🎀 server

🎀 title

🎀 user_agent

🎀 warnings

🎀 www_authenticate

---

👑 AUTHORS 👑

• Gonzalo Diethelm gonzalo.diethelm AT gmail DOT com 💌
• Sawyer X xsawyerx AT gmail DOT com 💌

---

🌈 THANKS 🌈

• Rafaël Garcia-Suarez 🌸
• p5pclub 🫶
• Christian Hansen ⭐

---

okay that's the whole page bestie, you're officially educated 💅✨

cute lil sign-off: this was written for perl v5.42.2, dated 2026-06-07, and it lives in the User Contributed Perl Documentation section of the manual. now go forth and be fast 🦋🎀