local-lib5/man/man3/HTTP::Server::Simple.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "HTTP::Server::Simple 3"
 127 .TH HTTP::Server::Simple 3 "2009-09-29" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 HTTP::Server::Simple \- Lightweight HTTP server
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 2
 137 \& use warnings;
 138 \& use strict;
 139 \&
 140 \& use HTTP::Server::Simple;
 141 \&
 142 \& my $server = HTTP::Server::Simple\->new();
 143 \& $server\->run();
 144 .Ve
 145 .PP
 146 However, normally you will sub-class the HTTP::Server::Simple::CGI
 147 module (see HTTP::Server::Simple::CGI);
 148 .PP
 149 .Vb 2
 150 \& package Your::Web::Server;
 151 \& use base qw(HTTP::Server::Simple::CGI);
 152 \&
 153 \& sub handle_request {
 154 \&     my ($self, $cgi) = @_;
 155 \&
 156 \&     #... do something, print output to default
 157 \&     # selected filehandle...
 158 \&
 159 \& }
 160 \&
 161 \& 1;
 162 .Ve
 163 .SH "DESCRIPTION"
 164 .IX Header "DESCRIPTION"
 165 This is a simple standalone \s-1HTTP\s0 server. By default, it doesn't thread
 166 or fork. It does, however, act as a simple frontend which can be used
 167 to build a standalone web-based application or turn a \s-1CGI\s0 into one.
 168 .PP
 169 It is possible to use Net::Server classes to create forking,
 170 pre-forking, and other types of more complicated servers; see
 171 \&\*(L"net_server\*(R".
 172 .PP
 173 By default, the server traps a few signals:
 174 .IP "\s-1HUP\s0" 4
 175 .IX Item "HUP"
 176 When you \f(CW\*(C`kill \-HUP\*(C'\fR the server, it lets the current request finish being
 177 processed, then uses the \f(CW\*(C`restart\*(C'\fR method to re-exec itself. Please note that
 178 in order to provide restart-on-SIGHUP, HTTP::Server::Simple sets a \s-1SIGHUP\s0
 179 handler during initialisation. If your request handling code forks you need to
 180 make sure you reset this or unexpected things will happen if somebody sends a
 181 \&\s-1HUP\s0 to all running processes spawned by your app (e.g. by \*(L"kill \-HUP <script>\*(R")
 182 .IP "\s-1PIPE\s0" 4
 183 .IX Item "PIPE"
 184 If the server detects a broken pipe while writing output to the client,
 185 it ignores the signal. Otherwise, a client closing the connection early
 186 could kill the server.
 187 .SH "EXAMPLE"
 188 .IX Header "EXAMPLE"
 189 .Vb 3
 190 \& #!/usr/bin/perl
 191 \& {
 192 \& package MyWebServer;
 193 \&
 194 \& use HTTP::Server::Simple::CGI;
 195 \& use base qw(HTTP::Server::Simple::CGI);
 196 \&
 197 \& my %dispatch = (
 198 \&     \*(Aq/hello\*(Aq => \e&resp_hello,
 199 \&     # ...
 200 \& );
 201 \&
 202 \& sub handle_request {
 203 \&     my $self = shift;
 204 \&     my $cgi  = shift;
 205 \&
 206 \&     my $path = $cgi\->path_info();
 207 \&     my $handler = $dispatch{$path};
 208 \&
 209 \&     if (ref($handler) eq "CODE") {
 210 \&         print "HTTP/1.0 200 OK\er\en";
 211 \&         $handler\->($cgi);
 212 \&
 213 \&     } else {
 214 \&         print "HTTP/1.0 404 Not found\er\en";
 215 \&         print $cgi\->header,
 216 \&               $cgi\->start_html(\*(AqNot found\*(Aq),
 217 \&               $cgi\->h1(\*(AqNot found\*(Aq),
 218 \&               $cgi\->end_html;
 219 \&     }
 220 \& }
 221 \&
 222 \& sub resp_hello {
 223 \&     my $cgi  = shift;   # CGI.pm object
 224 \&     return if !ref $cgi;
 225 \&
 226 \&     my $who = $cgi\->param(\*(Aqname\*(Aq);
 227 \&
 228 \&     print $cgi\->header,
 229 \&           $cgi\->start_html("Hello"),
 230 \&           $cgi\->h1("Hello $who!"),
 231 \&           $cgi\->end_html;
 232 \& }
 233 \&
 234 \& }
 235 \&
 236 \& # start the server on port 8080
 237 \& my $pid = MyWebServer\->new(8080)\->background();
 238 \& print "Use \*(Aqkill $pid\*(Aq to stop server.\en";
 239 .Ve
 240 .SH "METHODS"
 241 .IX Header "METHODS"
 242 .SS "HTTP::Server::Simple\->new($port)"
 243 .IX Subsection "HTTP::Server::Simple->new($port)"
 244 \&\s-1API\s0 call to start a new server.  Does not actually start listening
 245 until you call \f(CW\*(C`\->run()\*(C'\fR.  If omitted, \f(CW$port\fR defaults to 8080.
 246 .SS "lookup_localhost"
 247 .IX Subsection "lookup_localhost"
 248 Looks up the local host's \s-1IP\s0 address, and returns it.  For most hosts,
 249 this is \f(CW127.0.0.1\fR.
 250 .SS "port [\s-1NUMBER\s0]"
 251 .IX Subsection "port [NUMBER]"
 252 Takes an optional port number for this server to listen on.
 253 .PP
 254 Returns this server's port. (Defaults to 8080)
 255 .SS "host [address]"
 256 .IX Subsection "host [address]"
 257 Takes an optional host address for this server to bind to.
 258 .PP
 259 Returns this server's bound address (if any).  Defaults to \f(CW\*(C`undef\*(C'\fR
 260 (bind to all interfaces).
 261 .SS "background [\s-1ARGUMENTS\s0]"
 262 .IX Subsection "background [ARGUMENTS]"
 263 Runs the server in the background, and returns the process \s-1ID\s0 of the
 264 started process.  Any arguments will be passed through to \*(L"run\*(R".
 265 .SS "run [\s-1ARGUMENTS\s0]"
 266 .IX Subsection "run [ARGUMENTS]"
 267 Run the server.  If all goes well, this won't ever return, but it will
 268 start listening for \f(CW\*(C`HTTP\*(C'\fR requests.  Any arguments passed to this
 269 will be passed on to the underlying Net::Server implementation, if
 270 one is used (see \*(L"net_server\*(R").
 271 .SS "net_server"
 272 .IX Subsection "net_server"
 273 User-overridable method. If you set it to a Net::Server subclass,
 274 that subclass is used for the \f(CW\*(C`run\*(C'\fR method.  Otherwise, a minimal
 275 implementation is used as default.
 276 .SS "restart"
 277 .IX Subsection "restart"
 278 Restarts the server. Usually called by a \s-1HUP\s0 signal, not directly.
 279 .SS "stdio_handle [\s-1FILEHANDLE\s0]"
 280 .IX Subsection "stdio_handle [FILEHANDLE]"
 281 When called with an argument, sets the socket to the server to that arg.
 282 .PP
 283 Returns the socket to the server; you should only use this for actual socket-related
 284 calls like \f(CW\*(C`getsockname\*(C'\fR.  If all you want is to read or write to the socket,
 285 you should use \f(CW\*(C`stdin_handle\*(C'\fR and \f(CW\*(C`stdout_handle\*(C'\fR to get the in and out filehandles
 286 explicitly.
 287 .SS "stdin_handle"
 288 .IX Subsection "stdin_handle"
 289 Returns a filehandle used for input from the client.  By default,
 290 returns whatever was set with \f(CW\*(C`stdio_handle\*(C'\fR, but a subclass could do
 291 something interesting here.
 292 .SS "stdout_handle"
 293 .IX Subsection "stdout_handle"
 294 Returns a filehandle used for output to the client.  By default,
 295 returns whatever was set with \f(CW\*(C`stdio_handle\*(C'\fR, but a subclass
 296 could do something interesting here.
 297 .SH "IMPORTANT SUB-CLASS METHODS"
 298 .IX Header "IMPORTANT SUB-CLASS METHODS"
 299 A selection of these methods should be provided by sub-classes of this
 300 module.
 301 .SS "handler"
 302 .IX Subsection "handler"
 303 This method is called after setup, with no parameters.  It should
 304 print a valid, \fIfull\fR \s-1HTTP\s0 response to the default selected
 305 filehandle.
 306 .ie n .SS "setup(name => $value, ...)"
 307 .el .SS "setup(name => \f(CW$value\fP, ...)"
 308 .IX Subsection "setup(name => $value, ...)"
 309 This method is called with a name => value list of various things
 310 to do with the request.  This list is given below.
 311 .PP
 312 The default setup handler simply tries to call methods with the names
 313 of keys of this list.
 314 .PP
 315 .Vb 11
 316 \&  ITEM/METHOD   Set to                Example
 317 \&  \-\-\-\-\-\-\-\-\-\-\-  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-    \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
 318 \&  method       Request Method        "GET", "POST", "HEAD"
 319 \&  protocol     HTTP version          "HTTP/1.1"
 320 \&  request_uri  Complete Request URI  "/foobar/baz?foo=bar"
 321 \&  path         Path part of URI      "/foobar/baz"
 322 \&  query_string Query String          undef, "foo=bar"
 323 \&  port         Received Port         80, 8080
 324 \&  peername     Remote name           "200.2.4.5", "foo.com"
 325 \&  peeraddr     Remote address        "200.2.4.5", "::1"
 326 \&  localname    Local interface       "localhost", "myhost.com"
 327 .Ve
 328 .ie n .SS "headers([Header => $value, ...])"
 329 .el .SS "headers([Header => \f(CW$value\fP, ...])"
 330 .IX Subsection "headers([Header => $value, ...])"
 331 Receives \s-1HTTP\s0 headers and does something useful with them.  This is
 332 called by the default \f(CW\*(C`setup()\*(C'\fR method.
 333 .PP
 334 You have lots of options when it comes to how you receive headers.
 335 .PP
 336 You can, if you really want, define \f(CW\*(C`parse_headers()\*(C'\fR and parse them
 337 raw yourself.
 338 .PP
 339 Secondly, you can intercept them very slightly cooked via the
 340 \&\f(CW\*(C`setup()\*(C'\fR method, above.
 341 .PP
 342 Thirdly, you can leave the \f(CW\*(C`setup()\*(C'\fR header as-is (or calling the
 343 superclass \f(CW\*(C`setup()\*(C'\fR for unknown request items).  Then you can define
 344 \&\f(CW\*(C`headers()\*(C'\fR in your sub-class and receive them all at once.
 345 .PP
 346 Finally, you can define handlers to receive individual \s-1HTTP\s0 headers.
 347 This can be useful for very simple \s-1SOAP\s0 servers (to name a
 348 crack-fueled standard that defines its own special \s-1HTTP\s0 headers).
 349 .PP
 350 To do so, you'll want to define the \f(CW\*(C`header()\*(C'\fR method in your subclass.
 351 That method will be handed a (key,value) pair of the header name and the value.
 352 .SS "accept_hook"
 353 .IX Subsection "accept_hook"
 354 If defined by a sub-class, this method is called directly after an
 355 accept happens.  An accept_hook to add \s-1SSL\s0 support might look like this:
 356 .PP
 357 .Vb 3
 358 \&    sub accept_hook {
 359 \&        my $self = shift;
 360 \&        my $fh   = $self\->stdio_handle;
 361 \&
 362 \&        $self\->SUPER::accept_hook(@_);
 363 \&
 364 \&        my $newfh =
 365 \&        IO::Socket::SSL\->start_SSL( $fh,
 366 \&            SSL_server    => 1,
 367 \&            SSL_use_cert  => 1,
 368 \&            SSL_cert_file => \*(Aqmyserver.crt\*(Aq,
 369 \&            SSL_key_file  => \*(Aqmyserver.key\*(Aq,
 370 \&        )
 371 \&        or warn "problem setting up SSL socket: " . IO::Socket::SSL::errstr();
 372 \&
 373 \&        $self\->stdio_handle($newfh) if $newfh;
 374 \&    }
 375 .Ve
 376 .SS "post_setup_hook"
 377 .IX Subsection "post_setup_hook"
 378 If defined by a sub-class, this method is called after all setup has
 379 finished, before the handler method.
 380 .SS "print_banner"
 381 .IX Subsection "print_banner"
 382 This routine prints a banner before the server request-handling loop
 383 starts.
 384 .PP
 385 Methods below this point are probably not terribly useful to define
 386 yourself in subclasses.
 387 .SS "parse_request"
 388 .IX Subsection "parse_request"
 389 Parse the \s-1HTTP\s0 request line.  Returns three values, the request
 390 method, request \s-1URI\s0 and the protocol.
 391 .SS "parse_headers"
 392 .IX Subsection "parse_headers"
 393 Parses incoming \s-1HTTP\s0 headers from \s-1STDIN\s0, and returns an arrayref of
 394 \&\f(CW\*(C`(header => value)\*(C'\fR pairs.  See \*(L"headers\*(R" for possibilities on
 395 how to inspect headers.
 396 .SS "setup_listener"
 397 .IX Subsection "setup_listener"
 398 This routine binds the server to a port and interface.
 399 .SS "after_setup_listener"
 400 .IX Subsection "after_setup_listener"
 401 This method is called immediately after setup_listener. It's here just
 402 for you to override.
 403 .SS "bad_request"
 404 .IX Subsection "bad_request"
 405 This method should print a valid \s-1HTTP\s0 response that says that the
 406 request was invalid.
 407 .SS "valid_http_method($method)"
 408 .IX Subsection "valid_http_method($method)"
 409 Given a candidate \s-1HTTP\s0 method in \f(CW$method\fR, determine if it is valid.
 410 Override if, for example, you'd like to do some WebDAV.  The default
 411 implementation only accepts \f(CW\*(C`GET\*(C'\fR, \f(CW\*(C`POST\*(C'\fR, \f(CW\*(C`HEAD\*(C'\fR, \f(CW\*(C`PUT\*(C'\fR, and
 412 \&\f(CW\*(C`DELETE\*(C'\fR.
 413 .SH "AUTHOR"
 414 .IX Header "AUTHOR"
 415 Copyright (c) 2004\-2008 Jesse Vincent, <jesse@bestpractical.com>.
 416 All rights reserved.
 417 .PP
 418 Marcus Ramberg <drave@thefeed.no> contributed tests, cleanup, etc
 419 .PP
 420 Sam Vilain, <samv@cpan.org> contributed the \s-1CGI\s0.pm split-out and
 421 header/setup \s-1API\s0.
 422 .PP
 423 Example section by almut on perlmonks, suggested by Mark Fuller.
 424 .SH "BUGS"
 425 .IX Header "BUGS"
 426 There certainly are some. Please report them via rt.cpan.org
 427 .SH "LICENSE"
 428 .IX Header "LICENSE"
 429 This library is free software; you can redistribute it and/or modify
 430 it under the same terms as Perl itself.