NAME

http_servlet_file — HTTP file servlet

LIBRARY

PDEL Library (libpdel, -lpdel)

SYNOPSIS

#include <sys/types.h>
#include <stdio.h>
#include <netinet/in.h>
#include <openssl/ssl.h>
#include <pdel/tmpl/tmpl.h>
#include <pdel/http/http_defs.h>
#include <pdel/http/http_server.h>
#include <pdel/http/servlet/tmpl.h>
#include <pdel/http/servlet/file.h>

struct http_servlet *
http_servlet_file_create(const struct http_servlet_file_info *info);

void
http_servlet_file_serve(const char *path, http_logger_t *logger, struct http_request *req, struct http_response *resp);

DESCRIPTION

http_servlet_file_create() creates a new servlet that serves HTTP requests from a file or a tree of files in a directory hierarchy, with support for serving tmpl(3) template files.

info is a pointer to a struct http_servlet_file_info:

typedef int http_servlet_file_hide_t(
              const struct http_servlet_file_info *info,
              struct http_request *req, struct http_response *resp,
              const char *path);

struct http_servlet_file_info {
    const char    *docroot;       /* document root, or NULL for cwd */
    u_char        allow_escape;   /* allow url to escape docroot */
    const char    *filename;      /* filename, or NULL to use url */
    const char    *prefix;        /* url prefix to strip, or NULL */
    const char    *mime_type;     /* mime type, or NULL to guess */
    const char    *mime_encoding; /* mime encoding (or NULL) */
    http_logger_t *logger;        /* http error logger */

    http_servlet_file_hide_t       *hide;     /* optional file hider */
    struct http_servlet_tmpl_tinfo tinfo;     /* for *.tmpl files */
};

When a request is received, the above info is used together with the requested URL to identify a file in the filesystem from which to generate the response.

docroot specifies the root directory starting from which relative pathnames are resolved. If docroot is NULL, then the current working directory is assumed.

allow_escape is a boolean value that determines whether the file ultimately served may lie outside of the directory hierarchy rooted at docroot (or the current directory if docroot is equal to NULL). This can happen when symbolic links are encountered.

If not NULL, filename is the pathname of a specific file from which to serve all requests. It may be a relative or absolute pathname; in the relative case, it is relative to docroot.

Otherwise, if filename is NULL, a pathname is generated dynamically as follows. First, if prefix is not NULL and it exactly matches the first part of the requested URL path, then that prefix is removed from the URL path. Note that the first character of prefix must be '/' for it to match. Then a pathname is generated by by treating the requested URL path as a relative pathname relative to docroot.

In all cases, the strings “.”, “..”, and the empty string are disallowed as pathname components in the requested URL path and will generate a “404 Not Found” response.

mime_type may be used to specify the MIME type for the served file, and mime_encoding the content encoding. Either or both may be NULL to let the file servlet try to guess the MIME information.

The logger is a logging function whose type is defined in http_server(3).

The hide function pointer, if not NULL, allows selectively hiding certain files in the directory tree. hide() should return non-zero to hide the file with pathname path, which will always be an absolute pathname in normalized form (see realpath(3)). info points to a read-only copy of the information passed to http_servlet_file_create().

Template support

This servlet is capable of serving tmpl template files by automatically creating http_servlet_tmpl(3) servlets on a demand basis. To enable this feature, the tinfo structure should be filled in with a non- NULL handler field. Then if for any requested file pathname "/foo/bar" there is a file named "/foo/bar.tmpl", then this file will be treated as a tmpl(3) template and passed to the http_servlet_tmpl(3) servlet.

See http_servlet_tmpl(3) for a description of the tinfo structure. Although the same tinfo structure is used to create multiple template servlets, the tinfo.freer() destructor function will only be invoked once, when the enclosing http_servlet_file servlet is destroyed.

The hide() function (if specified) does not block template execution; however, it may still be used to block access to the actual template files themselves.

Directory support

If the file being served is a directory, the file servlet will respond with a corresponding HTTP redirect if any of the following files exist in that directory: index.tmpl, index.html, or index.htm.

http_servlet_file_serve() is a general function sometimes useful when implementing other servlets. It simply serves the file at pathname path using the MIME guessing and directory redirection algorithms.

RETURN VALUES

On failure, http_servlet_file_create() returns NULL and sets 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⟩