HTTP::...ionPack(3pm)

📦
version 0.09 · 6 versions
, in debian bookworm, ubuntu noble

💖 NAME 💖

HTTP::Headers::ActionPack — HTTP Action, Adventure and Excitement 🎢✨

(also it's a User Contributed Perl Documentation page, so like, iykyk)

🌈 VERSION 🌈

version 0.09 — she's a lil vintage bestie, and we love her for it 🫶

✨ SYNOPSIS ✨

okay bestie, watch this, it's giving main character energy:

use HTTP::Headers::ActionPack;

my $pack       = HTTP::Headers::ActionPack->new;
my $media_type = $pack->create_header( 'Content-Type' => 'application/xml;charset=UTF-8' );
my $link       = $pack->create( 'LinkHeader' => [ '</test/tree>', rel => "up" ] );

# auto-magic header inflation
# for multiple types
$pack->inflate( $http_headers_instance );
$pack->inflate( $http_request_instance );
$pack->inflate( $plack_request_instance );

auto-magic header inflation?? bestie that's not a feature that's a whole personality 💅

🦋 DESCRIPTION 🦋

so like, this is a module that handles the inflation and deflation of complex HTTP header types. no cap. in many cases header values are just simple strings, right, very demure — but in some cases they're complex values with a LOT of information encoded in them, and that's when things get spicy. 🌶️

the goal of this module is to make the parsing and analysis of these headers as easy as just calling "inflate" on a compatible object (there's a list below, don't worry babe).

this top-level class is basically a Factory for creating instances of the other classes in this module. she's the girlboss making sure everyone else shows up. she's also got a bunch of convenience methods so the common cases are, like, easy to write. periodt.

👑 DEFAULT MAPPINGS 👑

this class ships with a whole set of default mappings between HTTP headers and the classes that can inflate them. here's the full list, no skips, no cuts, all of it:

Link                HTTP::Headers::ActionPack::LinkList
Content-Type        HTTP::Headers::ActionPack::MediaType
Accept              HTTP::Headers::ActionPack::MediaTypeList
Accept-Charset      HTTP::Headers::ActionPack::PriorityList
Accept-Encoding     HTTP::Headers::ActionPack::PriorityList
Accept-Language     HTTP::Headers::ActionPack::PriorityList
Date                HTTP::Headers::ActionPack::DateHeader
Client-Date         HTTP::Headers::ActionPack::DateHeader
Expires             HTTP::Headers::ActionPack::DateHeader
Last-Modified       HTTP::Headers::ActionPack::DateHeader
If-Unmodified-Since HTTP::Headers::ActionPack::DateHeader
If-Modified-Since   HTTP::Headers::ActionPack::DateHeader
WWW-Authenticate    HTTP::Headers::ActionPack::WWWAuthenticate
Authentication-Info HTTP::Headers::ActionPack::AuthenticationInfo
Authorization       HTTP::Headers::ActionPack::Authorization
NOTE: the 'Client-Date' header is often added by LWP on HTTP::Response objects. so if you see her, that's why. she's a guest, not a resident. 🏠

💅 METHODS 💅

  • new( ?%mappings ) — the constructor, she takes an option hash of header-name to class mappings, and those get added to (or override) the default mappings (scroll up for those, bestie). every class is expected to have a "new_from_string" method that can parse the string representation of the given header and hand you back an object. so like, each class has to know how to read her own mail. 💌
  • mapping — returns the set of mappings in this instance. that's it. that's the whole thing. 🎀
  • classes — returns the list of supported classes. by default that's the list of classes included in this module, but she'll ALSO grab any extra classes you specified in the %mappings parameter to "new" (see above, babe, i'm not repeating myself). 👑
  • get_content_negotiator — returns an instance of HTTP::Headers::ActionPack::ContentNegotiation. go get 'em negotiator. 🕊️
  • create( $class_name, $args ) — give her a $class_name and $args and she'll inflate the value using the class found in the "classes" list. if $args is a string she calls "new_from_string" on the $class_name, but if $args is an ARRAY ref, she dereferences the ARRAY and passes it to "new". two paths, one girlboss. 🔥
  • create_header( $header_name, $header_value ) — give her a $header_name and a $header_value and she'll inflate the value using the class found in the mappings. if $header_value is a string she calls "new_from_string" on the class mapped to the $header_name, but if $header_value is an ARRAY ref, she dereferences the ARRAY and passes it to "new". same energy, different entry point. ✨
  • inflate( $http_headers )
  • inflate( $http_request )
  • inflate( $plack_request )
  • inflate( $web_request ) — hand her either an HTTP::Headers instance, an HTTP::Request instance, a Plack::Request instance, or a Web::Request instance, and she'll inflate all the relevant headers and store the object in the same instance. one method, four glow-ups. 🦋
in theory this should not negatively affect anything, since all the header objects overload the stringification operator, and most often the headers are treated as strings. BUT this is not for certain and care should be taken. so like, be careful bestie, i'm serious. 😭

😭 CAVEATS 😭

🐚 Plack Compatibility

we have a test in the suite that checks to make sure any inflated header objects will pass between HTTP::Request and HTTP::Response objects, as well as Plack::Request and Plack::Response objects. she's tested, she's vetted, she's that girl. 💯

a simple survey of most of the Plack::Handler subclasses shows that most of them will end up properly stringifying these header objects before sending them out. slay. the notable exceptions were the Apache handlers. not them. 💀

at the time of this writing, the solution for this would be for you to either stringify these objects prior to returning your Plack::Response, or to write a simple middleware component that would do that for you. in future versions we might provide just such a middleware (it would likely inflate the header objects on the request side as well). so like, watch this space. 👀

🎀 Stringification

as mentioned above (bestie i literally just said this), all the header objects overload the stringification operator, so normal usage of them should just do what you would expect (stringify in a sensible way). she's sensible! she's got it together!

however this is not certain, and so care should be taken when passing object headers onto another library that is expecting strings. don't be out here handing a whole object to a library that asked for a string. that's rude. 🙈

🌸 AUTHOR 🌸

Stevan Little <stevan.little@iinteractive.com> — the founder of the whole vibe. 👑

🫶 CONTRIBUTORS 🫶

  1. Andrew Nelson <anelson@cpan.org>
  2. Dave Rolsky <autarch@urth.org>
  3. Florian Ragwitz <rafl@debian.org>
  4. Jesse Luehrs <doy@tozt.net>
  5. Karen Etheridge <ether@cpan.org>

the group chat. the squad. the ones who showed up. 💜

this software is copyright (c) 2012 by Infinity Interactive, Inc. (yes there are two dots in the original, we're not touching it, it's iconic, periodt ✨).

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. so like, go off, but respectfully. 🎀

and that's the whole page bestie!! 🌈 she's built on perl v5.34.0 and this lil doc was born on 2022-06-14. mwah. 💅🦋🌸💖

📦 where this page comes from