FreeBSD Manual Pages
HTTP_SERVER(3) Library Functions Manual HTTP_SERVER(3) NAME http_server -- threaded server for HTTP and HTTPS LIBRARY PDEL Library (libpdel, -lpdel) SYNOPSIS #include <sys/types.h> #include <stdio.h> #include <netinet/in.h> #include <openssl/ssl.h> #include <pdel/http/http_defs.h> #include <pdel/http/http_server.h> struct http_server * 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); void http_server_stop(struct http_server **serverp); int http_server_register_servlet(struct http_server *serv, struct http_servlet *servlet, const char *vhost, const char *urlpat, int order); void http_server_destroy_servlet(struct http_servlet **servletp); void http_server_set_proxy_handler(struct http_server *serv, http_proxy_t *handler, void *arg); DESCRIPTION These functions implement a threaded HTTP server supporting SSL and user-definable "servlets". http_server_start() starts a new server listening on IP address ip and port port. If ip is 0.0.0.0 then the server listens on all configured IP addresses. If port is zero then the default port (either 80 or 443 depending on whether SSL is enabled) is used. SSL is enabled by sup- plying a non-NULL pointer ssl to this structure: struct http_server_ssl { const char *cert_path; /* path to certificate file */ const char *pkey_path; /* path to private key file */ const char *pkey_password; /* private key password, if needed */ }; ctx is a pevent(3) event context with which the server registers to ac- cept incoming connections. New connections are allocated individual threads in which to execute. The server enforces a hard limit of at most 1024 simultaneous connections, refusing to accept any new connec- tions until one or more existing connections terminate. The server_name string is used for the "Server:" HTTP header and typi- cally includes the name and version number of the software, e.g., "MyServer/1.0". The logger, if not NULL, specifies a callback for logging: typedef void http_logger_t(int sev, const char *fmt, ...); Here sev is a syslog(3) severity level. http_server_stop() stops a server. All registered servlets are de- stroyed (see http_server_destroy_servlet() below). Upon return, all connection threads are guaranteed to have exited and *serverp will be set to NULL. If *serverp is already NULL when http_server_stop() is in- voked, nothing happens. Invoking http_server_stop() from within a servlet is not supported and will give undefined results. Servlets For anything interesting to happen, one or more servlets must be regis- tered (see http_servlet(3)). Servlets are registered by invoking http_server_register_servlet(). The vhost parameter may be used for virtual hosting. If vhost is not NULL, it defines a virtual host for the server, and the servlet will only be invoked for requests whose Host: header matches vhost. If vhost is NULL, the servlet will only be invoked for requests with no Host: header or whose host does not match any other virtual host de- fined for the server (i.e., a NULL vhost indicates the default virtual host). The servlet will be invoked for queries matching urlpat, which is an extended regular expression (see re_format(7)). The request URI is URL-decoded before matching begins and only the rel- ative part is matched. For example, a servlet registered to match the regular expression "^/foo bar$" would match "http://server/foo%20bar" and "http://server/foo%20bar?field=value" but not "http://server/foo%20bar/". If two or more servlets match the same request, the servlet that was registered with the lowest order is chosen. If two servlets match and have the same order, the last one registered is chosen. The order in which servlets are registered is important, especially with authorization servlets, because incoming requests may arrive at any time. I.e., authorization servlets should be registered before the servlet(s) that they protect. http_server_destroy_servlet() destroys a servlet, unregistering it as necessary. If any instances of the servlet are executing, this func- tion will block until they exit. Upon return, *servletp is set to NULL. If *servletp is already NULL when http_server_destroy_servlet() is invoked, nothing happens. Proxy support Primitive proxy support is provided by http_server_set_proxy_handler(). The handler is a pointer to a function of this type: typedef void http_proxy_t(void *arg, struct http_request *req, struct http_response *resp); The handler is invoked with the same arg whenever an HTTP proxy request is received. To disable proxy support, invoke http_server_set_proxy_handler() with both arguments equal to NULL. RETURN VALUES Upon error, http_server_start() and http_server_register_servlet() re- turn NULL or -1, respectively, and set errno to an appropriate value. SEE ALSO http_client(3), http_mime(3), http_request(3), http_response(3), http_servlet(3), http_xml(3), libpdel(3), pevent(3), syslog(3), re_format(7) R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, and T. Berners-Lee, Hypertext Transfer Protocol -- HTTP/1.1, RFC 2616. HISTORY The PDEL library was developed at Packet Design, LLC. http://www.packetdesign.com/ AUTHORS Archie Cobbs <archie@freebsd.org> BUGS Creating a new thread for each request is somewhat expensive. The server should keep a pool of idle threads for faster dispatch of incom- ing connections. The maximum number of connections should be configurable. The server is probably not fully compliant to the HTTP specification. FreeBSD ports 15.0 April 22, 2002 HTTP_SERVER(3)
NAME | LIBRARY | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | HISTORY | AUTHORS | BUGS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=http_server_set_proxy_handler&sektion=3&manpath=FreeBSD+Ports+15.0>