]>
Commit | Line | Data |
---|---|---|
b1832b9e NB |
1 | NAME |
2 | HTTP::Daemon - a simple http server class | |
3 | ||
4 | SYNOPSIS | |
5 | use HTTP::Daemon; | |
6 | use HTTP::Status; | |
7 | ||
8 | my $d = HTTP::Daemon->new || die; | |
9 | print "Please contact me at: <URL:", $d->url, ">\n"; | |
10 | while (my $c = $d->accept) { | |
11 | while (my $r = $c->get_request) { | |
12 | if ($r->method eq 'GET' and $r->uri->path eq "/xyzzy") { | |
13 | # remember, this is *not* recommended practice :-) | |
14 | $c->send_file_response("/etc/passwd"); | |
15 | } | |
16 | else { | |
17 | $c->send_error(RC_FORBIDDEN) | |
18 | } | |
19 | } | |
20 | $c->close; | |
21 | undef($c); | |
22 | } | |
23 | ||
24 | DESCRIPTION | |
25 | Instances of the `HTTP::Daemon' class are HTTP/1.1 servers that listen | |
26 | on a socket for incoming requests. The `HTTP::Daemon' is a subclass of | |
27 | `IO::Socket::INET', so you can perform socket operations directly on it | |
28 | too. | |
29 | ||
30 | The accept() method will return when a connection from a client is | |
31 | available. The returned value will be an `HTTP::Daemon::ClientConn' | |
32 | object which is another `IO::Socket::INET' subclass. Calling the | |
33 | get_request() method on this object will read data from the client and | |
34 | return an `HTTP::Request' object. The ClientConn object also provide | |
35 | methods to send back various responses. | |
36 | ||
37 | This HTTP daemon does not fork(2) for you. Your application, i.e. the | |
38 | user of the `HTTP::Daemon' is responsible for forking if that is | |
39 | desirable. Also note that the user is responsible for generating | |
40 | responses that conform to the HTTP/1.1 protocol. | |
41 | ||
42 | The following methods of `HTTP::Daemon' are new (or enhanced) relative | |
43 | to the `IO::Socket::INET' base class: | |
44 | ||
45 | $d = HTTP::Daemon->new | |
46 | $d = HTTP::Daemon->new( %opts ) | |
47 | The constructor method takes the same arguments as the | |
48 | `IO::Socket::INET' constructor, but unlike its base class it can | |
49 | also be called without any arguments. The daemon will then set up a | |
50 | listen queue of 5 connections and allocate some random port number. | |
51 | ||
52 | A server that wants to bind to some specific address on the standard | |
53 | HTTP port will be constructed like this: | |
54 | ||
55 | $d = HTTP::Daemon->new( | |
56 | LocalAddr => 'www.thisplace.com', | |
57 | LocalPort => 80, | |
58 | ); | |
59 | ||
60 | See IO::Socket::INET for a description of other arguments that can | |
61 | be used configure the daemon during construction. | |
62 | ||
63 | $c = $d->accept | |
64 | $c = $d->accept( $pkg ) | |
65 | ($c, $peer_addr) = $d->accept | |
66 | This method works the same the one provided by the base class, but | |
67 | it returns an `HTTP::Daemon::ClientConn' reference by default. If a | |
68 | package name is provided as argument, then the returned object will | |
69 | be blessed into the given class. It is probably a good idea to make | |
70 | that class a subclass of `HTTP::Daemon::ClientConn'. | |
71 | ||
72 | The accept method will return `undef' if timeouts have been enabled | |
73 | and no connection is made within the given time. The timeout() | |
74 | method is described in IO::Socket. | |
75 | ||
76 | In list context both the client object and the peer address will be | |
77 | returned; see the description of the accept method IO::Socket for | |
78 | details. | |
79 | ||
80 | $d->url | |
81 | Returns a URL string that can be used to access the server root. | |
82 | ||
83 | $d->product_tokens | |
84 | Returns the name that this server will use to identify itself. This | |
85 | is the string that is sent with the `Server' response header. The | |
86 | main reason to have this method is that subclasses can override it | |
87 | if they want to use another product name. | |
88 | ||
89 | The default is the string "libwww-perl-daemon/#.##" where "#.##" is | |
90 | replaced with the version number of this module. | |
91 | ||
92 | The `HTTP::Daemon::ClientConn' is a `IO::Socket::INET' subclass. | |
93 | Instances of this class are returned by the accept() method of | |
94 | `HTTP::Daemon'. The following methods are provided: | |
95 | ||
96 | $c->get_request | |
97 | $c->get_request( $headers_only ) | |
98 | This method reads data from the client and turns it into an | |
99 | `HTTP::Request' object which is returned. It returns `undef' if | |
100 | reading fails. If it fails, then the `HTTP::Daemon::ClientConn' | |
101 | object ($c) should be discarded, and you should not try call this | |
102 | method again on it. The $c->reason method might give you some | |
103 | information about why $c->get_request failed. | |
104 | ||
105 | The get_request() method will normally not return until the whole | |
106 | request has been received from the client. This might not be what | |
107 | you want if the request is an upload of a large file (and with | |
108 | chunked transfer encoding HTTP can even support infinite request | |
109 | messages - uploading live audio for instance). If you pass a TRUE | |
110 | value as the $headers_only argument, then get_request() will return | |
111 | immediately after parsing the request headers and you are | |
112 | responsible for reading the rest of the request content. If you are | |
113 | going to call $c->get_request again on the same connection you | |
114 | better read the correct number of bytes. | |
115 | ||
116 | $c->read_buffer | |
117 | $c->read_buffer( $new_value ) | |
118 | Bytes read by $c->get_request, but not used are placed in the *read | |
119 | buffer*. The next time $c->get_request is called it will consume the | |
120 | bytes in this buffer before reading more data from the network | |
121 | connection itself. The read buffer is invalid after $c->get_request | |
122 | has failed. | |
123 | ||
124 | If you handle the reading of the request content yourself you need | |
125 | to empty this buffer before you read more and you need to place | |
126 | unconsumed bytes here. You also need this buffer if you implement | |
127 | services like *101 Switching Protocols*. | |
128 | ||
129 | This method always returns the old buffer content and can optionally | |
130 | replace the buffer content if you pass it an argument. | |
131 | ||
132 | $c->reason | |
133 | When $c->get_request returns `undef' you can obtain a short string | |
134 | describing why it happened by calling $c->reason. | |
135 | ||
136 | $c->proto_ge( $proto ) | |
137 | Return TRUE if the client announced a protocol with version number | |
138 | greater or equal to the given argument. The $proto argument can be a | |
139 | string like "HTTP/1.1" or just "1.1". | |
140 | ||
141 | $c->antique_client | |
142 | Return TRUE if the client speaks the HTTP/0.9 protocol. No status | |
143 | code and no headers should be returned to such a client. This should | |
144 | be the same as !$c->proto_ge("HTTP/1.0"). | |
145 | ||
146 | $c->head_request | |
147 | Return TRUE if the last request was a `HEAD' request. No content | |
148 | body must be generated for these requests. | |
149 | ||
150 | $c->force_last_request | |
151 | Make sure that $c->get_request will not try to read more requests | |
152 | off this connection. If you generate a response that is not self | |
153 | delimiting, then you should signal this fact by calling this method. | |
154 | ||
155 | This attribute is turned on automatically if the client announces | |
156 | protocol HTTP/1.0 or worse and does not include a "Connection: | |
157 | Keep-Alive" header. It is also turned on automatically when HTTP/1.1 | |
158 | or better clients send the "Connection: close" request header. | |
159 | ||
160 | $c->send_status_line | |
161 | $c->send_status_line( $code ) | |
162 | $c->send_status_line( $code, $mess ) | |
163 | $c->send_status_line( $code, $mess, $proto ) | |
164 | Send the status line back to the client. If $code is omitted 200 is | |
165 | assumed. If $mess is omitted, then a message corresponding to $code | |
166 | is inserted. If $proto is missing the content of the | |
167 | $HTTP::Daemon::PROTO variable is used. | |
168 | ||
169 | $c->send_crlf | |
170 | Send the CRLF sequence to the client. | |
171 | ||
172 | $c->send_basic_header | |
173 | $c->send_basic_header( $code ) | |
174 | $c->send_basic_header( $code, $mess ) | |
175 | $c->send_basic_header( $code, $mess, $proto ) | |
176 | Send the status line and the "Date:" and "Server:" headers back to | |
177 | the client. This header is assumed to be continued and does not end | |
178 | with an empty CRLF line. | |
179 | ||
180 | See the description of send_status_line() for the description of the | |
181 | accepted arguments. | |
182 | ||
183 | $c->send_header( $field, $value ) | |
184 | $c->send_header( $field1, $value1, $field2, $value2, ... ) | |
185 | Send one or more header lines. | |
186 | ||
187 | $c->send_response( $res ) | |
188 | Write a `HTTP::Response' object to the client as a response. We try | |
189 | hard to make sure that the response is self delimiting so that the | |
190 | connection can stay persistent for further request/response | |
191 | exchanges. | |
192 | ||
193 | The content attribute of the `HTTP::Response' object can be a normal | |
194 | string or a subroutine reference. If it is a subroutine, then | |
195 | whatever this callback routine returns is written back to the client | |
196 | as the response content. The routine will be called until it return | |
197 | an undefined or empty value. If the client is HTTP/1.1 aware then we | |
198 | will use chunked transfer encoding for the response. | |
199 | ||
200 | $c->send_redirect( $loc ) | |
201 | $c->send_redirect( $loc, $code ) | |
202 | $c->send_redirect( $loc, $code, $entity_body ) | |
203 | Send a redirect response back to the client. The location ($loc) can | |
204 | be an absolute or relative URL. The $code must be one the redirect | |
205 | status codes, and defaults to "301 Moved Permanently" | |
206 | ||
207 | $c->send_error | |
208 | $c->send_error( $code ) | |
209 | $c->send_error( $code, $error_message ) | |
210 | Send an error response back to the client. If the $code is missing a | |
211 | "Bad Request" error is reported. The $error_message is a string that | |
212 | is incorporated in the body of the HTML entity body. | |
213 | ||
214 | $c->send_file_response( $filename ) | |
215 | Send back a response with the specified $filename as content. If the | |
216 | file is a directory we try to generate an HTML index of it. | |
217 | ||
218 | $c->send_file( $filename ) | |
219 | $c->send_file( $fd ) | |
220 | Copy the file to the client. The file can be a string (which will be | |
221 | interpreted as a filename) or a reference to an `IO::Handle' or | |
222 | glob. | |
223 | ||
224 | $c->daemon | |
225 | Return a reference to the corresponding `HTTP::Daemon' object. | |
226 | ||
227 | SEE ALSO | |
228 | RFC 2616 | |
229 | ||
230 | IO::Socket::INET, IO::Socket | |
231 | ||
232 | COPYRIGHT | |
233 | Copyright 1996-2003, Gisle Aas | |
234 | ||
235 | This library is free software; you can redistribute it and/or modify it | |
236 | under the same terms as Perl itself. | |
237 |