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