Annotation of embedaddon/libpdel/http/http_server.3, revision 1.1.1.1
1.1 misho 1: .\" Copyright (c) 2001-2002 Packet Design, LLC.
2: .\" All rights reserved.
3: .\"
4: .\" Subject to the following obligations and disclaimer of warranty,
5: .\" use and redistribution of this software, in source or object code
6: .\" forms, with or without modifications are expressly permitted by
7: .\" Packet Design; provided, however, that:
8: .\"
9: .\" (i) Any and all reproductions of the source or object code
10: .\" must include the copyright notice above and the following
11: .\" disclaimer of warranties; and
12: .\" (ii) No rights are granted, in any manner or form, to use
13: .\" Packet Design trademarks, including the mark "PACKET DESIGN"
14: .\" on advertising, endorsements, or otherwise except as such
15: .\" appears in the above copyright notice or in the software.
16: .\"
17: .\" THIS SOFTWARE IS BEING PROVIDED BY PACKET DESIGN "AS IS", AND
18: .\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, PACKET DESIGN MAKES NO
19: .\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING
20: .\" THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED
21: .\" WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
22: .\" OR NON-INFRINGEMENT. PACKET DESIGN DOES NOT WARRANT, GUARANTEE,
23: .\" OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS
24: .\" OF THE USE OF THIS SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY,
25: .\" RELIABILITY OR OTHERWISE. IN NO EVENT SHALL PACKET DESIGN BE
26: .\" LIABLE FOR ANY DAMAGES RESULTING FROM OR ARISING OUT OF ANY USE
27: .\" OF THIS SOFTWARE, INCLUDING WITHOUT LIMITATION, ANY DIRECT,
28: .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE, OR CONSEQUENTIAL
29: .\" DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES, LOSS OF
30: .\" USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY THEORY OF
31: .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
32: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
33: .\" THE USE OF THIS SOFTWARE, EVEN IF PACKET DESIGN IS ADVISED OF
34: .\" THE POSSIBILITY OF SUCH DAMAGE.
35: .\"
36: .\" Author: Archie Cobbs <archie@freebsd.org>
37: .\"
38: .\" $Id: http_server.3,v 1.16 2004/06/02 17:24:37 archie Exp $
39: .\"
40: .Dd April 22, 2002
41: .Dt HTTP_SERVER 3
42: .Os
43: .Sh NAME
44: .Nm http_server
45: .Nd threaded server for HTTP and HTTPS
46: .Sh LIBRARY
47: PDEL Library (libpdel, \-lpdel)
48: .Sh SYNOPSIS
49: .In sys/types.h
50: .In stdio.h
51: .In netinet/in.h
52: .In openssl/ssl.h
53: .In pdel/http/http_defs.h
54: .In pdel/http/http_server.h
55: .Ft "struct http_server *"
56: .Fn http_server_start "struct pevent_ctx *ctx" "struct in_addr ip" "u_int16_t port" "const struct http_server_ssl *ssl" "const char *server_name" "http_logger_t *logger"
57: .Ft void
58: .Fn http_server_stop "struct http_server **serverp"
59: .Ft int
60: .Fn http_server_register_servlet "struct http_server *serv" "struct http_servlet *servlet" "const char *vhost" "const char *urlpat" "int order"
61: .Ft void
62: .Fn http_server_destroy_servlet "struct http_servlet **servletp"
63: .Ft void
64: .Fn http_server_set_proxy_handler "struct http_server *serv" "http_proxy_t *handler" "void *arg"
65: .Sh DESCRIPTION
66: These functions implement a threaded HTTP server supporting SSL and
67: user-definable "servlets".
68: .Pp
69: .Fn http_server_start
70: starts a new server listening on IP address
71: .Fa ip
72: and port
73: .Fa port .
74: If
75: .Fa ip
76: is 0.0.0.0 then the server listens on all configured IP addresses.
77: If
78: .Fa port
79: is zero then the default port (either 80 or 443 depending on whether
80: SSL is enabled) is used.
81: SSL is enabled by supplying a non-NULL pointer
82: .Fa ssl
83: to this structure:
84: .Pp
85: .Bd -literal -offset 3n
86: struct http_server_ssl {
87: const char *cert_path; /* path to certificate file */
88: const char *pkey_path; /* path to private key file */
89: const char *pkey_password; /* private key password, if needed */
90: };
91: .Ed
92: .Pp
93: .Fa ctx
94: is a
95: .Xr pevent 3
96: event context with which the server registers to accept incoming connections.
97: New connections are allocated individual threads in which to execute.
98: The server enforces a hard limit of at most 1024 simultaneous connections,
99: refusing to accept any new connections until one or more existing connections
100: terminate.
101: .Pp
102: The
103: .Fa server_name
104: string is used for the "Server:" HTTP header and typically includes
105: the name and version number of the software, e.g.,
106: .Dq "MyServer/1.0" .
107: .Pp
108: The
109: .Fa logger ,
110: if not
111: .Dv NULL,
112: specifies a callback for logging:
113: .Pp
114: .Bd -literal -offset 3n
115: typedef void http_logger_t(int sev, const char *fmt, ...);
116: .Ed
117: .Pp
118: Here
119: .Fa sev
120: is a
121: .Xr syslog 3
122: severity level.
123: .Pp
124: .Fn http_server_stop
125: stops a server.
126: All registered servlets are destroyed
127: (see
128: .Fn http_server_destroy_servlet
129: below).
130: Upon return, all connection threads are guaranteed to have exited and
131: .Fa "*serverp"
132: will be set to
133: .Dv NULL.
134: If
135: .Fa "*serverp"
136: is already
137: .Dv NULL
138: when
139: .Fn http_server_stop
140: is invoked, nothing happens.
141: .Pp
142: Invoking
143: .Fn http_server_stop
144: from within a servlet is not supported and will give undefined results.
145: .\"
146: .Ss Servlets
147: .\"
148: For anything interesting to happen, one or more
149: .Em servlets
150: must be registered (see
151: .Xr http_servlet 3) .
152: Servlets are registered by invoking
153: .Fn http_server_register_servlet .
154: .Pp
155: The
156: .Fa vhost
157: parameter may be used for virtual hosting.
158: If
159: .Fa vhost
160: is not
161: .Dv NULL ,
162: it defines a virtual host for the server, and the servlet will only
163: be invoked for requests whose Host: header matches
164: .Fa vhost .
165: If
166: .Fa vhost
167: is
168: .Dv NULL ,
169: the servlet will only be invoked for requests with no Host: header
170: or whose host does not match any other virtual host defined for the server
171: (i.e., a
172: .Dv NULL
173: .Fa vhost
174: indicates the default virtual host).
175: .Pp
176: The servlet will be invoked for queries matching
177: .Fa urlpat ,
178: which is an extended regular expression (see
179: .Xr re_format 7) .
180: .Pp
181: The request URI is URL-decoded before matching begins and
182: only the relative part is matched.
183: For example, a servlet registered to match the regular expression
184: "^/foo bar$" would match "http://server/foo%20bar" and
185: "http://server/foo%20bar?field=value" but not
186: "http://server/foo%20bar/".
187: .Pp
188: If two or more servlets match the same request,
189: the servlet that was registered with the lowest
190: .Fa order
191: is chosen.
192: If two servlets match and have the same
193: .Fa order ,
194: the last one registered is chosen.
195: .Pp
196: The order in which servlets are registered is important, especially with
197: authorization servlets, because incoming requests may arrive at any time.
198: I.e., authorization servlets should be registered before the servlet(s)
199: that they protect.
200: .Pp
201: .Fn http_server_destroy_servlet
202: destroys a servlet, unregistering it as necessary.
203: If any instances of the servlet are executing, this function will
204: block until they exit.
205: Upon return,
206: .Fa "*servletp"
207: is set to
208: .Dv NULL.
209: If
210: .Fa "*servletp"
211: is already
212: .Dv NULL
213: when
214: .Fn http_server_destroy_servlet
215: is invoked, nothing happens.
216: .\"
217: .Ss "Proxy support"
218: .\"
219: Primitive proxy support is provided by
220: .Fn http_server_set_proxy_handler .
221: The
222: .Fa handler
223: is a pointer to a function of this type:
224: .Pp
225: .Bd -literal -offset 3n
226: typedef void http_proxy_t(void *arg, struct http_request *req,
227: struct http_response *resp);
228: .Ed
229: .Pp
230: The
231: .Fa handler
232: is invoked with the same
233: .Fa arg
234: whenever an HTTP proxy request is received.
235: To disable proxy support, invoke
236: .Fn http_server_set_proxy_handler
237: with both arguments equal to
238: .Dv NULL.
239: .Sh RETURN VALUES
240: Upon error,
241: .Fn http_server_start
242: and
243: .Fn http_server_register_servlet
244: return
245: .Dv NULL
246: or -1, respectively, and set
247: .Va errno
248: to an appropriate value.
249: .Sh SEE ALSO
250: .Xr http_client 3 ,
251: .Xr http_mime 3 ,
252: .Xr http_request 3 ,
253: .Xr http_response 3 ,
254: .Xr http_servlet 3 ,
255: .Xr http_xml 3 ,
256: .Xr libpdel 3 ,
257: .Xr pevent 3 ,
258: .Xr syslog 3 ,
259: .Xr re_format 7
260: .Rs
261: .%A R. Fielding
262: .%A J. Gettys
263: .%A J. Mogul
264: .%A H. Frystyk
265: .%A L. Masinter
266: .%A P. Leach
267: .%A T. Berners-Lee
268: .%T "Hypertext Transfer Protocol -- HTTP/1.1"
269: .%O RFC 2616
270: .Re
271: .Sh HISTORY
272: The PDEL library was developed at Packet Design, LLC.
273: .Dv "http://www.packetdesign.com/"
274: .Sh AUTHORS
275: .An Archie Cobbs Aq archie@freebsd.org
276: .Sh BUGS
277: Creating a new thread for each request is somewhat expensive.
278: The server should keep a pool of idle threads for faster dispatch
279: of incoming connections.
280: .Pp
281: The maximum number of connections should be configurable.
282: .Pp
283: The server is probably not fully compliant to the HTTP specification.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to http_server.3 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / libpdel / http