README

   1 NAME
   2     AnyEvent::HTTPD - A simple lightweight event based web (application)
   3     server
   4
   5 VERSION
   6     Version 0.04
   7
   8 SYNOPSIS
   9         use AnyEvent::HTTPD;
  10
  11         my $httpd = AnyEvent::HTTPD->new (port => 9090);
  12
  13         $httpd->reg_cb (
  14            '/' => sub {
  15               my ($httpd, $req) = @_;
  16
  17               $req->o ("<html><body><h1>Hello World!</h1>");
  18               $req->o ("<a href=\"/test\">another test page</a>");
  19               $req->o ("</body></html>");
  20               $req->respond;
  21            },
  22            '/test' => sub {
  23               my ($httpd, $req) = @_;
  24
  25               $req->o ("<html><body><h1>Test page</h1>");
  26               $req->o ("<a href=\"/\">Back to the main page</a>");
  27               $req->o ("</body></html>");
  28               $req->respond;
  29            },
  30         );
  31
  32         $httpd->run; # making a AnyEvent condition variable would also work
  33
  34 DESCRIPTION
  35     This module provides a simple HTTPD for serving simple web application
  36     interfaces. It's completly event based and independend from any event
  37     loop by using the AnyEvent module.
  38
  39     It's HTTP implementation is a bit hacky, so before using this module
  40     make sure it works for you and the expected deployment. Feel free to
  41     improve the HTTP support and send in patches!
  42
  43     The documentation is currently only the source code, but next versions
  44     of this module will be better documented hopefully. See also the
  45     "samples/" directory in the AnyEvent::HTTPD distribution for basic
  46     starting points.
  47
  48     AnyEvent::HTTPD even comes with some basic AJAX framework/helper.
  49
  50 FEATURES
  51     *   support for GET and POST requests
  52
  53     *   processing of "x-www-form-urlencoded" and "multipart/form-data"
  54         encoded form parameters
  55
  56     *   ajax helper and javascript output functions in
  57         AnyEvent::HTTPD::Appgets
  58
  59 METHODS
  60     The AnyEvent::HTTPD class inherits directly from
  61     AnyEvent::HTTPD::HTTPServer which inherits the event callback interface
  62     from Object::Event.
  63
  64     Event callbacks can be registered via the Object::Event API (see the
  65     documentation of Object::Event for details).
  66
  67     For a list of available events see below in the *EVENTS* section.
  68
  69     new (%args)
  70         This is the constructor for a AnyEvent::HTTPD object. The %args hash
  71         may contain one of these key/value pairs:
  72
  73         port => $port
  74             The TCP port the HTTP server will listen on.
  75
  76     stop_request
  77         When the server walks the request URI path upwards you can stop the
  78         walk by calling this method. Example:
  79
  80            $httpd->reg_cb (
  81               '/test' => sub {
  82                  my ($httpd, $req) = @_;
  83
  84                  # ...
  85
  86                  $httpd->stop_request; # will prevent that the callback below is called
  87               },
  88               '' => sub { # this one wont be called by a request to '/test'
  89                  my ($httpd, $req) = @_;
  90
  91                  # ...
  92               }
  93            );
  94
  95     run This method is a simplification of the "AnyEvent" condition variable
  96         idiom. You can use it instead of writing:
  97
  98            my $cvar = AnyEvent->condvar;
  99            $cvar->wait;
 100
 101     stop
 102         This will stop the HTTP server and return from the "run" method if
 103         you started the server via that method!
 104
 105 EVENTS
 106     Every request goes to a specific URL. After a (GET or POST) request is
 107     received the URL's path segments are walked down and for each segment a
 108     event is generated. An example:
 109
 110     If the URL '/test/bla.jpg' is requestes following events will be
 111     generated:
 112
 113       '/test/bla.jpg' - the event for the last segment
 114       '/test'         - the event for the 'test' segment
 115       ''              - the root event of each request
 116
 117     To actually handle any request you just have to register a callback for
 118     the event name with the empty string. To handle all requests in the
 119     '/test' directory you have to register a callback for the event with the
 120     name '/test'. Here is an example how to register an event for the
 121     example URL above:
 122
 123        $httpd->reg_cb (
 124           '/test/bla.jpg' => sub {
 125              my ($httpd, $req) = @_;
 126
 127              $req->respond ([200, 'ok', { 'Content-Type' => 'text/html' }, '<h1>Test</h1>' }]);
 128           }
 129        );
 130
 131     See also "stop_request" about stopping the walk of the path segments.
 132
 133     The first argument to such a callback is always the AnyEvent::HTTPD
 134     object itself. The second argument ($req) is the
 135     AnyEvent::HTTPD::Request object for this request. It can be used to get
 136     the (possible) form parameters for this request or the transmitted
 137     content and respond to the request.
 138
 139     Also every request also emits the "request" event, with the same
 140     arguments and semantics, you can use this to implement your own request
 141     multiplexing.
 142
 143 CACHING
 144     Any response from the HTTP server will have "Cache-Control" set to
 145     "max-age=0" and also the "Expires" header set to the "Date" header.
 146     Meaning: Caching is disabled.
 147
 148     If you need caching or would like to have it you can send me a mail or
 149     even better: a patch :)
 150
 151 AUTHOR
 152     Robin Redeker, "<elmex at ta-sa.org>"
 153
 154 BUGS
 155     Please report any bugs or feature requests to "bug-bs-httpd at
 156     rt.cpan.org", or through the web interface at
 157     <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=AnyEvent-HTTPD>. I will
 158     be notified, and then you'll automatically be notified of progress on
 159     your bug as I make changes.
 160
 161 SUPPORT
 162     You can find documentation for this module with the perldoc command.
 163
 164         perldoc AnyEvent::HTTPD
 165
 166     You can also look for information at:
 167
 168     *   RT: CPAN's request tracker
 169
 170         <http://rt.cpan.org/NoAuth/Bugs.html?Dist=AnyEvent-HTTPD>
 171
 172     *   AnnoCPAN: Annotated CPAN documentation
 173
 174         <http://annocpan.org/dist/AnyEvent-HTTPD>
 175
 176     *   CPAN Ratings
 177
 178         <http://cpanratings.perl.org/d/AnyEvent-HTTPD>
 179
 180     *   Search CPAN
 181
 182         <http://search.cpan.org/dist/AnyEvent-HTTPD>
 183
 184 ACKNOWLEDGEMENTS
 185 COPYRIGHT & LICENSE
 186     Copyright 2008 Robin Redeker, all rights reserved.
 187
 188     This program is free software; you can redistribute it and/or modify it
 189     under the same terms as Perl itself.
 190