/ 
AnyEvent-HTTP-Message-0.302
River stage one • 2 direct dependents • 4 total dependents
/ AnyEvent::HTTP::Request

NAME

AnyEvent::HTTP::Request - HTTP Request object for AnyEvent::HTTP

VERSION

version 0.302

SYNOPSIS

# parses the same argument list as AnyEvent::HTTP::http_request
my $req = AnyEvent::HTTP::Request->new(
  POST => $uri,
  body => $body,
  headers => \%headers,
  %params,
  sub { ... }
);

# provides introspection
print $req->header('user-agent');
print $req->uri;

# can be upgraded to an HTTP::Request object
my $http_req = $req->to_http_message;

# or submitted via AnyEvent::HTTP::http_request
$req->send();

DESCRIPTION

This class creates a lightweight object to represent an HTTP request as used by AnyEvent::HTTP.

It was created to provide simple, clear test code for parsing the parameters passed to "http_request" in AnyEvent::HTTP.

Instead of code that looks something like this:

is $args[0],       'POST',              'request method';
is $args[1],       'http://some/where', 'request uri';
is ref($args[-1]), 'CODE',              'http_request callback';
is_deeply { @args[ 2 .. $#args - 1 ] }->{headers},
  \%expected_headers, 'request headers';

You can write clearer, simpler code like this:

my $req = AnyEvent::HTTP::Request->new(@args);

is $req->method,  'POST',              'request method';
is $req->uri,     'http://some/where', 'request uri';
is ref($req->cb), 'CODE',              'http_request callback';
is_deeply $req->headers, \%expected_headers, 'request headers';

It's a little less weird, and easier to maintain (and do again).

This class also allows you to build an object by passing a hashref of named parameters in case you'd prefer that. You can then call "send" to actually make the request (via "http_request" in AnyEvent::HTTP), or "args" to get the list of arguments the object would pass.

It can also be converted from or to the more featureful HTTP::Request.

CLASS METHODS

new

Accepts the same argument list as "http_request" in AnyEvent::HTTP (see "parse_args"):

AnyEvent::HTTP::Request->new(
  $method => $uri,
  body    => $body,
  headers => \%headers,
  %params,
  sub { ... }
);

Alternatively accepts an instance of HTTP::Request with an optional hashref of extra attributes (see "from_http_message"):

AnyEvent::HTTP::Request->new(
  HTTP::Request->new( $method, $uri, $headers, $body ),
  {
    cb => sub { ... },
    params => \%params,
  }
);

Also accepts a single hashref of named attributes (see "ATTRIBUTES"):

AnyEvent::HTTP::Request->new({
  method  => 'POST',
  uri     => 'http://example.com',
  cb      => sub { ... },
  params  => \%params,
  headers => \%headers,
  body    => $body,
});

parse_args

Called by the constructor to parse the argument list for "http_request" in AnyEvent::HTTP and return a hashref which will be the basis for the object.

The list should look like ($method, $uri, %optional, \&callback) where the %optional hash may include body, headers, and any of the other options accepted by "http_request" in AnyEvent::HTTP (which will become "params").

from_http_message

Called by the constructor when "new" is passed an instance of HTTP::Request.

Since only method, uri, headers, and body can be determined from HTTP::Request, a hashref can be passed as a second parameter containing cb and params.

ATTRIBUTES

method

Request method (GET, POST, etc) (first argument to "http_request" in AnyEvent::HTTP)

uri

Request uri (string) (second argument to "http_request" in AnyEvent::HTTP)

body

Request content body

content

Alias for "body"

headers

A hashref of the HTTP request headers

params

A hashref of the function parameters (optional middle (key => value) arguments to "http_request" in AnyEvent::HTTP)

Note that these are connection params like persistent and timeout, not query params like in CGI.

Note that body and headers will not be included. This hashref is essentially user-agent parameters.

cb

Callback subroutine reference (last argument to "http_request" in AnyEvent::HTTP)

Note: For consistency with the other attributes (and to avoid confusion with other modules) this is a read-only accessor and will croak if passed any arguments.

If you intend to execute the callback (to simulate a response) you can dereference the return value:

$req->cb->($body, $headers);

or use "respond_with".

METHODS

args

Returns a list of arguments that can be passed to "http_request" in AnyEvent::HTTP (beware the sub's prototype, though).

respond_with

$req->respond_with($body, \%headers);
$req->respond_with(AnyEvent::HTTP::Response->new(@args));
$req->respond_with(HTTP::Response->new($code, $message, \@headers, $body));

Simulate a response by calling "cb". This method is mostly useful for testing, but then again so is the whole module.

For convenience this method can accept an instance of AnyEvent::HTTP::Response or any list of arguments that can be passed to "new" in AnyEvent::HTTP::Response.

send

Actually submit the request by passing "args" to "http_request" in AnyEvent::HTTP

to_http_message

Returns an instance of HTTP::Request to provide additional functionality.

Note that "cb" and "params" will not be represented in the HTTP::Request object (since they are for the user-agent and not the request).

SEE ALSO

AUTHOR

Randy Stauner <rwstauner@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Randy Stauner.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.