Dogcows Code - chaz/p5-HTTP-AnyUA/blob - lib/HTTP/AnyUA/Backend.pm

   1 package HTTP::AnyUA::Backend;
   2 # ABSTRACT: A base class for HTTP::AnyUA backends
   3
   4 =head1 SYNOPSIS
   5
   6     package HTTP::AnyUA::Backend::MyUserAgent;
   7
   8     use parent 'HTTP::AnyUA::Backend';
   9
  10     sub response_is_future { 0 }
  11
  12     sub request {
  13         my ($self, $method, $url, $args) = @_;
  14
  15         my $ua = $self->ua;
  16
  17         # Here is where you transform the arguments into a request that $ua
  18         # understands, make the request against $ua and get a response, and
  19         # transform the response to the expected hashref form.
  20
  21         my $resp = $ua->make_request();
  22
  23         return $resp;
  24     }
  25
  26     ### Non-blocking user agents are expected to return Future objects:
  27
  28     use Future;
  29
  30     sub response_is_future { 1 }
  31
  32     sub request {
  33         my ($self, $method, $url, $args) = @_;
  34
  35         my $ua = $self->ua;
  36
  37         my $future = Future->new;
  38
  39         # Again, this example glosses over transforming the request and response
  40         # to and from the actual user agent, but such details are the whole
  41         # point of a backend.
  42
  43         $ua->nonblocking_callback(sub {
  44             my $resp = shift;
  45
  46             if ($resp->{success}) {
  47                 $future->done($resp);
  48             }
  49             else {
  50                 $future->fail($resp);
  51             }
  52         });
  53
  54         return $future;
  55     }
  56
  57 =head1 DESCRIPTION
  58
  59 This module provides an interface for an L<HTTP::AnyUA> "backend," which is an adapter that adds
  60 support for using a type of user agent with L<HTTP::AnyUA>.
  61
  62 This class should not be instantiated directly, but it may be convenient for backend implementations
  63 to subclass it.
  64
  65 At its core, a backend simply takes a set of standard arguments that represent an HTTP request,
  66 transforms that request into a form understood by an underlying user agent, calls upon the user
  67 agent to make the request and get a response, and then transforms that response into a standard
  68 form. The standard forms for the request and response are based on L<HTTP::Tiny>'s arguments and
  69 return value to and from its L<request|HTTP::Tiny/request> method.
  70
  71 =head1 SEE ALSO
  72
  73 =for :list
  74 * L<HTTP::AnyUA/The Request>  - Explanation of the request arguments
  75 * L<HTTP::AnyUA/The Response> - Explanation of the response
  76
  77 =cut
  78
  79 use warnings;
  80 use strict;
  81
  82 our $VERSION = '9999.999'; # VERSION
  83
  84
  85 =method new
  86
  87     $backend = HTTP::AnyUA::Backend::MyUserAgent->new($my_user_agent);
  88
  89 Construct a new backend.
  90
  91 =cut
  92
  93 sub new {
  94     my $class   = shift;
  95     my $ua      = shift or die 'User agent is required';
  96     bless {ua => $ua}, $class;
  97 }
  98
  99 =method request
 100
 101     $response = $backend->request($method => $url, \%options);
 102
 103 Make a request, get a response.
 104
 105 This must be overridden by implementations.
 106
 107 =cut
 108
 109 sub request {
 110     die 'Not yet implemented';
 111 }
 112
 113 =attr ua
 114
 115 Get the user agent that was passed to L</new>.
 116
 117 =cut
 118
 119 sub ua { shift->{ua} }
 120
 121 =attr response_is_future
 122
 123 Get whether or not responses are L<Future> objects. Default is false.
 124
 125 This may be overridden by implementations.
 126
 127 =cut
 128
 129 sub response_is_future { 0 }
 130
 131 1;