From c639019b1955f2d3f7e9a14131160e4c28962507 Mon Sep 17 00:00:00 2001 From: Olaf Alders Date: Thu, 11 Apr 2019 14:07:09 -0400 Subject: [PATCH 1/2] Add an example script to demonstrate handler order --- examples/handler-order.pl | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100755 examples/handler-order.pl diff --git a/examples/handler-order.pl b/examples/handler-order.pl new file mode 100755 index 000000000..813fac727 --- /dev/null +++ b/examples/handler-order.pl @@ -0,0 +1,21 @@ +#!/usr/bin/env perl + +use strict; +use warnings; +use feature qw( say ); + +use LWP::UserAgent; +my $ua = LWP::UserAgent->new; + +my @phases = ( + 'request_preprepare', 'request_prepare', + 'request_send', 'response_header', + 'response_data', 'response_done', + 'response_redirect', +); + +for my $phase (@phases) { + $ua->add_handler($phase => sub { say "$phase"; return undef; }); +} + +$ua->get('http://example.com'); From fa388bc100dfccbb404931d078b7fdfd6646fd7c Mon Sep 17 00:00:00 2001 From: Olaf Alders Date: Thu, 11 Apr 2019 14:06:58 -0400 Subject: [PATCH 2/2] Document the order in which handlers are fired. Fixes #273 --- Changes | 1 + lib/LWP/UserAgent.pm | 74 +++++++++++++++++++++++++------------------- 2 files changed, 43 insertions(+), 32 deletions(-) diff --git a/Changes b/Changes index 4bf5c09c1..0e57abce1 100644 --- a/Changes +++ b/Changes @@ -2,6 +2,7 @@ Change history for libwww-perl {{$NEXT}} - Document current best practices (Olaf Alders) + - Document handlers in their order of operation (Olaf Alders) 6.38 2019-03-25 18:58:58Z - Update Net::HTTP dependency from 6.07 to 6.18 (GH#310) (Olaf Alders) diff --git a/lib/LWP/UserAgent.pm b/lib/LWP/UserAgent.pm index 4c4a18591..3690bd5df 100644 --- a/lib/LWP/UserAgent.pm +++ b/lib/LWP/UserAgent.pm @@ -1627,34 +1627,27 @@ the active handlers: Add handler to be invoked in the given processing phase. For how to specify C<%matchspec> see L. -The possible values C<$phase> and the corresponding callback signatures are: +The possible values C<$phase> and the corresponding callback signatures are as +follows. Note that the handlers are documented in the order in which they will +be run, which is: + + request_preprepare + request_prepare + request_send + response_header + response_data + response_done + response_redirect =over -=item response_data => sub { my($response, $ua, $handler, $data) = @_; ... } - -This handler is called for each chunk of data received for the -response. The handler might croak to abort the request. - -This handler needs to return a TRUE value to be called again for -subsequent chunks for the same request. - -=item response_done => sub { my($response, $ua, $handler) = @_; ... } - -The handler is called after the response has been fully received, but -before any redirect handling is attempted. The handler can be used to -extract information or modify the response. - -=item response_header => sub { my($response, $ua, $handler) = @_; ... } - -This handler is called right after the response headers have been -received, but before any content data. The handler might set up -handlers for data and might croak to abort the request. +=item request_preprepare => sub { my($request, $ua, $handler) = @_; ... } -The handler might set the C<< $response->{default_add_content} >> value to -control if any received data should be added to the response object -directly. This will initially be false if the C<< $ua->request() >> method -was called with a C<$content_file> or C<$content_cb argument>; otherwise true. +The handler is called before the C and other standard +initialization of the request. This can be used to set up headers +and attributes that the C handler depends on. Proxy +initialization should take place here; but in general don't register +handlers for this phase. =item request_prepare => sub { my($request, $ua, $handler) = @_; ... } @@ -1669,14 +1662,6 @@ The return value from the callback is ignored. If an exception is raised it will abort the request and make the request method return a "400 Bad request" response. -=item request_preprepare => sub { my($request, $ua, $handler) = @_; ... } - -The handler is called before the C and other standard -initialization of the request. This can be used to set up headers -and attributes that the C handler depends on. Proxy -initialization should take place here; but in general don't register -handlers for this phase. - =item request_send => sub { my($request, $ua, $handler) = @_; ... } This handler gets a chance of handling requests before they're sent to the @@ -1686,6 +1671,31 @@ wishes to terminate the processing; otherwise it should return nothing. The C and C handlers will not be invoked for this response, but the C will be. +=item response_header => sub { my($response, $ua, $handler) = @_; ... } + +This handler is called right after the response headers have been +received, but before any content data. The handler might set up +handlers for data and might croak to abort the request. + +The handler might set the C<< $response->{default_add_content} >> value to +control if any received data should be added to the response object +directly. This will initially be false if the C<< $ua->request() >> method +was called with a C<$content_file> or C<$content_cb argument>; otherwise true. + +=item response_data => sub { my($response, $ua, $handler, $data) = @_; ... } + +This handler is called for each chunk of data received for the +response. The handler might croak to abort the request. + +This handler needs to return a TRUE value to be called again for +subsequent chunks for the same request. + +=item response_done => sub { my($response, $ua, $handler) = @_; ... } + +The handler is called after the response has been fully received, but +before any redirect handling is attempted. The handler can be used to +extract information or modify the response. + =item response_redirect => sub { my($response, $ua, $handler) = @_; ... } The handler is called in C<< $ua->request >> after C. If the