1Net::Server::HTTP(3) User Contributed Perl Documentation Net::Server::HTTP(3)
2
6 Net::Server::HTTP - very basic Net::Server based HTTP server class
7
9 perl -e 'use base qw(Net::Server::HTTP); main->run(port => 8080)'
10 # will start up an echo server
11
13 use base qw(Net::Server::HTTP);
14 __PACKAGE__->run;
15 sub process_http_request {
17 my $self = shift;
18 print "Content-type: text/html\n\n";
20 print "<form method=post action=/bam><input type=text name=foo><input type=submit></form>\n";
21 require Data::Dumper;
23 local $Data::Dumper::Sortkeys = 1;
24 require CGI;
26 my $form = {};
27 my $q = CGI->new; $form->{$_} = $q->param($_) for $q->param;
28 print "<pre>".Data::Dumper->Dump([\%ENV, $form], ['*ENV', 'form'])."</pre>";
30 }
31
33 Even though Net::Server::HTTP doesn't fall into the normal parallel of
34 the other Net::Server flavors, handling HTTP requests is an often
35 requested feature and is a standard and simple protocol.
36 Net::Server::HTTP begins with base type MultiType defaulting to
38 Net::Server::Fork. It is easy to change it to any of the other
39 Net::Server flavors by passing server_type => $other_flavor in the
40 server configurtation. The port has also been defaulted to port 80 -
41 but could easily be changed to another through the server
42 configuration. You can also very easily add ssl by including,
43 proto=>"ssl" and provide a SSL_cert_file and SSL_key_file.
44 For example, here is a basic server that will bind to all interfaces,
46 will speak both HTTP on port 8080 as well as HTTPS on 8443, and will
47 speak both IPv4, as well as IPv6 if it is available.
48 use base qw(Net::Server::HTTP);
50 __PACKAGE__->run(
52 port => [8080, "8443/ssl"],
53 ipv => '*', # IPv6 if available
54 SSL_key_file => '/my/key',
55 SSL_cert_file => '/my/cert',
56 );
57
59 "_init_access_log"
60 Used to open and initialize any requested access_log (see
61 access_log_file and access_log_format).
62 "_tie_client_stdout"
64 Used to initialize automatic response header parsing.
65 "process_http_request"
67 Will be passed the client handle, and will have STDOUT and STDIN
68 tied to the client.
69 During this method, the %ENV will have been set to a standard CGI
71 style environment. You will need to be sure to print the Content-
72 type header. This is one change from the other standard
73 Net::Server base classes.
74 During this method you can read from %ENV and STDIN just like a
76 normal HTTP request in other web servers. You can print to STDOUT
77 and Net::Server will handle the header negotiation for you.
78 Note: Net::Server::HTTP has no concept of document root or script
80 aliases or default handling of static content. That is up to the
81 consumer of Net::Server::HTTP to work out.
82 Net::Server::HTTP comes with a basic %ENV display installed as the
84 default process_http_request method.
85 "process_request"
87 This method has been overridden in Net::Server::HTTP - you should
88 not use it while using Net::Server::HTTP. This overridden method
89 parses the environment and sets up request alarms and handles dying
90 failures. It calls process_http_request once the request is ready
91 and headers have been parsed.
92 "process_headers"
94 Used to read in the incoming headers and set the ENV.
95 "_init_http_request_info"
97 Called at the end of process_headers. Initializes the contents of
98 http_request_info.
99 "http_request_info"
101 Returns a hashref of information specific to the current request.
102 This information will be used for logging later on.
103 "send_status"
105 Takes an HTTP status and a message. Sends out the correct headers.
106 "send_500"
108 Calls send_status with 500 and the argument passed to send_500.
109 c<log_http_request>
111 Called at the end of post_process_request. The default method
112 looks for the default access_log_format and checks if logging was
113 initilized during _init_access_log. If both of these exist, the
114 http_request_info is formatted using http_log_format and the result
115 is logged.
116 "http_log_format"
118 Takes a format string, and request_info and returns a formatted
119 string. The format should follow the apache mod_log_config
120 specification. As in the mod_log_config specification,
121 backslashes, quotes should be escaped with backslashes and you may
122 also include \n and \t characters as well.
123 The following is a listing of the available parameters as well as
125 sample output based on a very basic HTTP server.
126 %% % # a percent
128 %a ::1 # remote ip
129 %A ::1 # local ip
130 %b 83 # response size (- if 0) Common Log Format
131 %B 83 # response size
132 %{bar}C baz # value of cookie by that name
133 %D 916 # elapsed in microseconds
134 %{HTTP_COOKIE}e bar=baz # value of %ENV by that name
135 %f - # filename - unused
136 %h ::1 # remote host if lookups are on, remote ip otherwise
137 %H http # request protocol
138 %{Host}i localhost:8080 # request header by that name
139 %I 336 # bytes received including headers
140 %l - # remote logname - unsused
141 %m GET # request method
142 %n Just a note # http_note by that name
143 %{Content-type}o text/html # output header by that name
144 %O 189 # response size including headers
145 %p 8080 # server port
146 %P 22999 # pid - does not support %{tid}P
147 q ?hello=there # query_string including ? (- otherwise)
148 r GET /bam?hello=there HTTP/1.1 # the first line of the request
149 %s 200 # response status
150 %u - # remote user - unused
151 %U /bam # request path (no query string)
152 %t [06/Jun/2012:12:14:21 -0600] # http_log_time standard format
153 %t{%F %T %z}t [2012-06-06 12:14:21 -0600] # http_log_time with format
154 %T 0 # elapsed time in seconds
155 %v localhost:8080 # http_log_vhost - partial implementation
156 %V localhost:8080 # http_log_vhost - partial implementation
157 %X - # Connection completed and is 'close' (-)
158 Additionally, the log parsing allows for the following formats.
160 %>s 200 # status of last request
162 %<s 200 # status of original request
163 %400a - # remote ip if status is 400
164 %!400a ::1 # remote ip if status is not 400
165 %!200a - # remote ip if status is not 200
166 There are few bits not completely implemented:
168 > and < # There is no internal redirection
170 %I # The answer to this is based on header size and Content-length
171 instead of the more correct actual number of bytes read though
172 in common cases those would be the same.
173 %X # There is no Connection keepalive in the default server.
174 %v and %V # There are no virtual hosts in the default HTTP server.
175 %{tid}P # The default servers are not threaded.
176 See the "access_log_format" option for how to set a different
178 format as well as to see the default string.
179 "exec_cgi"
181 Allow for calling an external script as a CGI. This will use
182 IPC::Open3 to fork a new process and read/write from it.
183 use base qw(Net::Server::HTTP);
185 __PACKAGE__->run;
186 sub process_http_request {
188 my $self = shift;
189 if ($ENV{'PATH_INFO'} && $ENV{'PATH_INFO'} =~ s{^ (/foo) (?= $ | /) }{}x) {
191 $ENV{'SCRIPT_NAME'} = $1;
192 my $file = "/var/www/cgi-bin/foo"; # assuming this exists
193 return $self->exec_cgi($file);
194 }
195 print "Content-type: text/html\n\n";
197 print "<a href=/foo>Foo</a>";
198 }
199 At this first release, the parent server is not tracking the child
201 script which may cause issues if the script is running when a HUP
202 is received.
203 "http_log_time"
205 Used to implement the %t format.
206 "http_log_env"
208 Used to implement the %e format.
209 "http_log_cookie"
211 Used to implement the %C format.
212 "http_log_header_in"
214 used to implement the %i format.
215 "http_log_note"
217 Used to implement the %n format.
218 "http_note"
220 Takes a key and an optional value. If passed a key and value, sets
221 the note for that key. Always returns the value. These notes
222 currently only are used for %{key}n output format.
223 "http_log_header_out"
225 Used to implement the %o format.
226 "http_log_pid"
228 Used to implement the %P format.
229 "http_log_vhost"
231 Used to implement the %v and %V formats.
232 "http_log_constat"
234 Used to implement the %X format.
235 "exec_trusted_perl"
237 Allow for calling an external perl script. This method will still
238 fork, but instead of using IPC::Open3, it simply requires the perl
239 script. That means that the running script will be able to make
240 use of any shared memory. It also means that the
241 STDIN/STDOUT/STDERR handles the script is using are those directly
242 bound by the server process.
243 use base qw(Net::Server::HTTP);
245 __PACKAGE__->run;
246 sub process_http_request {
248 my $self = shift;
249 if ($ENV{'PATH_INFO'} && $ENV{'PATH_INFO'} =~ s{^ (/foo) (?= $ | /) }{}x) {
251 $ENV{'SCRIPT_NAME'} = $1;
252 my $file = "/var/www/cgi-bin/foo"; # assuming this exists
253 return $self->exec_trusted_perl($file);
254 }
255 print "Content-type: text/html\n\n";
257 print "<a href=/foo>Foo</a>";
258 }
259 At this first release, the parent server is not tracking the child
261 script which may cause issues if the script is running when a HUP
262 is received.
263 "exec_fork_hook"
265 This method is called after the fork of exec_trusted_perl and
266 exec_cgi hooks. It is passed the pid (0 if the child) and the file
267 being ran. Note, that the hook will not be called from the child
268 during exec_cgi.
269 "http_dispatch"
271 Called if the default process_http_request and process_request
272 methods have not been overridden and "app" configuration parameters
273 have been passed. In this case this replaces the default echo
274 server. You can also enable this subsystem for your own direct use
275 by setting enable_dispatch to true during configuration. See the
276 "app" configuration item. It will be passed a dispatch qr (regular
277 expression) generated during _check_dispatch, and a dispatch table.
278 The qr will be applied to path_info. This mechanism could be used
279 to augment Net::Server::HTTP with document root and virtual host
280 capabilities.
281
283 In addition to the command line arguments of the Net::Server base
284 classes you can also set the following options.
285 max_header_size
287 Defaults to 100_000. Maximum number of bytes to read while parsing
288 headers.
289 server_revision
291 Defaults to Net::Server::HTTP/$Net::Server::VERSION.
292 timeout_header
294 Defaults to 15 - number of seconds to wait for parsing headers.
295 timeout_idle
297 Defaults to 60 - number of seconds a request can be idle before the
298 request is closed.
299 access_log_file
301 Defaults to undef. If true, this represents the location of where
302 the access log should be written to. If a special value of STDERR
303 is passed, the access log entry will be writing to the same
304 location as the ERROR log.
305 access_log_format
307 Should be a valid apache log format that will be passed to
308 http_log_format. See the http_log_format method for more
309 information.
310 The default value is the NCSA extended/combined log format:
312 '%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"'
314 app Takes one or more items and registers them for dispatch. Arguments
316 may be supplied as an arrayref containing a location/target pairs,
317 a hashref containing a location/target pairs, a bare code ref that
318 will use "/" as the location and the codref as the target, a string
319 with a space indicating "location target", a string containing
320 "location=target", or finally a string that will be used as both
321 location and target. For items passed as an arrayref or hashref,
322 the target may be a coderef which will be called and should handle
323 the request. In all other cases the target should be a valid
324 executable suitable for passing to exec_cgi.
325 The locations will be added in the order that they are configured.
327 They will be added to a regular expression which will be applied to
328 the incoming PATH_INFO string. If the match is successful, the
329 $ENV{'SCRIPT_NAME'} will be set to the matched portion and the
330 matched portion will be removed from $ENV{'PATH_INFO'}.
331 Once an app has been passed, it is necessary for the server to
333 listen on /. Therefore if "/" has not been specifically configured
334 for dispatch, the first found dispatch target will also be used to
335 handle "/".
336 For convenience, if the log_level is 2 or greater, the dispatch
338 table is output to the log.
339 This mechanism is left as a generic mechanism suitable for
341 overriding by servers meant to handle more complex dispatch. At
342 the moment there is no handling of virtual hosts. At some point we
343 will add in the default ability to play static content and likely
344 for the ability to configure virtual hosts - or that may have to
345 wait for a third party module.
346 app => "/home/paul/foo.cgi",
348 # Dispatch: /home/paul/foo.cgi => home/paul/foo.cgi
349 # Dispatch: / => home/paul/foo.cgi (default)
350 app => "../../foo.cgi",
353 app => "./bar.cgi",
354 app => "baz ./bar.cgi",
355 app => "bim=./bar.cgi",
356 # Dispatch: /foo.cgi => ../../foo.cgi
357 # Dispatch: /bar.cgi => ./bar.cgi
358 # Dispatch: /baz => ./bar.cgi
359 # Dispatch: /bim => ./bar.cgi
360 # Dispatch: / => ../../foo.cgi (default)
361 app => "../../foo.cgi",
364 app => "/=./bar.cgi",
365 # Dispatch: /foo.cgi => ../../foo.cgi
366 # Dispatch: / => ./bar.cgi
367 # you could also do this on the commandline
369 net-server HTTP app ../../foo.cgi app /=./bar.cgi
370 # extended options when configured from code
372 Net::Server::HTTP->run(app => { # loses order of matching
374 '/' => sub { ... },
375 '/foo' => sub { ... },
376 '/bar' => '/path/to/some.cgi',
377 });
378 Net::Server::HTTP->run(app => [
380 '/' => sub { ... },
381 '/foo' => sub { ... },
382 '/bar' => '/path/to/some.cgi',
383 ]);
384
386 Add support for writing out HTTP/1.1.
387
389 Paul T. Seamons paul@seamons.com
390
392 See Net::Server
393
395 Please see also Net::Server::Fork, Net::Server::INET,
396 Net::Server::PreFork, Net::Server::PreForkSimple,
397 Net::Server::MultiType, Net::Server::Single Net::Server::SIG
398 Net::Server::Daemonize Net::Server::Proto
399perl v5.26.3 2017-08-10 Net::Server::HTTP(3)