1HTTP::Server::Simple(3)User Contributed Perl DocumentatioHnTTP::Server::Simple(3)
2
6 HTTP::Server::Simple - Lightweight HTTP server
7
9 use warnings;
10 use strict;
11 use HTTP::Server::Simple;
13 my $server = HTTP::Server::Simple->new();
15 $server->run();
16 However, normally you will sub-class the HTTP::Server::Simple::CGI
18 module (see HTTP::Server::Simple::CGI);
19 package Your::Web::Server;
21 use base qw(HTTP::Server::Simple::CGI);
22 sub handle_request {
24 my ($self, $cgi) = @_;
25 #... do something, print output to default
27 # selected filehandle...
28 }
30 1;
32
34 This is a simple standalone HTTP server. By default, it doesn't thread
35 or fork. It does, however, act as a simple frontend which can be used
36 to build a standalone web-based application or turn a CGI into one.
37 It is possible to use Net::Server classes to create forking, pre-
39 forking, and other types of more complicated servers; see "net_server".
40 By default, the server traps a few signals:
42 HUP When you "kill -HUP" the server, it lets the current request finish
44 being processed, then uses the "restart" method to re-exec itself.
45 Please note that in order to provide restart-on-SIGHUP,
46 HTTP::Server::Simple sets a SIGHUP handler during initialisation.
47 If your request handling code forks you need to make sure you reset
48 this or unexpected things will happen if somebody sends a HUP to
49 all running processes spawned by your app (e.g. by "kill -HUP
50 <script>")
51 PIPE
53 If the server detects a broken pipe while writing output to the
54 client, it ignores the signal. Otherwise, a client closing the
55 connection early could kill the server.
56
58 #!/usr/bin/perl
59 {
60 package MyWebServer;
61 use HTTP::Server::Simple::CGI;
63 use base qw(HTTP::Server::Simple::CGI);
64 my %dispatch = (
66 '/hello' => \&resp_hello,
67 # ...
68 );
69 sub handle_request {
71 my $self = shift;
72 my $cgi = shift;
73 my $path = $cgi->path_info();
75 my $handler = $dispatch{$path};
76 if (ref($handler) eq "CODE") {
78 print "HTTP/1.0 200 OK\r\n";
79 $handler->($cgi);
80 } else {
82 print "HTTP/1.0 404 Not found\r\n";
83 print $cgi->header,
84 $cgi->start_html('Not found'),
85 $cgi->h1('Not found'),
86 $cgi->end_html;
87 }
88 }
89 sub resp_hello {
91 my $cgi = shift; # CGI.pm object
92 return if !ref $cgi;
93 my $who = $cgi->param('name');
95 print $cgi->header,
97 $cgi->start_html("Hello"),
98 $cgi->h1("Hello $who!"),
99 $cgi->end_html;
100 }
101 }
103 # start the server on port 8080
105 my $pid = MyWebServer->new(8080)->background();
106 print "Use 'kill $pid' to stop server.\n";
107
109 HTTP::Server::Simple->new($port, $family)
110 API call to start a new server. Does not actually start listening
111 until you call "->run()". If omitted, $port defaults to 8080, and
112 $family defaults to Socket::AF_INET. The alternative domain is
113 Socket::AF_INET6.
114 lookup_localhost
116 Looks up the local host's IP address, and returns it. For most hosts,
117 this is 127.0.0.1, or possibly "::1".
118 port [NUMBER]
120 Takes an optional port number for this server to listen on.
121 Returns this server's port. (Defaults to 8080)
123 family [NUMBER]
125 Takes an optional address family for this server to use. Valid values
126 are Socket::AF_INET and Socket::AF_INET6. All other values are
127 silently changed into Socket::AF_INET for backwards compatibility with
128 previous versions of the module.
129 Returns the address family of the present listening socket. (Defaults
131 to Socket::AF_INET.)
132 host [address]
134 Takes an optional host address for this server to bind to.
135 Returns this server's bound address (if any). Defaults to "undef"
137 (bind to all interfaces).
138 background [ARGUMENTS]
140 Runs the server in the background, and returns the process ID of the
141 started process. Any arguments will be passed through to "run".
142 run [ARGUMENTS]
144 Run the server. If all goes well, this won't ever return, but it will
145 start listening for "HTTP" requests. Any arguments passed to this will
146 be passed on to the underlying Net::Server implementation, if one is
147 used (see "net_server").
148 net_server
150 User-overridable method. If you set it to a Net::Server subclass, that
151 subclass is used for the "run" method. Otherwise, a minimal
152 implementation is used as default.
153 restart
155 Restarts the server. Usually called by a HUP signal, not directly.
156 stdio_handle [FILEHANDLE]
158 When called with an argument, sets the socket to the server to that
159 arg.
160 Returns the socket to the server; you should only use this for actual
162 socket-related calls like "getsockname". If all you want is to read or
163 write to the socket, you should use "stdin_handle" and "stdout_handle"
164 to get the in and out filehandles explicitly.
165 stdin_handle
167 Returns a filehandle used for input from the client. By default,
168 returns whatever was set with "stdio_handle", but a subclass could do
169 something interesting here.
170 stdout_handle
172 Returns a filehandle used for output to the client. By default,
173 returns whatever was set with "stdio_handle", but a subclass could do
174 something interesting here.
175
177 A selection of these methods should be provided by sub-classes of this
178 module.
179 handler
181 This method is called after setup, with no parameters. It should print
182 a valid, full HTTP response to the default selected filehandle.
183 setup(name => $value, ...)
185 This method is called with a name => value list of various things to do
186 with the request. This list is given below.
187 The default setup handler simply tries to call methods with the names
189 of keys of this list.
190 ITEM/METHOD Set to Example
192 ----------- ------------------ ------------------------
193 method Request Method "GET", "POST", "HEAD"
194 protocol HTTP version "HTTP/1.1"
195 request_uri Complete Request URI "/foobar/baz?foo=bar"
196 path Path part of URI "/foobar/baz"
197 query_string Query String undef, "foo=bar"
198 port Received Port 80, 8080
199 peername Remote name "200.2.4.5", "foo.com"
200 peeraddr Remote address "200.2.4.5", "::1"
201 peerport Remote port 42424
202 localname Local interface "localhost", "myhost.com"
203 headers([Header => $value, ...])
205 Receives HTTP headers and does something useful with them. This is
206 called by the default setup() method.
207 You have lots of options when it comes to how you receive headers.
209 You can, if you really want, define parse_headers() and parse them raw
211 yourself.
212 Secondly, you can intercept them very slightly cooked via the setup()
214 method, above.
215 Thirdly, you can leave the setup() header as-is (or calling the
217 superclass setup() for unknown request items). Then you can define
218 headers() in your sub-class and receive them all at once.
219 Finally, you can define handlers to receive individual HTTP headers.
221 This can be useful for very simple SOAP servers (to name a crack-fueled
222 standard that defines its own special HTTP headers).
223 To do so, you'll want to define the header() method in your subclass.
225 That method will be handed a (key,value) pair of the header name and
226 the value.
227 accept_hook
229 If defined by a sub-class, this method is called directly after an
230 accept happens. An accept_hook to add SSL support might look like
231 this:
232 sub accept_hook {
234 my $self = shift;
235 my $fh = $self->stdio_handle;
236 $self->SUPER::accept_hook(@_);
238 my $newfh =
240 IO::Socket::SSL->start_SSL( $fh,
241 SSL_server => 1,
242 SSL_use_cert => 1,
243 SSL_cert_file => 'myserver.crt',
244 SSL_key_file => 'myserver.key',
245 )
246 or warn "problem setting up SSL socket: " . IO::Socket::SSL::errstr();
247 $self->stdio_handle($newfh) if $newfh;
249 }
250 post_setup_hook
252 If defined by a sub-class, this method is called after all setup has
253 finished, before the handler method.
254 print_banner
256 This routine prints a banner before the server request-handling loop
257 starts.
258 Methods below this point are probably not terribly useful to define
260 yourself in subclasses.
261 parse_request
263 Parse the HTTP request line. Returns three values, the request method,
264 request URI and the protocol.
265 parse_headers
267 Parses incoming HTTP headers from STDIN, and returns an arrayref of
268 "(header => value)" pairs. See "headers" for possibilities on how to
269 inspect headers.
270 setup_listener
272 This routine binds the server to a port and interface.
273 after_setup_listener
275 This method is called immediately after setup_listener. It's here just
276 for you to override.
277 bad_request
279 This method should print a valid HTTP response that says that the
280 request was invalid.
281 valid_http_method($method)
283 Given a candidate HTTP method in $method, determine if it is valid.
284 Override if, for example, you'd like to do some WebDAV. The default
285 implementation only accepts "GET", "POST", "HEAD", "PUT", "PATCH",
286 "DELETE" and "OPTIONS".
287
289 Best Practical Solutions, LLC <modules@bestpractical.com>
290
292 Jesse Vincent, <jesse@bestpractical.com>. Original author.
293 Marcus Ramberg <drave@thefeed.no> contributed tests, cleanup, etc
295 Sam Vilain, <samv@cpan.org> contributed the CGI.pm split-out and
297 header/setup API.
298 Example section by almut on perlmonks, suggested by Mark Fuller.
300
302 There certainly are some. Please report them via rt.cpan.org
303
305 This software is Copyright (c) 2004-2015 Best Practical Solutions
306 This library is free software; you can redistribute it and/or modify it
308 under the same terms as Perl itself.
309perl v5.36.0 2023-01-20 HTTP::Server::Simple(3)