NAME

Net::HTTPServer

SYNOPSIS

Net::HTTPServer provides a lite HTTP server. It can serve files, or can be configured to call Perl functions when a URL is accessed.

DESCRIPTION

Net::HTTPServer basically turns a CGI script into a stand alone server. Useful for temporary services, mobile/local servers, or embedding an HTTP server into another program.

EXAMPLES

use Net::HTTPServer;

my $server = new Net::HTTPServer(port=>5000, docroot=>"/var/www/site");

$server->Start();

$server->Process(); # Run forever

   or

while(1) { $server->Process(5); # Run for 5 seconds # Do something else... }

$server->Stop();

METHODS

new(%cfg)

Given a config hash, return a server object that you can start, process, and stop. The config hash takes the options:

    chroot => 0|1       - Run the server behind a virtual chroot().
                          Since only root can actually call chroot,
                          a URL munger is provided that will not
                          allow URLs to go beyond the document root
                          if this is specified.
                          ( Default: 1 )

    docroot => string   - Path on the filesystem that you want to be
                          the document root "/" for the server.
                          ( Default: "." )

    index => list       - Specify a list of file names to use as the
                          the index file when a directory is requested.
                          ( Default: ["index.html","index.htm"] )

    log => string       - Path to store the log at.  If you set this to
                          "STDOUT" then it will display to STDOUT.
                          ( Default: access.log )

    mimetypes => string - Path to an alternate mime.types file.
                          ( Default: included in release )

    numproc => int      - When type is set to "forking", this tells the
                          server how many child processes to keep
                          running at all times.
                          ( Default: 5 )
                                 
    port => int         - Port number to use.  You can optionally
                          specify the string "scan", and the server
                          will loop through ports until it finds one
                          it can listen on.  This port is then returned
                          by the Start() method.
                          ( Default: 9000 )

    ssl => 0|1          - Run a secure server using SSL.  You must
                          specify ssl_key, ssl_cert, and ssl_ca if
                          set this to 1.
                          ( Default: 0 )

    ssl_ca => string    - Path to the SSL ca file.
                          ( Default: undef )

    ssl_cert => string  - Path to the SSL cert file.
                          ( Default: undef )

    ssl_key => string   - Path to the SSL key file.
                          ( Default: undef )

    type => string      - What kind of server to create?  Available
                          types are:
                            single  - single process/no forking
                            forking - preforking server
                          (Default: "single")

Start()

Starts the server based on the config options passed to new(). Returns the port number the server is listening on, or undef if the server was unable to start.

Stop()

Shuts down the socket connection and cleans up after itself.

Process(timeout)

Listens for incoming requests and responds back to them. This function will block, unless a timeout is specified, then it will block for that number of seconds before returning. Useful for embedding this into other programs and still letting the other program get some CPU time.

RegisterURL(url,function)

Register the function with the provided URL. When that URL is requested, the function is called and passed in the environment (GET+POST) so that it can do something meaningful with them. A simple handler looks like:

  $server->RegisterURL("/foo/bar.pl",\&test);

  sub test
  {
      my $env = shift;  # hash reference

      my $res;
      $res  = "<html>\n";
      $res .= "  <head>\n";
      $res .= "    <title>This is a test</title>\n";
      $res .= "  </head>\n";
      $res .= "  <body>\n";
      $res .= "    <pre>\n";

      foreach my $var (keys(%{$env}))
      {
          $res .= "$var -> ".$env->{$var}."\n";
      }
      
      $res .= "    </pre>\n";
      $res .= "  </body>\n";
      $res .= "</html>\n";

      return ["200",   # HTTP Response code (200 = Ok)
              {},      # Headers to send back
              $res     # Whatever you are sending back
             ];
  }
  

Start a server with that and point your browser to:

  http://localhost:9000/foo/bar.pl?test=bing&test2=bong

You should see a page titled "This is a test" with this body:

  test -> bing
  test2 -> bong

AUTHOR

Ryan Eatmon

COPYRIGHT

This module is free software, you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Net::HTTPServer

perl -MCPAN -e shell
install Net::HTTPServer