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 supplying 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 accept 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 connections until one or more existing connections terminate.

The server_name string is used for the "Server:" HTTP header and typically 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 destroyed (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 invoked, 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 registered (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 defined 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 relative 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 function 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() return NULL or -1, respectively, and set errno to an appropriate value.

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 incoming connections.

The maximum number of connections should be configurable.

The server is probably not fully compliant to the HTTP specification.