NAME

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

VERSION

version 0.301

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).

AUTHOR

Randy Stauner <rwstauner@cpan.org>

COPYRIGHT AND LICENSE

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

CPAN RT