Annotation of embedaddon/libpdel/http/http_server.3, revision 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