/ 
WebSocket-v0.2.1
River stage zero No dependents
/ WebSocket::Headers

NAME

WebSocket::Headers - WebSocket Headers Class

SYNOPSIS

use WebSocket::Headers;
my $h = WebSocket::Headers->new || die( WebSocket::Headers->error, "\n" );
$h->header('Content-Type' => 'text/plain');  # set
$ct = $h->header('Content-Type');            # get

And now also:

my $conn = $h->header( 'connection' )->split( qr/\s*,\s*/ ) if( $h->header( 'connection' )->length > 7 );
die( "Connection header has no \"Upgrade\" value." ) ) unless( $conn->grep(sub{ lc( $_ ) eq 'upgrade' })->length );

die( "Bad value\n" ) if( $h->header( 'upgrade' )->lc ne 'websocket' );

VERSION

v0.1.0

DESCRIPTION

This package inherits all its methods from HTTP::Headers and provides convenient chaining on the value returned from header. For convenience those relevant methods are also documented here.

Any header value returned by "header" in HTTP::Headers that is an array will be returned as an Module::Generic::Array object and regular string will be returned as Module::Generic::Scalar object.

METHODS

as_string

Takes an optional $eol parameter to be used as end of line.

Return the header fields as a formatted MIME header. Since it internally uses the "scan" method to build the string, the result will use case as suggested by HTTP spec, and it will follow recommended "Good Practice" of ordering the header fields. Long header values are not folded.

The optional $eol parameter specifies the line ending sequence to use. The default is "\n". Embedded "\n" characters in header field values will be substituted with this line ending sequence.

authorization

A user agent that wishes to authenticate itself with a server or a proxy, may do so by including these headers.

authorization_basic

This method is used to get or set an authorization header that use the "Basic Authentication Scheme". In array context it will return two values; the user name and the password. In scalar context it will return "uname:password" as a single string value.

When used to set the header value, it expects two arguments. E.g.:

$h->authorization_basic( $uname, $password );

The method will croak if the $uname contains a colon ':'.

clear

This will remove all header fields.

content_length

A decimal number indicating the size in bytes of the message content.

exists

Returns true if the provided header exists, false otherwise. The value can be provided in a case insensitive manner and the dash (-) can be provided as underscore (_)

flatten

Returns the list of pairs of keys and values.

Set or get the WebSocket header.

In set mode, if an array object, it will convert it into a regular array and if a scalar object is provided, it will be converted into its actual underlying value.

You can set multiple headers in one call.

$header->header( Origin => 'https://example.org:8080' );
$header->header( 'Sec-WebSocket-Protocol' => 'chat,com.example.v2', 'Sec-WebSocket-Version' => 13 );
my $accept = $header->header( 'Sec-WebSocket-Accept' );

In get mode, it does the reverse operation, i.e. transform an array into an array object and a string into an scalar object.

It returns a list in list context, or a comma separated values in scalar context.

header_field_names

Returns the list of distinct names for the fields present in the header. The field names have case as suggested by HTTP spec, and the names are returned in the recommended "Good Practice" order.

In scalar context return the number of distinct field names.

proxy_authenticate

This header must be included in a 407 Proxy Authentication Required response.

proxy_authorization

A user agent that wishes to authenticate itself with a server or a proxy, may do so by including these headers.

proxy_authorization_basic

Same as authorization_basic() but will set the Proxy-Authorization header instead.

push_header

Add a new field value for the specified header field. Previous values for the same field are retained.

As for the /header method, the field name ($field) is not case sensitive and '_' can be used as a replacement for '-'.

The $value argument may be a scalar or a reference to a list of scalars.

$header->push_header( 'Sec-WebSocket-Protocol' => 'chat' );
$header->push_header( 'Sec-WebSocket-Protocol' => [qw( com.example.chat.v2 com.example.chat.v1 )] );

remove_header

This function removes the header fields with the specified names.

The header field names ($field) are not case sensitive and '_' can be used as a replacement for '-'.

The return value is the values of the fields removed. In scalar context the number of fields removed is returned.

Note that if you pass in multiple field names then it is generally not possible to tell which of the returned values belonged to which field.

remove_content_headers

This will remove all the header fields used to describe the content of a message. All header field names prefixed with Content- fall into this category, as well as Allow, Expires and Last-Modified. RFC 2616 denotes these fields as Entity Header Fields.

The return value is a new HTTP::Headers object that contains the removed headers only.

scan

Apply a subroutine to each header field in turn. The callback routine is called with two parameters; the name of the field and a single value (a string). If a header field is multi-valued, then the routine is called once for each value. The field name passed to the callback routine has case as suggested by HTTP spec, and the headers will be visited in the recommended "Good Practice" order.

Any return values of the callback routine are ignored. The loop can be broken by raising an exception ("die" in perlfunc), but the caller of scan() would have to trap the exception itself.

server

The server header field contains information about the software being used by the originating server program handling the request.

user_agent

This header field is used in request messages and contains information about the user agent originating the request. E.g.:

$h->user_agent( 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:93.0) Gecko/20100101 Firefox/93.0' );

AUTHOR

Jacques Deguest <jack@deguest.jp>

SEE ALSO

WebSocket::Request, WebSocket::Response, HTTP::Headers

COPYRIGHT & LICENSE

Copyright(c) 2021-2023 DEGUEST Pte. Ltd.

You can use, copy, modify and redistribute this package and associated files under the same terms as Perl itself.