Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Net::Server::HTTP(3)  User Contributed Perl Documentation Net::Server::HTTP(3)

NAME
       Net::Server::HTTP - very	basic Net::Server based	HTTP server class

TEST ONE LINER
	   perl	-e 'use	base qw(Net::Server::HTTP); main->run(port => 8080)'
	   # will start	up an echo server

SYNOPSIS
	   use base qw(Net::Server::HTTP);
	   __PACKAGE__->run;

	   sub process_http_request {
	       my $self	= shift;

	       print "Content-type: text/html\n\n";
	       print "<form method=post	action=/bam><input type=text name=foo><input type=submit></form>\n";

	       require Data::Dumper;
	       local $Data::Dumper::Sortkeys = 1;

	       require CGI;
	       my $form	= {};
	       my $q = CGI->new; $form->{$_} = $q->param($_) for $q->param;

	       print "<pre>".Data::Dumper->Dump([\%ENV,	$form],	['*ENV', 'form'])."</pre>";
	   }

DESCRIPTION
       Even though Net::Server::HTTP doesn't fall into the normal parallel of
       the other Net::Server flavors, handling HTTP requests is	an often
       requested feature and is	a standard and simple protocol.

       Net::Server::HTTP begins	with base type MultiType defaulting to
       Net::Server::Fork.  It is easy to change	it to any of the other
       Net::Server flavors by passing server_type => $other_flavor in the
       server configurtation.  The port	has also been defaulted	to port	80 -
       but could easily	be changed to another through the server
       configuration.  You can also very easily	add ssl	by including,
       proto=>"ssl" and	provide	a SSL_cert_file	and SSL_key_file.

       For example, here is a basic server that	will bind to all interfaces,
       will speak both HTTP on port 8080 as well as HTTPS on 8443, and will
       speak both IPv4,	as well	as IPv6	if it is available.

	   use base qw(Net::Server::HTTP);

	   __PACKAGE__->run(
	       port  =>	[8080, "8443/ssl"],
	       ipv   =>	'*', # IPv6 if available
	       SSL_key_file  =>	'/my/key',
	       SSL_cert_file =>	'/my/cert',
	   );

METHODS
       "_init_access_log"
	   Used	to open	and initialize any requested access_log	(see
	   access_log_file and access_log_format).

       "_tie_client_stdout"
	   Used	to initialize automatic	response header	parsing.

       "process_http_request"
	   Will	be passed the client handle, and will have STDOUT and STDIN
	   tied	to the client.

	   During this method, the %ENV	will have been set to a	standard CGI
	   style environment.  You will	need to	be sure	to print the Content-
	   type	header.	 This is one change from the other standard
	   Net::Server base classes.

	   During this method you can read from	%ENV and STDIN just like a
	   normal HTTP request in other	web servers.  You can print to STDOUT
	   and Net::Server will	handle the header negotiation for you.

	   Note: Net::Server::HTTP has no concept of document root or script
	   aliases or default handling of static content.  That	is up to the
	   consumer of Net::Server::HTTP to work out.

	   Net::Server::HTTP comes with	a basic	%ENV display installed as the
	   default process_http_request	method.

       "process_request"
	   This	method has been	overridden in Net::Server::HTTP	- you should
	   not use it while using Net::Server::HTTP.  This overridden method
	   parses the environment and sets up request alarms and handles dying
	   failures.  It calls process_http_request once the request is	ready
	   and headers have been parsed.

       "process_headers"
	   Used	to read	in the incoming	headers	and set	the ENV.

       "_init_http_request_info"
	   Called at the end of	process_headers.  Initializes the contents of
	   http_request_info.

       "http_request_info"
	   Returns a hashref of	information specific to	the current request.
	   This	information will be used for logging later on.

       "send_status"
	   Takes an HTTP status	and a message.	Sends out the correct headers.

       "send_500"
	   Calls send_status with 500 and the argument passed to send_500.

       c<log_http_request>
	   Called at the end of	post_process_request.  The default method
	   looks for the default access_log_format and checks if logging was
	   initilized during _init_access_log.	If both	of these exist,	the
	   http_request_info is	formatted using	http_log_format	and the	result
	   is logged.

       "http_log_format"
	   Takes a format string, and request_info and returns a formatted
	   string.  The	format should follow the apache	mod_log_config
	   specification.  As in the mod_log_config specification,
	   backslashes,	quotes should be escaped with backslashes and you may
	   also	include	\n and \t characters as	well.

	   The following is a listing of the available parameters as well as
	   sample output based on a very basic HTTP server.

	       %%		 %		   # a percent
	       %a		 ::1		   # remote ip
	       %A		 ::1		   # local ip
	       %b		 83		   # response size (- if 0) Common Log Format
	       %B		 83		   # response size
	       %{bar}C		 baz		   # value of cookie by	that name
	       %D		 916		   # elapsed in	microseconds
	       %{HTTP_COOKIE}e	 bar=baz	   # value of %ENV by that name
	       %f		 -		   # filename -	unused
	       %h		 ::1		   # remote host if lookups are	on, remote ip otherwise
	       %H		 http		   # request protocol
	       %{Host}i		 localhost:8080	   # request header by that name
	       %I		 336		   # bytes received including headers
	       %l		 -		   # remote logname - unsused
	       %m		 GET		   # request method
	       %n		 Just a	note	   # http_note by that name
	       %{Content-type}o	 text/html	   # output header by that name
	       %O		 189		   # response size including headers
	       %p		 8080		   # server port
	       %P		 22999		   # pid - does	not support %{tid}P
	       q		 ?hello=there	   # query_string including ? (- otherwise)
	       r		 GET /bam?hello=there HTTP/1.1	    # the first	line of	the request
	       %s		 200		   # response status
	       %u		 -		   # remote user - unused
	       %U		 /bam		   # request path (no query string)
	       %t		 [06/Jun/2012:12:14:21 -0600]	    # http_log_time standard format
	       %t{%F %T	%z}t	 [2012-06-06 12:14:21 -0600]	    # http_log_time with format
	       %T		 0		   # elapsed time in seconds
	       %v		 localhost:8080	   # http_log_vhost - partial implementation
	       %V		 localhost:8080	   # http_log_vhost - partial implementation
	       %X		 -		   # Connection	completed and is 'close' (-)

	   Additionally, the log parsing allows	for the	following formats.

	       %>s		 200		   # status of last request
	       %<s		 200		   # status of original	request
	       %400a		 -		   # remote ip if status is 400
	       %!400a		 ::1		   # remote ip if status is not	400
	       %!200a		 -		   # remote ip if status is not	200

	   There are few bits not completely implemented:

	       > and <	  # There is no	internal redirection
	       %I	  # The	answer to this is based	on header size and Content-length
			    instead of the more	correct	actual number of bytes read though
			    in common cases those would	be the same.
	       %X	  # There is no	Connection keepalive in	the default server.
	       %v and %V  # There are no virtual hosts in the default HTTP server.
	       %{tid}P	  # The	default	servers	are not	threaded.

	   See the "access_log_format" option for how to set a different
	   format as well as to	see the	default	string.

       "exec_cgi"
	   Allow for calling an	external script	as a CGI.  This	will use
	   IPC::Open3 to fork a	new process and	read/write from	it.

	       use base	qw(Net::Server::HTTP);
	       __PACKAGE__->run;

	       sub process_http_request	{
		   my $self = shift;

		   if ($ENV{'PATH_INFO'} && $ENV{'PATH_INFO'} =~ s{^ (/foo) (?=	$ | /) }{}x) {
		      $ENV{'SCRIPT_NAME'} = $1;
		      my $file = "/var/www/cgi-bin/foo"; # assuming this exists
		      return $self->exec_cgi($file);
		   }

		   print "Content-type:	text/html\n\n";
		   print "<a href=/foo>Foo</a>";
	       }

	   At this first release, the parent server is not tracking the	child
	   script which	may cause issues if the	script is running when a HUP
	   is received.

       "http_log_time"
	   Used	to implement the %t format.

       "http_log_env"
	   Used	to implement the %e format.

       "http_log_cookie"
	   Used	to implement the %C format.

       "http_log_header_in"
	   used	to implement the %i format.

       "http_log_note"
	   Used	to implement the %n format.

       "http_note"
	   Takes a key and an optional value.  If passed a key and value, sets
	   the note for	that key.  Always returns the value.  These notes
	   currently only are used for %{key}n output format.

       "http_log_header_out"
	   Used	to implement the %o format.

       "http_log_pid"
	   Used	to implement the %P format.

       "http_log_vhost"
	   Used	to implement the %v and	%V formats.

       "http_log_constat"
	   Used	to implement the %X format.

       "exec_trusted_perl"
	   Allow for calling an	external perl script.  This method will	still
	   fork, but instead of	using IPC::Open3, it simply requires the perl
	   script.  That means that the	running	script will be able to make
	   use of any shared memory.  It also means that the
	   STDIN/STDOUT/STDERR handles the script is using are those directly
	   bound by the	server process.

	       use base	qw(Net::Server::HTTP);
	       __PACKAGE__->run;

	       sub process_http_request	{
		   my $self = shift;

		   if ($ENV{'PATH_INFO'} && $ENV{'PATH_INFO'} =~ s{^ (/foo) (?=	$ | /) }{}x) {
		      $ENV{'SCRIPT_NAME'} = $1;
		      my $file = "/var/www/cgi-bin/foo"; # assuming this exists
		      return $self->exec_trusted_perl($file);
		   }

		   print "Content-type:	text/html\n\n";
		   print "<a href=/foo>Foo</a>";
	       }

	   At this first release, the parent server is not tracking the	child
	   script which	may cause issues if the	script is running when a HUP
	   is received.

       "exec_fork_hook"
	   This	method is called after the fork	of exec_trusted_perl and
	   exec_cgi hooks.  It is passed the pid (0 if the child) and the file
	   being ran.  Note, that the hook will	not be called from the child
	   during exec_cgi.

       "http_dispatch"
	   Called if the default process_http_request and process_request
	   methods have	not been overridden and	"app" configuration parameters
	   have	been passed.  In this case this	replaces the default echo
	   server.  You	can also enable	this subsystem for your	own direct use
	   by setting enable_dispatch to true during configuration.  See the
	   "app" configuration item.  It will be passed	a dispatch qr (regular
	   expression) generated during	_check_dispatch, and a dispatch	table.
	   The qr will be applied to path_info.	 This mechanism	could be used
	   to augment Net::Server::HTTP	with document root and virtual host
	   capabilities.

OPTIONS
       In addition to the command line arguments of the	Net::Server base
       classes you can also set	the following options.

       max_header_size
	   Defaults to 100_000.	 Maximum number	of bytes to read while parsing
	   headers.

       server_revision
	   Defaults to Net::Server::HTTP/$Net::Server::VERSION.

       timeout_header
	   Defaults to 15 - number of seconds to wait for parsing headers.

       timeout_idle
	   Defaults to 60 - number of seconds a	request	can be idle before the
	   request is closed.

       access_log_file
	   Defaults to undef.  If true,	this represents	the location of	where
	   the access log should be written to.	 If a special value of STDERR
	   is passed, the access log entry will	be writing to the same
	   location as the ERROR log.

       access_log_format
	   Should be a valid apache log	format that will be passed to
	   http_log_format.  See the http_log_format method for	more
	   information.

	   The default value is	the NCSA extended/combined log format:

	       '%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"'

       app Takes one or	more items and registers them for dispatch.  Arguments
	   may be supplied as an arrayref containing a location/target pairs,
	   a hashref containing	a location/target pairs, a bare	code ref that
	   will	use "/"	as the location	and the	codref as the target, a	string
	   with	a space	indicating "location target", a	string containing
	   "location=target", or finally a string that will be used as both
	   location and	target.	 For items passed as an	arrayref or hashref,
	   the target may be a coderef which will be called and	should handle
	   the request.	 In all	other cases the	target should be a valid
	   executable suitable for passing to exec_cgi.

	   The locations will be added in the order that they are configured.
	   They	will be	added to a regular expression which will be applied to
	   the incoming	PATH_INFO string.  If the match	is successful, the
	   $ENV{'SCRIPT_NAME'} will be set to the matched portion and the
	   matched portion will	be removed from	$ENV{'PATH_INFO'}.

	   Once	an app has been	passed,	it is necessary	for the	server to
	   listen on /.	 Therefore if "/" has not been specifically configured
	   for dispatch, the first found dispatch target will also be used to
	   handle "/".

	   For convenience, if the log_level is	2 or greater, the dispatch
	   table is output to the log.

	   This	mechanism is left as a generic mechanism suitable for
	   overriding by servers meant to handle more complex dispatch.	 At
	   the moment there is no handling of virtual hosts.  At some point we
	   will	add in the default ability to play static content and likely
	   for the ability to configure	virtual	hosts -	or that	may have to
	   wait	for a third party module.

	       app => "/home/paul/foo.cgi",
		 # Dispatch: /home/paul/foo.cgi	=> home/paul/foo.cgi
		 # Dispatch: / => home/paul/foo.cgi (default)

	       app => "../../foo.cgi",
	       app => "./bar.cgi",
	       app => "baz ./bar.cgi",
	       app => "bim=./bar.cgi",
		 # Dispatch: /foo.cgi => ../../foo.cgi
		 # Dispatch: /bar.cgi => ./bar.cgi
		 # Dispatch: /baz => ./bar.cgi
		 # Dispatch: /bim => ./bar.cgi
		 # Dispatch: / => ../../foo.cgi	(default)

	       app => "../../foo.cgi",
	       app => "/=./bar.cgi",
		 # Dispatch: /foo.cgi => ../../foo.cgi
		 # Dispatch: / => ./bar.cgi

	       # you could also	do this	on the commandline
	       net-server HTTP app ../../foo.cgi app /=./bar.cgi

	       # extended options when configured from code

	       Net::Server::HTTP->run(app => { # loses order of	matching
		 '/' =>	sub { ... },
		 '/foo'	=> sub { ... },
		 '/bar'	=> '/path/to/some.cgi',
	       });

	       Net::Server::HTTP->run(app => [
		 '/' =>	sub { ... },
		 '/foo'	=> sub { ... },
		 '/bar'	=> '/path/to/some.cgi',
	       ]);

TODO
       Add support for writing out HTTP/1.1.

AUTHOR
       Paul T. Seamons paul@seamons.com

THANKS
       See Net::Server

SEE ALSO
       Please see also Net::Server::Fork, Net::Server::INET,
       Net::Server::PreFork, Net::Server::PreForkSimple,
       Net::Server::MultiType, Net::Server::Single Net::Server::SIG
       Net::Server::Daemonize Net::Server::Proto

perl v5.32.0			  2017-08-10		  Net::Server::HTTP(3)

NAME | TEST ONE LINER | SYNOPSIS | DESCRIPTION | METHODS | OPTIONS | TODO | AUTHOR | THANKS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Net::Server::HTTP&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help