| 1 |
NAME |
| 2 |
AnyEvent::HTTPD - A simple lightweight event based web (application) |
| 3 |
server |
| 4 |
|
| 5 |
VERSION |
| 6 |
Version 0.93 |
| 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->respond ({ content => ['text/html', |
| 18 |
"<html><body><h1>Hello World!</h1>" |
| 19 |
. "<a href=\"/test\">another test page</a>" |
| 20 |
. "</body></html>" |
| 21 |
]}); |
| 22 |
}, |
| 23 |
'/test' => sub { |
| 24 |
my ($httpd, $req) = @_; |
| 25 |
|
| 26 |
$req->respond ({ content => ['text/html', |
| 27 |
"<html><body><h1>Test page</h1>" |
| 28 |
. "<a href=\"/\">Back to the main page</a>" |
| 29 |
. "</body></html>" |
| 30 |
]}); |
| 31 |
}, |
| 32 |
); |
| 33 |
|
| 34 |
$httpd->run; # making a AnyEvent condition variable would also work |
| 35 |
|
| 36 |
DESCRIPTION |
| 37 |
This module provides a simple HTTPD for serving simple web application |
| 38 |
interfaces. It's completly event based and independend from any event |
| 39 |
loop by using the AnyEvent module. |
| 40 |
|
| 41 |
It's HTTP implementation is a bit hacky, so before using this module |
| 42 |
make sure it works for you and the expected deployment. Feel free to |
| 43 |
improve the HTTP support and send in patches! |
| 44 |
|
| 45 |
The documentation is currently only the source code, but next versions |
| 46 |
of this module will be better documented hopefully. See also the |
| 47 |
"samples/" directory in the AnyEvent::HTTPD distribution for basic |
| 48 |
starting points. |
| 49 |
|
| 50 |
FEATURES |
| 51 |
* support for GET and POST requests. |
| 52 |
|
| 53 |
* support for HTTP 1.0 keep-alive. |
| 54 |
|
| 55 |
* processing of "x-www-form-urlencoded" and "multipart/form-data" |
| 56 |
("multipart/mixed") encoded form parameters. |
| 57 |
|
| 58 |
* support for streaming responses. |
| 59 |
|
| 60 |
* with version 0.8 no more dependend on LWP for HTTP::Date. |
| 61 |
|
| 62 |
* (limited) support for SSL |
| 63 |
|
| 64 |
METHODS |
| 65 |
The AnyEvent::HTTPD class inherits directly from |
| 66 |
AnyEvent::HTTPD::HTTPServer which inherits the event callback interface |
| 67 |
from Object::Event. |
| 68 |
|
| 69 |
Event callbacks can be registered via the Object::Event API (see the |
| 70 |
documentation of Object::Event for details). |
| 71 |
|
| 72 |
For a list of available events see below in the *EVENTS* section. |
| 73 |
|
| 74 |
new (%args) |
| 75 |
This is the constructor for a AnyEvent::HTTPD object. The %args hash |
| 76 |
may contain one of these key/value pairs: |
| 77 |
|
| 78 |
host => $host |
| 79 |
The TCP address of the HTTP server will listen on. Usually |
| 80 |
0.0.0.0 (the default), for a public server, or 127.0.0.1 for a |
| 81 |
local server. |
| 82 |
|
| 83 |
port => $port |
| 84 |
The TCP port the HTTP server will listen on. If undefined some |
| 85 |
free port will be used. You can get it via the "port" method. |
| 86 |
|
| 87 |
ssl => $tls_ctx |
| 88 |
If this option is given the server will listen for a SSL/TLS |
| 89 |
connection on the configured port. As $tls_ctx you can pass |
| 90 |
anything that you can pass as "tls_ctx" to an AnyEvent::Handle |
| 91 |
object. |
| 92 |
|
| 93 |
Example: |
| 94 |
|
| 95 |
my $httpd = |
| 96 |
AnyEvent::HTTPD->new ( |
| 97 |
port => 443, |
| 98 |
ssl => { cert_file => "/path/to/my/server_cert_and_key.pem" } |
| 99 |
); |
| 100 |
|
| 101 |
Or: |
| 102 |
|
| 103 |
my $httpd = |
| 104 |
AnyEvent::HTTPD->new ( |
| 105 |
port => 443, |
| 106 |
ssl => AnyEvent::TLS->new (...), |
| 107 |
); |
| 108 |
|
| 109 |
request_timeout => $seconds |
| 110 |
This will set the request timeout for connections. The default |
| 111 |
value is 60 seconds. |
| 112 |
|
| 113 |
backlog => $int |
| 114 |
The backlog argument defines the maximum length the queue of |
| 115 |
pending connections may grow to. The real maximum queue length |
| 116 |
will be 1.5 times more than the value specified in the backlog |
| 117 |
argument. |
| 118 |
|
| 119 |
See also "man 2 listen". |
| 120 |
|
| 121 |
By default will be set by AnyEvent::Socket"::tcp_server" to 128. |
| 122 |
|
| 123 |
connection_class => $class |
| 124 |
This is a special parameter that you can use to pass your own |
| 125 |
connection class to AnyEvent::HTTPD::HTTPServer. This is only of |
| 126 |
interest to you if you plan to subclass |
| 127 |
AnyEvent::HTTPD::HTTPConnection. |
| 128 |
|
| 129 |
request_class => $class |
| 130 |
This is a special parameter that you can use to pass your own |
| 131 |
request class to AnyEvent::HTTPD. This is only of interest to |
| 132 |
you if you plan to subclass AnyEvent::HTTPD::Request. |
| 133 |
|
| 134 |
allowed_methods => $arrayref |
| 135 |
This parameter sets the allowed HTTP methods for requests, |
| 136 |
defaulting to GET, HEAD and POST. Each request received is |
| 137 |
matched against this list, and a '501 not implemented' is |
| 138 |
returned if no match is found. Requests using disallowed |
| 139 |
handlers will never trigger callbacks. |
| 140 |
|
| 141 |
port |
| 142 |
Returns the port number this server is bound to. |
| 143 |
|
| 144 |
host |
| 145 |
Returns the host/ip this server is bound to. |
| 146 |
|
| 147 |
allowed_methods |
| 148 |
Returns an arrayref of allowed HTTP methods, possibly as set by the |
| 149 |
allowed_methods argument to the constructor. |
| 150 |
|
| 151 |
stop_request |
| 152 |
When the server walks the request URI path upwards you can stop the |
| 153 |
walk by calling this method. You can even stop further handling |
| 154 |
after the "request" event. |
| 155 |
|
| 156 |
Example: |
| 157 |
|
| 158 |
$httpd->reg_cb ( |
| 159 |
'/test' => sub { |
| 160 |
my ($httpd, $req) = @_; |
| 161 |
|
| 162 |
# ... |
| 163 |
|
| 164 |
$httpd->stop_request; # will prevent that the callback below is called |
| 165 |
}, |
| 166 |
'' => sub { # this one wont be called by a request to '/test' |
| 167 |
my ($httpd, $req) = @_; |
| 168 |
|
| 169 |
# ... |
| 170 |
} |
| 171 |
); |
| 172 |
|
| 173 |
run This method is a simplification of the "AnyEvent" condition variable |
| 174 |
idiom. You can use it instead of writing: |
| 175 |
|
| 176 |
my $cvar = AnyEvent->condvar; |
| 177 |
$cvar->wait; |
| 178 |
|
| 179 |
stop |
| 180 |
This will stop the HTTP server and return from the "run" method if |
| 181 |
you started the server via that method! |
| 182 |
|
| 183 |
EVENTS |
| 184 |
Every request goes to a specific URL. After a (GET or POST) request is |
| 185 |
received the URL's path segments are walked down and for each segment a |
| 186 |
event is generated. An example: |
| 187 |
|
| 188 |
If the URL '/test/bla.jpg' is requestes following events will be |
| 189 |
generated: |
| 190 |
|
| 191 |
'/test/bla.jpg' - the event for the last segment |
| 192 |
'/test' - the event for the 'test' segment |
| 193 |
'' - the root event of each request |
| 194 |
|
| 195 |
To actually handle any request you just have to register a callback for |
| 196 |
the event name with the empty string. To handle all requests in the |
| 197 |
'/test' directory you have to register a callback for the event with the |
| 198 |
name '/test'. Here is an example how to register an event for the |
| 199 |
example URL above: |
| 200 |
|
| 201 |
$httpd->reg_cb ( |
| 202 |
'/test/bla.jpg' => sub { |
| 203 |
my ($httpd, $req) = @_; |
| 204 |
|
| 205 |
$req->respond ([200, 'ok', { 'Content-Type' => 'text/html' }, '<h1>Test</h1>' }]); |
| 206 |
} |
| 207 |
); |
| 208 |
|
| 209 |
See also "stop_request" about stopping the walk of the path segments. |
| 210 |
|
| 211 |
The first argument to such a callback is always the AnyEvent::HTTPD |
| 212 |
object itself. The second argument ($req) is the |
| 213 |
AnyEvent::HTTPD::Request object for this request. It can be used to get |
| 214 |
the (possible) form parameters for this request or the transmitted |
| 215 |
content and respond to the request. |
| 216 |
|
| 217 |
Along with the above mentioned events these events are also provided: |
| 218 |
|
| 219 |
request => $req |
| 220 |
Every request also emits the "request" event, with the same |
| 221 |
arguments and semantics as the above mentioned path request events. |
| 222 |
You can use this to implement your own request multiplexing. You can |
| 223 |
use "stop_request" to stop any further processing of the request as |
| 224 |
the "request" event is the first thing that is executed for an |
| 225 |
incoming request. |
| 226 |
|
| 227 |
An example of one of many possible uses: |
| 228 |
|
| 229 |
$httpd->reg_cb ( |
| 230 |
request => sub { |
| 231 |
my ($httpd, $req) = @_; |
| 232 |
|
| 233 |
my $url = $req->url; |
| 234 |
|
| 235 |
if ($url->path =~ /\/images\/img_(\d+).jpg$/) { |
| 236 |
handle_image_request ($req, $1); # your task :) |
| 237 |
|
| 238 |
# stop the request from emitting further events |
| 239 |
# so that the '/images/img_001.jpg' and the |
| 240 |
# '/images' and '' events are NOT emitted: |
| 241 |
$httpd->stop_request; |
| 242 |
} |
| 243 |
} |
| 244 |
); |
| 245 |
|
| 246 |
client_connected => $host, $port |
| 247 |
client_disconnected => $host, $port |
| 248 |
These events are emitted whenever a client coming from "$host:$port" |
| 249 |
connects to your server or is disconnected from it. |
| 250 |
|
| 251 |
CACHING |
| 252 |
Any response from the HTTP server will have "Cache-Control" set to |
| 253 |
"max-age=0" and also the "Expires" header set to the "Date" header. |
| 254 |
Meaning: Caching is disabled. |
| 255 |
|
| 256 |
You can of course set those headers yourself in the response, or remove |
| 257 |
them by setting them to undef, but keep in mind that the default for |
| 258 |
those headers are like mentioned above. |
| 259 |
|
| 260 |
If you need more support here you can send me a mail or even better: a |
| 261 |
patch :) |
| 262 |
|
| 263 |
AUTHOR |
| 264 |
Robin Redeker, "<elmex at ta-sa.org>" |
| 265 |
|
| 266 |
BUGS |
| 267 |
Please report any bugs or feature requests to "bug-bs-httpd at |
| 268 |
rt.cpan.org", or through the web interface at |
| 269 |
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=AnyEvent-HTTPD>. I will |
| 270 |
be notified, and then you'll automatically be notified of progress on |
| 271 |
your bug as I make changes. |
| 272 |
|
| 273 |
SUPPORT |
| 274 |
You can find documentation for this module with the perldoc command. |
| 275 |
|
| 276 |
perldoc AnyEvent::HTTPD |
| 277 |
|
| 278 |
You can also look for information at: |
| 279 |
|
| 280 |
* Git repository |
| 281 |
|
| 282 |
<http://git.ta-sa.org/AnyEvent-HTTPD.git> |
| 283 |
|
| 284 |
* RT: CPAN's request tracker |
| 285 |
|
| 286 |
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=AnyEvent-HTTPD> |
| 287 |
|
| 288 |
* AnnoCPAN: Annotated CPAN documentation |
| 289 |
|
| 290 |
<http://annocpan.org/dist/AnyEvent-HTTPD> |
| 291 |
|
| 292 |
* CPAN Ratings |
| 293 |
|
| 294 |
<http://cpanratings.perl.org/d/AnyEvent-HTTPD> |
| 295 |
|
| 296 |
* Search CPAN |
| 297 |
|
| 298 |
<http://search.cpan.org/dist/AnyEvent-HTTPD> |
| 299 |
|
| 300 |
ACKNOWLEDGEMENTS |
| 301 |
Andrey Smirnov - for keep-alive patches. |
| 302 |
Pedro Melo - for valuable input in general and patches. |
| 303 |
Nicholas Harteau - patch for ';' pair separator support, |
| 304 |
patch for allowed_methods support |
| 305 |
Chris Kastorff - patch for making default headers removable |
| 306 |
and more fault tolerant w.r.t. case. |
| 307 |
Mons Anderson - Optimizing the regexes in L<AnyEvent::HTTPD::HTTPConnection> |
| 308 |
and adding the C<backlog> option to L<AnyEvent::HTTPD>. |
| 309 |
|
| 310 |
COPYRIGHT & LICENSE |
| 311 |
Copyright 2008-2011 Robin Redeker, all rights reserved. |
| 312 |
|
| 313 |
This program is free software; you can redistribute it and/or modify it |
| 314 |
under the same terms as Perl itself. |
| 315 |
|