1POE::Component::Server:U:sHeTrTPC(o3n)tributed Perl DocuPmOeEn:t:aCtoimopnonent::Server::HTTP(3)
2
3
4

NAME

6       POE::Component::Server::HTTP - Foundation of a POE HTTP Daemon
7

SYNOPSIS

9        use POE::Component::Server::HTTP;
10        use HTTP::Status;
11        my $aliases = POE::Component::Server::HTTP->new(
12            Port => 8000,
13            ContentHandler => {
14                  '/' => \&handler1,
15                  '/dir/' => sub { ... },
16                  '/file' => sub { ... }
17            },
18            Headers => { Server => 'My Server' },
19         );
20
21         sub handler {
22             my ($request, $response) = @_;
23             $response->code(RC_OK);
24             $response->content("Hi, you fetched ". $request->uri);
25             return RC_OK;
26         }
27
28         POE::Kernel->call($aliases->{httpd}, "shutdown");
29         # next line isn't really needed
30         POE::Kernel->call($aliases->{tcp}, "shutdown");
31

DESCRIPTION

33       POE::Component::Server::HTTP (PoCo::HTTPD) is a framework for building
34       custom HTTP servers based on POE. It is loosely modeled on the ideas of
35       apache and the mod_perl/Apache module.
36
37       It is built alot on work done by Gisle Aas on HTTP::* modules and the
38       URI module which are subclassed.
39
40       PoCo::HTTPD lets you register different handler, stacked by directory
41       that will be run during the cause of the request.
42
43   Handlers
44       Handlers are put on a stack in fifo order. The path
45       /foo/bar/baz/honk.txt will first push the handlers of / then of /foo/
46       then of /foo/bar/, then of /foo/bar/baz/, and lastly
47       /foo/bar/baz/honk.txt.  Pay attention to directories!  A request for
48       /honk will not match /honk/ as you are used to with apache.  If you
49       want /honk to act like a directory, you should have a handler for /honk
50       which redirects to /honk/.
51
52       However, there can be only one ContentHandler and if any handler
53       installs a ContentHandler that will override the old ContentHandler.
54
55       If no handler installs a ContentHandler it will find the closest one
56       directory wise and use it.
57
58       There is also a special StreamHandler which is a coderef that gets
59       invoked if you have turned on streaming by doing
60       $response->streaming(1);
61
62       Handlers take the $request and $response objects as arguments.
63
64       RC_OK
65           Everything is ok, please continue processing.
66
67       RC_DENY
68           If it is a TransHandler, stop translation handling and carry on
69           with a PreHandler, if it is a PostHandler do nothing, else return
70           denied to the client.
71
72       RC_WAIT
73           This is a special handler that suspends the execution of the
74           handlers.  They will be suspended until $response->continue() is
75           called, this is usefull if you want to do a long request and not
76           blocck.
77
78       The following handlers are available.
79
80       TransHandler
81           TransHandlers are run before the URI has been resolved, giving them
82           a chance to change the URI. They can therefore not be registred per
83           directory.
84
85               new(TransHandler => [ sub {return RC_OK} ]);
86
87           A TransHandler can stop the dispatching of TransHandlers and jump
88           to the next handler type by specifing RC_DENY;
89
90       PreHandler
91           PreHandlers are stacked by directory and run after TransHandler but
92           before the ContentHandler. They can change ContentHandler (but
93           beware, other PreHandlers might also change it) and push on
94           PostHandlers.
95
96               new(PreHandler => { '/' => [sub {}], '/foo/' => [\&foo]});
97
98       ContentHandler
99           The handler that is supposed to give the content. When this handler
100           returns it will send the response object to the client. It will
101           automaticly add Content-Length and Date if these are not set. If
102           the response is streaming it will make sure the correct headers are
103           set. It will also expand any cookies which have been pushed onto
104           the response object.
105
106               new(ContentHandler => { '/' => sub {}, '/foo/' => \&foo});
107
108       ErrorHandler
109           This handler is called when there is a read or write error on the
110           socket.  This is most likely caused by the remote side closing the
111           connection.  $resquest->is_error and $response->is_error will
112           return true.  Note that "PostHanlder" will still called, but
113           "TransHandler" and "PreHandler" won't be.  It is a map to coderefs
114           just like ContentHandler is.
115
116       PostHandler
117           These handlers are run after the socket has been flushed.
118
119               new(PostHandler => { '/' => [sub {}], '/foo/' => [\&foo]});
120
121       StreamHandler
122           If you turn on streaming in any other handler, the request is
123           placed in streaming mode.  This handler is called, with the usual
124           parameters, when streaming mode is first entered, and subsequently
125           when each block of data is flushed to the client.
126
127           Streaming mode is turned on via the $response object:
128
129               $response->streaming(1);
130
131           You deactivate streaming mode with the same object:
132
133               $response->close;
134
135           Content is also sent to the client via the $response object:
136
137               $response->send($somedata);
138
139           The output filter is set to POE::Filter::Stream, which passes the
140           data through unchanged.  If you are doing a multipart/mixed
141           response, you will have to set up your own headers.
142
143           Example:
144
145               sub new {
146                   .....
147                   POE::Component::Filter::HTTP->new(
148                            ContentHandler => { '/someurl' => sub { $self->someurl(@_) },
149                            StreamHandler  => sub { $self->stream(@_),
150                       );
151               }
152
153               sub someurl {
154                   my($self, $resquest, $response)=@_;
155                   $self->{todo} = [ .... ];
156                   $response->streaming(1);
157                   $response->code(RC_OK);         # you must set up your response header
158                   $response->content_type(...);
159
160                   return RC_OK;
161               }
162
163               sub stream {
164                   my($self, $resquest, $response)=@_;
165
166                   if( @{$self->{todo}} ) {
167                       $response->send(shift @{$self->{todo}});
168                   }
169                   else {
170                       $response->close;
171                   }
172               }
173
174           Another example can be found in t/30_stream.t.  The parts dealing
175           with multipart/mixed are well documented and at the end of the
176           file.
177
178           NOTE: Changes in streaming mode are only verified when
179           StreamHandler exits.  So you must either turn streaming off in your
180           StreamHandler, or make sure that the StreamHandler will be called
181           again.  This last is done by sending data to the client.  If for
182           some reason you have no data to send, you can get the same result
183           with "continue". Remember that this will also cause the
184           StreamHandler to be called one more time.
185
186               my $aliases=POE::Component::Filter::HTTP->new( ....);
187
188               # and then, when the end of the stream in met
189               $response->close;
190               $response->continue;
191
192           NOTE: even when the stream ends, the client connection will be held
193           open if Keepalive is active.  To force the connection closed, set
194           the Connection header to close:
195
196               $resquest->header(Connection => 'close');
197
198           This might be a bug.  Are there any cases where we'd want to keep
199           the connection open after a stream?
200

Events

202       The "shutdown" event may be sent to the component indicating that it
203       should shut down.  The event may be sent using the return value of the
204       new() method (which is a session id) by either post()ing or call()ing.
205
206       I've experienced some problems with the session not receiving the event
207       when it gets post()ed so call() is advised.
208

See Also

210       Please also take a look at HTTP::Response, HTTP::Request, URI, POE and
211       POE::Filter::HTTPD
212

TODO

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

AUTHOR

223       Arthur Bergman, arthur@contiller.se
224
225       Additional hacking by Philip Gwyn, poe-at-pied.nu
226
227       Released under the same terms as POE.
228
229
230
231perl v5.28.1                      2006-05-23   POE::Component::Server::HTTP(3)
Impressum