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

FreeBSD Manual Pages

  
 
  

home | help
POE::Component::ServerUserTContributed PePOE::Component::Server::HTTPServer(3)

NAME
       POE::Component::Server::HTTPServer - serve HTTP requests

SYNOPSIS
	   use POE;
	   use POE::Component::Server::HTTPServer;

	   my $server =	POE::Component::Server::HTTPServer->new();
	   $server->port( 8080 );
	   $server->handlers( [
			       '/' => new_handler('StaticHandler', './htdocs'),
			       '/foo' => \&foo_handler,
			       '/bar' => MyBarHandler->new(),
			      ]	);
	   my $svc = $server->create_server();
	   $poe_kernel->run();
	   exit	0;

   DESCRIPTION
       POE::Component::Server::HTTPServer is a POE-based HTTP server.
       Requests	are dispatched based on	an ordered list	of "prefix => handler"
       pairs.

       For each	pair in	the handlers list in sequence, the given handler is
       invoked if the prefix matches the request path.	Each handler can
       return either a value indicating	to continue processing the request, or
       one telling HTTPServer that request processing is done.	Handlers may
       also modify the request and tell	the HTTPServer to restart the dispatch
       process.

       HTTPServer creates a context object for each request (just a hash
       reference) which	it passes to each handler when invoked.	 Among other
       standard	attributes, this context object	contains the "HTTP::Request"
       and "HTTP::Response" objects for	the request being processed, as	well
       as the requested	path with and without the matched prefix.  Handlers
       may retrieve and	set attributes in this context in order	to get
       information and to modify the state of other handlers.

   Creational Methods
       new( %args )
	   Creates a new HTTPServer object. The	following arguments provide
	   shortcuts for the setter methods of the same	name:

	     port (default: 8080)
	     handlers (default:	none)
	     log_file (default:	httpserver.log)
	     backstop_handler (default:	the NotFoundHandler instance)

	   For example:

	       $s = POE::Component::Server::HTTPServer->new(
		       port => 8088,
		       handlers	=> [ '/' => new_handler("StaticHandler", "./html") ],
		       log_file	=> "/var/log/myhttp.log",
		       backstop_handler	=> \&my_backstop,
		   );

	   "new()" does	not install a POE component in the kernel.  Use
	   "create_server()" to	do this, once the server is appropriately
	   configured.

       log_file( $filename ), log_file(	)
	   Returns and (optionally) sets the filename for the request log
	   file.  This log lists all requests handled by the server in a
	   format similar to common httpd log format.  By default, this	file
	   name	will be	"httpserver.log".

       port( $port ), port( )
	   Returns and (optionally) sets the port for the server to listen on.
	   If not explicitly set, the server will listen on port 8080.

       handlers( $handlers_listref ), handlers(	)
	   Returns and (optionally) sets the list of request handlers.	This
	   accepts and returns an array	reference.  The	list referenced	by the
	   return value	may be modifed,	should you prefer to manipulate	the
	   handler list	that way.  By default, this list is empty.

	   See "Request	Handlers".

       backstop_handler( $handler ), backstop_handler( )
	   Returns and (optionally) sets the backstop handler, the handler
	   invoked if none of the configured handlers finalize the request.
	   If not specified, the server	will use the instance of
	   POE::Component::Server::HTTPServer::NotFoundHandler.

   Other Methods
       create_server( )
	   Sets	up and installs	the POE	server component in the	POE kernel.
	   The newly created component object is returned.

       dispatch( $context, $full_request_path )
	   Dispatch the	current	request, as set	up in the $context.  This is
	   intended for	redispatching requests to specific server-relative
	   locations.  If $full_request_path is	not provided, the context
	   attribute "fullpath"	will be	used, as set (originally) by the
	   HTTPServer on recieving a new request.

	   HTTPServer saves a reference	to itself in the context under the key
	   "dispatcher", allowing you to call this method inside handlers like
	   this:

	       $context->{dispatcher}->dispatch( $context, $newpath );

   Internal Methods
       The following methods should be considered private, but may be of
       interest	when subclassing HTTPServer.

       _init( @args )
	   Called by "new()" to	initialize newly created objects.

       _get_dispatcher(	)
	   Badly named:	returns	the coderef for	POE::Component::Server::TCP's
	   "ClientInput" property.  This is the	coderef	that does the request
	   dispatching work.

       _request_log( )
	   Logs	a request.

   Exported Functions
       The following subroutines are exported by default:

       new_handler( $short_handler_name, @args )
	   This	is a shortcut for

	       "POE::Component::Server::HTTPServer::$short_handler_name"->new( @args );

	   which is significantly less typing for handlers in the default
	   package.  This is intended for use when setting the list of
	   handlers.

   Request Handlers
       Request handlers	are used to service incoming requests.	Each handler
       in turn is associated with a relative request URI prefix, and may
       choose to either	finalize the request processing	or let it continue.

       The prefixes are	regular	expressions, to	be matched against the
       beginning of the	request	URI (eg, assume	a prepended "^").  Each
       handler in sequence is invoked if the request matches this prefix.

       The handlers themselves may be either an	object implementing the
       interface in "POE::Component::Server::HTTPServer", or a subroutine
       reference.  In the first	case, HTTPServer will can the object's
       "handle()" method, and in the second, HTTPServer	will execute the
       subroutine reference.  In both cases, HTTPServer	will pass the context
       object to the method or sub as an argument.

       HTTPServer always sets certain attributes in the	context	before
       invoking	the request:

       $context->{request}
	   The HTTP::Request object holding the	request	message	data.

       $context->{response}
	   The HTTP::Response object to	use to build the response message.

       $context->{fullpath}
	   The full relative path of the request URI.  This is initially equal
	   to "$context->{request}->uri()->path()", but	may be modified	by
	   request handlers.

       $context->{contextpath}
	   The part of the request path	after the prefix which matched for the
	   request handler being invoked.

       $context->{dispatcher}
	   The dispatcher (HTTPServer) processing this request.	 Request
	   handlers may	use this object's "dispatch()" method to redispatch
	   the request.

       Each request handler is passed the context as an	argument.  Handlers
       should return either H_CONT, indicating that request processing should
       continue, or H_FINAL, indicating	that the response has been finalized
       and HTTPServer should stop and return the response message.

       There are four standard basic request handlers.	The package names for
       each begin with POE::Component::Server::HTTPServer, but you can use
       "HTTPServer::new_handler()" to avoid typing all that.  See the
       documentation for each handler for more detailed	information.

       NotFoundHandler
	   Creates and finalizes a 404 Not Found response.  If the context
	   attribute "error_message" is	set, it	will be	included in the
	   response body.

	   An instance of NotFoundHandler is used by HTTPServer	as the
	   backstop handler, so	that requests not finalized by any other
	   handler result in a usable response.

       StaticHandler
	   Serves filesystem resources.	 May also be subclassed	to server
	   interpreted resources based on the underlying filesystem.

       ParameterParseHandler
	   Extracts CGI	parameters from	GET and	POST requests, and adds	them
	   to the context's "param" attribute.

       BasicAuthenHandler
	   Performs HTTP basic authentication: interprets request headers and
	   sets	the context's "basic_username" and "basic_password"
	   attributes.	Issues a basic authen challenge	response if the
	   request has no auth headers.

OTHER
       This module was inspired	by POE::Component::Server::HTTP, which deals
       with request processing in a slightly different manner.

SEE ALSO
       POE::Component::Server::HTTPServer::Handler, POE,
       POE::Component::Server::HTTPServer::Examples

AUTHOR
       Greg Fast <gdf@speakeasy.net>

COPYRIGHT
       Copyright 2003 Greg Fast.

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

perl v5.32.0			  2005-05POE::Component::Server::HTTPServer(3)

NAME | SYNOPSIS | OTHER | SEE ALSO | AUTHOR | COPYRIGHT

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

home | help