perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/src/docs/2.0/user/handlers handlers.pod
Date Wed, 14 Aug 2002 09:29:47 GMT
stas        2002/08/14 02:29:47

  Modified:    src/docs/2.0/user/handlers handlers.pod
  Log:
  improving the snooping filter
  
  Revision  Changes    Path
  1.10      +263 -81   modperl-docs/src/docs/2.0/user/handlers/handlers.pod
  
  Index: handlers.pod
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/handlers/handlers.pod,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- handlers.pod	13 Aug 2002 15:57:07 -0000	1.9
  +++ handlers.pod	14 Aug 2002 09:29:47 -0000	1.10
  @@ -944,15 +944,15 @@
     use Apache::Const -compile => qw(OK DECLINED);
     use APR::Const -compile => ':common';
     
  -  sub connection : FilterConnectionHandler { snoop(@_) }
  -  sub request    : FilterRequestHandler    { snoop(@_) }
  +  sub connection : FilterConnectionHandler { snoop("connection", @_) }
  +  sub request    : FilterRequestHandler    { snoop("request",    @_) }
     
     sub snoop {
  -      my($filter, $bb, $mode, $block, $readbytes) = @_;
  +      my $type = shift;
  +      my($filter, $bb, $mode, $block, $readbytes) = @_; # filter args
     
         # $mode, $block, $readbytes are passed only for input filters
  -      my $stream = defined $mode ? "input"   : "output";
  -      my $phase  = $filter->r    ? "request" : "connection";
  +      my $stream = defined $mode ? "input" : "output";
     
         # read the data and pass-through the bucket brigades unchanged
         my $ra_data = '';
  @@ -969,12 +969,15 @@
             return $rv unless $rv == APR::SUCCESS;
         }
     
  -      # send the sniffed info to stderr so not to interfere with normal
  +      # send the sniffed info to STDERR so not to interfere with normal
         # output
  -      warn "[$phase ($stream)]\n";
  +      my $direction = $stream eq 'output' ? ">>>" : "<<<";
  +      print STDERR "\n$direction $type $stream filter\n";
  +      my $c = 1;
         while (my($btype, $data) = splice @$ra_data, 0, 2) {
  -          $data = join "", map "        $_\n", split /\n/, $data;
  -          warn "    $btype:\n$data\n";
  +          print STDERR "    o bucket $c: $btype\n";
  +          print STDERR "[$data]\n";
  +          $c++;
         }
     
         return Apache::OK;
  @@ -996,12 +999,15 @@
   This package provides two filter handlers, one for connection and
   another for request filtering:
   
  -  sub connection : FilterConnectionHandler { snoop(@_) }
  -  sub request    : FilterRequestHandler    { snoop(@_) }
  +  sub connection : FilterConnectionHandler { snoop("connection", @_) }
  +  sub request    : FilterRequestHandler    { snoop("request",    @_) }
   
   Both handlers forward their arguments to the C<snoop()> function that
   does the real job. We needed to add these two subroutines in order to
  -assign the two different attributes.
  +assign the two different attributes. Plus the functions pass the
  +filter type to C<snoop()> as the first argument, which gets shifted
  +off C<@_> and the rest of the C<@_> are the arguments that were
  +originally passed to the filter handler.
   
   It's easy to know whether a filter handler is running in the input or
   the output mode. The arguments C<$filter> and C<$bb> are always
  @@ -1058,40 +1064,49 @@
   work.
   
   First we can see the connection input filter at work, as it processes
  -the HTTP headers. We can see that each header is put into a separate
  -brigade with a single bucket:
  -
  -  [connection (input)]
  -      HEAP:
  -          POST /dump?foo=1&bar=2 HTTP/1.1
  -  
  -  [connection (input)]
  -      HEAP:
  -          TE: deflate,gzip;q=0.3
  -  
  -  [connection (input)]
  -      HEAP:
  -          Connection: TE, close
  -  
  -  [connection (input)]
  -      HEAP:
  -          Host: localhost:8008
  -  
  -  [connection (input)]
  -      HEAP:
  -          User-Agent: lwp-request/2.01
  -  
  -  [connection (input)]
  -      HEAP:
  -          Content-Length: 15
  -  
  -  [connection (input)]
  -      HEAP:
  -          Content-Type: application/x-www-form-urlencoded
  -  
  -  [connection (input)]
  -      HEAP:
  -          
  +the HTTP headers. We can see that for this request each header is put
  +into a separate brigade with a single bucket. The data is conveniently
  +enclosed by C<[]> so you can see the new line characters as well.
  +
  +  <<< connection input filter
  +      o bucket 1: HEAP
  +  [POST /dump?foo=1&bar=2 HTTP/1.1
  +  ]
  +  
  +  <<< connection input filter
  +      o bucket 1: HEAP
  +  [TE: deflate,gzip;q=0.3
  +  ]
  +  
  +  <<< connection input filter
  +      o bucket 1: HEAP
  +  [Connection: TE, close
  +  ]
  +  
  +  <<< connection input filter
  +      o bucket 1: HEAP
  +  [Host: localhost:8008
  +  ]
  +  
  +  <<< connection input filter
  +      o bucket 1: HEAP
  +  [User-Agent: lwp-request/2.01
  +  ]
  +  
  +  <<< connection input filter
  +      o bucket 1: HEAP
  +  [Content-Length: 14
  +  ]
  +  
  +  <<< connection input filter
  +      o bucket 1: HEAP
  +  [Content-Type: application/x-www-form-urlencoded
  +  ]
  +  
  +  <<< connection input filter
  +      o bucket 1: HEAP
  +  [
  +  ]
   
   Here the HTTP header has been terminated by a double new line. So far
   all the buckets were of the I<HEAP> type, meaning that they were
  @@ -1102,15 +1117,15 @@
   The following two entries are generated when
   C<MyApache::Dump::handler> reads the POSTed content:
   
  -  [connection (input)]
  -      HEAP:
  -          mod_perl rules
  -  
  -  [request (input)]
  -      HEAP:
  -          mod_perl rules
  -  
  -      EOS:
  +  <<< connection input filter
  +      o bucket 1: HEAP
  +  [mod_perl rules]
  +  
  +  <<< request input filter
  +      o bucket 1: HEAP
  +  [mod_perl rules]
  +      o bucket 2: EOS
  +  []
   
   as we saw earlier on the diagram, the connection input filter is run
   before the request input filter. Since our connection input filter was
  @@ -1124,12 +1139,13 @@
   response. However only the request output filter is filtering it at
   this point:
   
  -  [request (output)]
  -      TRANSIENT:
  -          args:
  -          foo=1&bar=2
  -          content:
  -          mod_perl rules
  +  >>> request output filter
  +      o bucket 1: TRANSIENT
  +  [args:
  +  foo=1&bar=2
  +  content:
  +  mod_perl rules
  +  ]
   
   This happens because Apache hasn't sent yet the response HTTP headers
   to the client. Apache postpones the header sending so it can calculate
  @@ -1142,35 +1158,38 @@
   connection output filters (notice that the request output filters
   don't see it):
   
  -  [connection (output)]
  -      HEAP:
  -          HTTP/1.1 200 OK
  -          Date: Tue, 13 Aug 2002 12:36:52 GMT
  -          Server: Apache/2.0.40-dev (Unix) mod_perl/1.99_05-dev 
  -          Perl/v5.8.0 mod_ssl/2.0.40-dev OpenSSL/0.9.6d DAV/2
  -          Content-Length: 43
  -          Connection: close
  -          Content-Type: text/plain; charset=ISO-8859-1
  -          
  +  >>> connection output filter
  +      o bucket 1: HEAP
  +  [HTTP/1.1 200 OK
  +  Date: Wed, 14 Aug 2002 07:31:53 GMT
  +  Server: Apache/2.0.41-dev (Unix) mod_perl/1.99_05-dev 
  +  Perl/v5.8.0 mod_ssl/2.0.41-dev OpenSSL/0.9.6d DAV/2
  +  Content-Length: 42
  +  Connection: close
  +  Content-Type: text/plain; charset=ISO-8859-1
  +  
  +  ]
   
   Now the response body in the bucket of type I<HEAP> is passed through
   the connection output filter, followed by the I<EOS> bucket to mark
   the end of the request:
   
  -  [connection (output)]
  -      HEAP:
  -          args:
  -          foo=1&bar=2
  -          content:
  -          mod_perl rules
  -  
  -      EOS:
  +  >>> connection output filter
  +      o bucket 1: HEAP
  +  [args:
  +  foo=1&bar=2
  +  content:
  +  mod_perl rules
  +  ]
  +      o bucket 2: EOS
  +  []
   
   Finally the output is flushed, to make sure that any buffered output
   is sent to the client:
   
  -  [connection (output)]
  -      FLUSH:
  +  >>> connection output filter
  +      o bucket 1: FLUSH
  +  []
   
   This module helps to understand that each filter handler can be called
   many time during each request and connection. It's called for each
  @@ -1182,6 +1201,169 @@
   input filter won't be called.
   
   
  +
  +=head2 Connection Input Filter
  +
  +Let's say that we want to test how our handlers behave when they are
  +requested as C<HEAD> requests, rather than C<GET>. We can alter the
  +request headers at the incoming connection level transparently to all
  +handlers. So here is the input filter handler that does that by
  +directly manipulating the bucket brigades:
  +
  +  file:MyApache/InputFilterGET2HEAD.pm
  +  -----------------------------------
  +  package MyApache::InputFilterGET2HEAD;
  +  
  +  use strict;
  +  use warnings;
  +  
  +  use base qw(Apache::Filter);
  +  
  +  use Apache::RequestRec ();
  +  use Apache::RequestIO ();
  +  use APR::Brigade ();
  +  use APR::Bucket ();
  +  
  +  use Apache::Const -compile => 'OK';
  +  use APR::Const -compile => ':common';
  +  
  +  sub handler : FilterConnectionHandler {
  +      my($filter, $bb, $mode, $block, $readbytes) = @_;
  +  
  +      my $c = $filter->c;
  +      my $ctx_bb = APR::Brigade->new($c->pool, $c->bucket_alloc);
  +      my $rv = $filter->next->get_brigade($ctx_bb, $mode, $block, $readbytes);
  +      return $rv unless $rv == APR::SUCCESS;
  +  
  +      while (!$ctx_bb->empty) {
  +          my $bucket = $ctx_bb->first;
  +  
  +          $bucket->remove;
  +  
  +          if ($bucket->is_eos) {
  +              $bb->insert_tail($bucket);
  +              last;
  +          }
  +  
  +          my $data;
  +          my $status = $bucket->read($data);
  +          return $status unless $status == APR::SUCCESS;
  +  
  +          if ($data and $data =~ s|^GET|HEAD|) {
  +              $bucket = APR::Bucket->new($data);
  +          }
  +  
  +          $bb->insert_tail($bucket);
  +      }
  +  
  +      Apache::OK;
  +  }
  +  
  +  1;
  +
  +The filter handler is called for each bucket brigade, which in turn
  +includes buckets with data. The gist of any filter handler is to
  +retrieve the bucket brigade sent from the previous filter, prepare a
  +new empty brigade, and move buckets from the former brigade to the
  +latter optionally modifying the buckets on the way, which may include
  +removing or adding new buckets. Of course if the filter doesn't want
  +to modify any of the buckets it may decide to pass through the
  +original brigade without doing any work.
  +
  +In our example the handler first removes the bucket at the top of the
  +brigade and looks at its type. If it sees an end of stream, that
  +removed bucket is linked to the tail of the bucket brigade that will
  +go to the next filter and it doesn't attempt to read any more
  +buckets. If this event doesn't happen the handler reads the data from
  +that bucket and if it finds that the data is of interest to us, it
  +modifies the data, creates a new bucket using the modified data and
  +links it to the tail of the outgoing brigade, while discarding the
  +original bucket. In our case the interesting data is a such that
  +matches the regex C</^GET/>. If the data is not interesting to the
  +handler, it simply links the unmodified bucket to the outgoing
  +brigade.
  +
  +The handler looks for data like:
  +
  +  GET /perl/test.pl HTTP/1.1
  +
  +and turns it into:
  +
  +  HEAD /perl/test.pl HTTP/1.1
  +
  +For example, consider the following response handler:
  +
  +  file:MyApache/RequestType.pm
  +  ---------------------------
  +  package MyApache::RequestType;
  +  
  +  use strict;
  +  use warnings;
  +  
  +  use Apache::Const -compile => 'OK';
  +  
  +  sub handler {
  +      my $r = shift;
  +      $r->content_type('text/plain');
  +      $r->print("the request type was " . $r->method);
  +      Apache::OK;
  +  }
  +  1;
  +
  +which returns to the client the request type it has issued. In the
  +case of the C<HEAD> request Apache will discard the response body, but
  +it'll will still set the correct C<Content-Length> header, which will
  +be 24 in case of the C<GET> request and 25 for C<HEAD>. Therefore if
  +this response handler is configured as:
  +
  +  Listen 8005
  +  <VirtualHost _default_:8005>
  +      <Location />
  +          SetHandler modperl
  +          PerlResponseHandler +MyApache::RequestType
  +      </Location>
  +  </VirtualHost>
  +
  +and a C<GET> request is issued to I</>:
  +
  +  panic% perl -MLWP::UserAgent -le \
  +  '$r = LWP::UserAgent->new()->get("http://localhost:8005/"); \
  +  print $r->headers->content_length . ": ".  $r->content'
  +  24: the request type was GET
  +
  +where the response's body is:
  +
  +  the request type was GET
  +
  +And the C<Content-Length> header is set to 24.
  +
  +However if we enable the C<MyApache::InputFilterGET2HEAD> input
  +connection filter:
  +
  +  Listen 8005
  +  <VirtualHost _default_:8005>
  +      PerlInputFilterHandler +MyApache::InputFilterGET2HEAD
  +  
  +      <Location />
  +          SetHandler modperl
  +          PerlResponseHandler +MyApache::RequestType
  +      </Location>
  +  </VirtualHost>
  +
  +And issue the same C<GET> request, we get only:
  +
  +  25: 
  +
  +which means that the body was discarded by Apache, because our filter
  +turned the C<GET> request into a C<HEAD> request and if Apache wasn't
  +discarding the body on C<HEAD>, the response would be:
  +
  +  the request type was HEAD
  +
  +that's why the content length is reported as 25 and not 24 as in the
  +real GET request.
  +
  +=head2 Request Input Filter
   
   =head2 Bucket Brigades and Stream-Oriented Request Output Filters
   
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message