NAME

Protocol::UWSGI - handle the UWSGI wire protocol

VERSION

version 0.001

SYNOPSIS

 use Protocol::UWSGI;
 my $uwsgi = Protocol::UWSGI->new;
 $uwsgi->build_request(
   uri    => 'http://localhost',
   method => 'GET',
   remote => '1.2.3.4:1234',
 );

DESCRIPTION

Provides protocol-level support for UWSGI packet generation/decoding, as defined by http://uwsgi-docs.readthedocs.org/en/latest/Protocol.html. Currently expects to deal with PSGI data (modifier 1 == 5), although this may be extended later if there's any demand for the other packet types.

This is unlikely to be useful in an application - it's intended to provide support for dealing with the protocol in an existing framework: it deals with the abstract protocol only, and has no network transport handling at all.

Typically you'd create a UNIX socket and listen for requests, passing any data to the "extract_frame" method and handling the resulting data if that method returns something other than undef:

 # Detect read - first packet is usually the UWSGI header, everything
 # after that would be the HTTP request body if there is one:
 sub on_read {
   my ($self, $buffref) = @_;
   while(my $pkt = $uwsgi->extract_frame($buffref)) {
     $self->handle_uwsgi($pkt);
   }
 }

 # and probably an EOF handler to detect client hangup
 # sub on_eof { ... }

METHODS

new

Instantiate. Takes no parameters, returns an instance.

extract_frame

Attempts to extract a single UWSGI packet from the given buffer (which should be passed as a scalar ref, e.g. my $buffref = \"...").

If we had enough data for a packet, that packet will be removed from the buffer and returned. There may be additional packet data that can be extracted, or non-UWSGI data such as HTTP request body.

If this returns undef, there's not enough data to process - in this case, the buffer is guaranteed not to be modified.

bytes_required

Returns the number of additional bytes we'll need in order to proceed.

If zero, this means we should be able to extract a valid frame.

build_request

Builds an UWSGI request using the given modifier, defaulting to modifier1 == 5 and modifier2 == 0, i.e. PSGI request.

Takes the following named parameters:

• modifier1 - the modifier1 value, defaults to 5 if not provided

• modifier2 - the modifier2 value, defaults to 0 if not provided

• method - the HTTP request method

• uri - which URI we're requesting, can be passed as a plain string in which case we'll upgrade to a URI object internally

• headers - a hashref of HTTP headers, e.g. { 'Content-Type' => 'text/html' }

Returns a scalar containing packet data or raises an exception on failure.

extract_modifier

Used internally to extract and handle the modifier-specific data.

AUTHOR

Tom Molesworth <cpan@entitymodel.com>

LICENSE

Copyright Tom Molesworth 2013. Licensed under the same terms as Perl itself.

cpanm Protocol::UWSGI

perl -MCPAN -e shell
install Protocol::UWSGI