NAME
Protocol::UWSGI - handle the UWSGI wire protocol
VERSION
Version 1.000
SYNOPSIS
use strict;
use warnings;
use Protocol::UWSGI qw(:all);
# Encode...
my $req = build_request(
uri => 'http://localhost',
method => 'GET',
remote => '1.2.3.4:1234',
);
# ... and decode again
warn "URI was " . uri_from_env(
extract_frame(\$req)
);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. Try Net::Async::UWSGI for an implementation that actually does something useful.
Typically you'd create a UNIX socket and listen for requests, passing any data to the "extract_frame" function and handling the resulting data if that function 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 = extract_frame($buffref)) {
$self->handle_uwsgi($pkt);
}
}
# and probably an EOF handler to detect client hangup
# sub on_eof { ... }IMPLEMENTATION - Server
A server implementation typically accepts requests from a reverse proxy, such as nginx, and returns HTTP responses.
Import the :server tag to get "uri_from_env", "extract_frame" and in future maybe "psgi_from_env" functions:
use Protocol::UWSGI qw(:server);IMPLEMENTATION - Client
A client implementation typically accepts HTTP requests and converts them to UWSGI for passing to a UWSGI-capable application.
Import the :client tag to get "build_request":
use Protocol::UWSGI qw(:client);FUNCTIONS
If you're handling incoming UWSGI requests, you'll need to instantiate via "new" then decode the request using "extract_frame".
If you're making UWSGI requests against an external UWSGI server, that'll be "build_request".
Just want to decode captured traffic? "extract_frame" again.
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 = \"...";
my $req = Protocol::UWSGI->extract_frame($buffref)
or die "could not find UWSGI frame";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.
This may be called as a class method or an instance method. The instance state will remain unchanged after calling this method.
Note that there is no constructor provided in this class - if you want to call this as an instance method, you'll need to bless manually or be applying this as a role/mixin.
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.
uri_from_env
Returns a URI object parsed from a request ("environment").
INHERITED METHODS
- Exporter
-
as_heavy, export, export_fail, export_ok_tags, export_tags, export_to_level, import, require_version
AUTHOR
Tom Molesworth <cpan@perlsite.co.uk>
LICENSE
Copyright Tom Molesworth 2013-2014. Licensed under the same terms as Perl itself.