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
   5 use warnings;
   6 use strict;
   7
   8 our $VERSION = '0.900'; # VERSION
   9
  10
  11
  12 sub new {
  13     my $class   = shift;
  14     my $ua      = shift or die 'User agent is required';
  15     bless {ua => $ua}, $class;
  16 }
  17
  18
  19 sub request {
  20     die 'Not yet implemented';
  21 }
  22
  23
  24 sub ua { shift->{ua} }
  25
  26
  27 sub response_is_future { 0 }
  28
  29 1;
  30
  31 __END__
  32
  33 =pod
  34
  35 =encoding UTF-8
  36
  37 =head1 NAME
  38
  39 HTTP::AnyUA::Backend - A base class for HTTP::AnyUA backends
  40
  41 =head1 VERSION
  42
  43 version 0.900
  44
  45 =head1 SYNOPSIS
  46
  47     package HTTP::AnyUA::Backend::MyUserAgent;
  48
  49     use parent 'HTTP::AnyUA::Backend';
  50
  51     sub response_is_future { 0 }
  52
  53     sub request {
  54         my ($self, $method, $url, $args) = @_;
  55
  56         my $ua = $self->ua;
  57
  58         # Here is where you transform the arguments into a request that $ua
  59         # understands, make the request against $ua and get a response, and
  60         # transform the response to the expected hashref form.
  61
  62         my $resp = $ua->make_request();
  63
  64         return $resp;
  65     }
  66
  67     ### Non-blocking user agents return responses as Future objects:
  68
  69     sub response_is_future { 1 }
  70
  71     sub request {
  72         my ($self, $method, $url, $args) = @_;
  73
  74         my $ua = $self->ua;
  75
  76         my $future = Future->new;
  77
  78         # Again, this example glosses over transforming the request and response
  79         # to and from the actual user agent, but such details are the whole
  80         # point of a backend.
  81
  82         $ua->nonblocking_callback(sub {
  83             my $resp = shift;
  84
  85             if ($resp->{success}) {
  86                 $future->done($resp);
  87             }
  88             else {
  89                 $future->fail($resp);
  90             }
  91         });
  92
  93         return $future;
  94     }
  95
  96 =head1 DESCRIPTION
  97
  98 This module provides an interface for an L<HTTP::AnyUA> "backend," which is an adapter that adds
  99 support for using a type of user agent with L<HTTP::AnyUA>.
 100
 101 This class should not be instantiated directly, but it may be convenient for backend implementations
 102 to subclass it.
 103
 104 At its core, a backend simply takes a set of standard arguments that represent an HTTP request,
 105 transforms that request into a form understood by an underlying user agent, calls upon the user
 106 agent to make the request and get a response, and then transforms that response into a standard
 107 form. The standard forms for the request and response are based on L<HTTP::Tiny>'s arguments and
 108 return value to and from its L<request|HTTP::Tiny/request> method.
 109
 110 =head1 ATTRIBUTES
 111
 112 =head2 ua
 113
 114 Get the user agent that was passed to L</new>.
 115
 116 =head2 response_is_future
 117
 118 Get whether or not responses are L<Future> objects. Default is false.
 119
 120 This may be overridden by implementations.
 121
 122 =head1 METHODS
 123
 124 =head2 new
 125
 126     $backend = HTTP::AnyUA::Backend::MyUserAgent->new($my_user_agent);
 127
 128 Construct a new backend.
 129
 130 =head2 request
 131
 132     $response = $backend->request($method => $url, \%options);
 133
 134 Make a request, get a response.
 135
 136 This must be overridden by implementations.
 137
 138 =head1 SEE ALSO
 139
 140 =over 4
 141
 142 =item *
 143
 144 L<HTTP::AnyUA/REQUEST>  - Explanation of the request arguments
 145
 146 =item *
 147
 148 L<HTTP::AnyUA/RESPONSE> - Explanation of the response
 149
 150 =back
 151
 152 =head1 BUGS
 153
 154 Please report any bugs or feature requests on the bugtracker website
 155 L<https://github.com/chazmcgarvey/HTTP-AnyUA/issues>
 156
 157 When submitting a bug or request, please include a test-file or a
 158 patch to an existing test-file that illustrates the bug or desired
 159 feature.
 160
 161 =head1 AUTHOR
 162
 163 Charles McGarvey <chazmcgarvey@brokenzipper.com>
 164
 165 =head1 COPYRIGHT AND LICENSE
 166
 167 This software is copyright (c) 2017 by Charles McGarvey.
 168
 169 This is free software; you can redistribute it and/or modify it under
 170 the same terms as the Perl 5 programming language system itself.
 171
 172 =cut