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

FreeBSD Manual Pages

  
 
  

home | help
POE::Component::ServerUserTContributed Perl DocPOE::Component::Server::HTTP(3)

NAME
       POE::Component::Server::HTTP - Foundation of a POE HTTP Daemon

SYNOPSIS
	use POE::Component::Server::HTTP;
	use HTTP::Status;
	my $aliases = POE::Component::Server::HTTP->new(
	    Port => 8000,
	    ContentHandler => {
		  '/' => \&handler1,
		  '/dir/' => sub { ... },
		  '/file' => sub { ... }
	    },
	    Headers => { Server	=> 'My Server' },
	 );

	 sub handler {
	     my	($request, $response) =	@_;
	     $response->code(RC_OK);
	     $response->content("Hi, you fetched ". $request->uri);
	     return RC_OK;
	 }

	 POE::Kernel->call($aliases->{httpd}, "shutdown");
	 # next	line isn't really needed
	 POE::Kernel->call($aliases->{tcp}, "shutdown");

DESCRIPTION
       POE::Component::Server::HTTP (PoCo::HTTPD) is a framework for building
       custom HTTP servers based on POE. It is loosely modeled on the ideas of
       apache and the mod_perl/Apache module.

       It is built alot	on work	done by	Gisle Aas on HTTP::* modules and the
       URI module which	are subclassed.

       PoCo::HTTPD lets	you register different handler,	stacked	by directory
       that will be run	during the cause of the	request.

   Handlers
       Handlers	are put	on a stack in fifo order. The path
       /foo/bar/baz/honk.txt will first	push the handlers of / then of /foo/
       then of /foo/bar/, then of /foo/bar/baz/, and lastly
       /foo/bar/baz/honk.txt.  Pay attention to	directories!  A	request	for
       /honk will not match /honk/ as you are used to with apache.  If you
       want /honk to act like a	directory, you should have a handler for /honk
       which redirects to /honk/.

       However,	there can be only one ContentHandler and if any	handler
       installs	a ContentHandler that will override the	old ContentHandler.

       If no handler installs a	ContentHandler it will find the	closest	one
       directory wise and use it.

       There is	also a special StreamHandler which is a	coderef	that gets
       invoked if you have turned on streaming by doing
       $response->streaming(1);

       Handlers	take the $request and $response	objects	as arguments.

       RC_OK
	   Everything is ok, please continue processing.

       RC_DENY
	   If it is a TransHandler, stop translation handling and carry	on
	   with	a PreHandler, if it is a PostHandler do	nothing, else return
	   denied to the client.

       RC_WAIT
	   This	is a special handler that suspends the execution of the
	   handlers.  They will	be suspended until $response->continue() is
	   called, this	is usefull if you want to do a long request and	not
	   blocck.

       The following handlers are available.

       TransHandler
	   TransHandlers are run before	the URI	has been resolved, giving them
	   a chance to change the URI. They can	therefore not be registred per
	   directory.

	       new(TransHandler	=> [ sub {return RC_OK}	]);

	   A TransHandler can stop the dispatching of TransHandlers and	jump
	   to the next handler type by specifing RC_DENY;

       PreHandler
	   PreHandlers are stacked by directory	and run	after TransHandler but
	   before the ContentHandler. They can change ContentHandler (but
	   beware, other PreHandlers might also	change it) and push on
	   PostHandlers.

	       new(PreHandler => { '/' => [sub {}], '/foo/' => [\&foo]});

       ContentHandler
	   The handler that is supposed	to give	the content. When this handler
	   returns it will send	the response object to the client. It will
	   automaticly add Content-Length and Date if these are	not set. If
	   the response	is streaming it	will make sure the correct headers are
	   set.	It will	also expand any	cookies	which have been	pushed onto
	   the response	object.

	       new(ContentHandler => { '/' => sub {}, '/foo/' => \&foo});

       ErrorHandler
	   This	handler	is called when there is	a read or write	error on the
	   socket.  This is most likely	caused by the remote side closing the
	   connection.	$resquest->is_error and	$response->is_error will
	   return true.	 Note that "PostHanlder" will still called, but
	   "TransHandler" and "PreHandler" won't be.  It is a map to coderefs
	   just	like ContentHandler is.

       PostHandler
	   These handlers are run after	the socket has been flushed.

	       new(PostHandler => { '/'	=> [sub	{}], '/foo/' =>	[\&foo]});

       StreamHandler
	   If you turn on streaming in any other handler, the request is
	   placed in streaming mode.  This handler is called, with the usual
	   parameters, when streaming mode is first entered, and subsequently
	   when	each block of data is flushed to the client.

	   Streaming mode is turned on via the $response object:

	       $response->streaming(1);

	   You deactivate streaming mode with the same object:

	       $response->close;

	   Content is also sent	to the client via the $response	object:

	       $response->send($somedata);

	   The output filter is	set to POE::Filter::Stream, which passes the
	   data	through	unchanged.  If you are doing a multipart/mixed
	   response, you will have to set up your own headers.

	   Example:

	       sub new {
		   .....
		   POE::Component::Filter::HTTP->new(
			    ContentHandler => {	'/someurl' => sub { $self->someurl(@_) },
			    StreamHandler  => sub { $self->stream(@_),
		       );
	       }

	       sub someurl {
		   my($self, $resquest,	$response)=@_;
		   $self->{todo} = [ .... ];
		   $response->streaming(1);
		   $response->code(RC_OK);	   # you must set up your response header
		   $response->content_type(...);

		   return RC_OK;
	       }

	       sub stream {
		   my($self, $resquest,	$response)=@_;

		   if( @{$self->{todo}}	) {
		       $response->send(shift @{$self->{todo}});
		   }
		   else	{
		       $response->close;
		   }
	       }

	   Another example can be found	in t/30_stream.t.  The parts dealing
	   with	multipart/mixed	are well documented and	at the end of the
	   file.

	   NOTE: Changes in streaming mode are only verified when
	   StreamHandler exits.	 So you	must either turn streaming off in your
	   StreamHandler, or make sure that the	StreamHandler will be called
	   again.  This	last is	done by	sending	data to	the client.  If	for
	   some	reason you have	no data	to send, you can get the same result
	   with	"continue". Remember that this will also cause the
	   StreamHandler to be called one more time.

	       my $aliases=POE::Component::Filter::HTTP->new( ....);

	       # and then, when	the end	of the stream in met
	       $response->close;
	       $response->continue;

	   NOTE: even when the stream ends, the	client connection will be held
	   open	if Keepalive is	active.	 To force the connection closed, set
	   the Connection header to close:

	       $resquest->header(Connection => 'close');

	   This	might be a bug.	 Are there any cases where we'd	want to	keep
	   the connection open after a stream?

Events
       The "shutdown" event may	be sent	to the component indicating that it
       should shut down.  The event may	be sent	using the return value of the
       new() method (which is a	session	id) by either post()ing	or call()ing.

       I've experienced	some problems with the session not receiving the event
       when it gets post()ed so	call() is advised.

See Also
       Please also take	a look at HTTP::Response, HTTP::Request, URI, POE and
       POE::Filter::HTTPD

TODO
       Document	Connection Response and	Request	objects.
       Write more tests
       Add a PoCo::Server::HTTP::Session that matches a	http session against
       poe session using cookies or other state	system
       Add more	options	to streaming
       Figure out why post()ed "shutdown" events don't get received.
       Probably	lots of	other API changes

AUTHOR
       Arthur Bergman, arthur@contiller.se

       Additional hacking by Philip Gwyn, poe-at-pied.nu

       Released	under the same terms as	POE.

perl v5.32.0			  2006-05-23   POE::Component::Server::HTTP(3)

NAME | SYNOPSIS | DESCRIPTION | Events | See Also | TODO | AUTHOR

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

home | help