NAME

HTTP::Engine - Web Server Gateway Interface and HTTP Server Engine Drivers

SYNOPSIS

  use HTTP::Engine;
  my $engine = HTTP::Engine->new(
      interface => {
          module => 'ServerSimple',
          args   => {
              host => 'localhost',
              port =>  1978,
          },
          request_handler => \&handle_request,
      },
  );
  $engine->run;

  sub handle_request {
      my $req = shift;
      HTTP::Engine::Response->new( body => "Hello world" );
  }

DESCRIPTION

HTTP::Engine abstracts handling the input and output of various web server environments, including CGI, mod_perl and FastCGI. Most of the code is ported over from Catalyst::Engine.

If you're familiar with WSGI for Python or Rack for Ruby, HTTP::Engine exactly does the same thing, for Perl.

WHY WOULD YOU USE HTTP::ENGINE

CGI.pm is popular under the CGI environment and Apache::Request is great for better performance under mod_perl environment. The problem is, these HTTP request and response handling abstractions have incompatible interfaces, and it's not easy to switch between them.

HTTP::Engine prepareas a HTTP::Engine::Request object for you which is optimized for your current environment, and pass that to your request handler. Your request handler then returns a HTTP::Engine::Response object, which we communicate back to the server for you.

HTTP::Engine::Request covers the bases of common request process tasks, like handling GET and POST parameters, parsing HTTP cookies and processing file uploads. Unlike CGI.pm, but like most other web programming languages, it allows you to mix GET and POST parameters.

And importantly, it allows you to seamlessly move your code from CGI to a persistent environment (like mod_perl or FastCGI) without rewriting your code. At the same time, you'll maintain the possibility of additional performance benefits, as HTTP::Engine can transparently take advantage of native mod_perl functions when they are available.

MIDDLEWARE

Middleware is a framwork to extend HTTP::Engine, much like Catalyst::Plugin for Catalyst. Please see HTTP::Engine::Middleware.

INTERFACES

Interfaces are the actual environment-dependent components which handles the actual interaction between your clients and the application.

For example, in CGI mode, you can write to STDOUT and expect your clients to see it, but in mod_perl, you may need to use $r->print instead.

Interfaces are the actual layers that does the interaction. HTTP::Engine currently supports the following:

# XXX TODO: Update the list

HTTP::Engine::Interface::ServerSimple
HTTP::Engine::Interface::FastCGI
HTTP::Engine::Interface::CGI
HTTP::Engine::Interface::Test: for test code interface
HTTP::Engine::Interface::ModPerl: experimental
HTTP::Engine::Interface::Standalone: old style

Interfaces can be specified as part of the HTTP::Engine constructor:

  my $interface = HTTP::Engine::Interface::FastCGI->new(
    request_handler => ...
  );
  HTTP::Engine->new(
    interface => $interface
  )->run();

Or you can let HTTP::Engine instantiate the interface for you:

  HTTP::Engine->new(
    interface => {
      module => 'FastCGI',
      args   => {
      }
      request_handler => ...
    }
  )->run();

COMMUNITY

The community can be found via:

  IRC: irc.perl.org#http-engine

  Mailing list: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/http-engine

  GitHub: http://github.com/http-engine/HTTP-Engine

  Twitter: http://twitter.com/httpengine

ADDITIONAL DOCUMENTATIONS

<http://en.wikibooks.org/wiki/Perl_Programming/HTTP::Engine> writing by gugod++.

AUTHOR

Kazuhiro Osawa <yappo <at> shibuya <döt> pl>

Daisuke Maki

tokuhirom

nyarla

marcus

hidek

dann

typester (Interface::FCGI)

lopnor

nothingmuch

kan

Mark Stosberg (documentation)

walf443

kawa0117

mattn

otsune

gugod

stevan

hirose31

fujiwara

miyagawa

Shawn M Moore

REPOSITORY

We moved to GitHub.

  git clone git://github.com/http-engine/HTTP-Engine.git

HTTP::Engine's Git repository is hosted at <http://github.com/http-engine/HTTP-Engine>. patches and collaborators are welcome.

LICENSE

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