Small multi-threaded HTTP server. More...

#include <http.h>

Inheritance diagram for mlib::http::server:

Public Member Functions
	server (unsigned short port=0, unsigned int maxconn=0)
	Constructor.

	~server ()
	Destructor.

void	add_ohdr (const std::string &hdr, const std::string &value)
	Add or modify a server response header.

void	remove_ohdr (const std::string &hdr)
	Remove a server response header.

void	add_handler (const std::string &uri, uri_handler func, void *info=0)
	Add or modify an URI handler function.

void	add_post_handler (const std::string &uri, uri_handler func, void *info=0)
	Add or modify an POST handler function.

void	add_user (const std::string &realm, const std::string &username, const std::string &pwd)
	Add a new user to a protection realm.

void	remove_user (const std::string &realm, const std::string &username)
	Remove an allowed user from an protection realm.

void	add_secured_path (const std::string &realm, const std::string &uri)
	Add an URI to a protection realm.

template<typename T>
void	add_var (const std::string &name, const T addr, const char fmt=nullptr)

template<typename T>
std::enable_if_t< std::is_floating_point_v< T > >	add_var (const std::string &name, const T addr, const char fmt=nullptr, double multiplier=1.)

const std::string	get_var (const std::string &name)
	Return the current string representation of a variable.

void	aquire_varlock ()
	Acquire lock on server's variables.

void	release_varlock ()
	Release lock on server's variables.

bool	try_varlock ()
	Try to acquire lock on server's variables.

void	name (const std::string &name_)
	Change server name.

void	docroot (const std::filesystem::path &path)
	Set server root path.

const std::filesystem::path &	docroot () const
	Return current root path as absolute path.

void	add_alias (const std::string &uri, const std::string &path)
	Maps a local file path to an URI resource path.

void	default_uri (const std::string &name)
	Set default file name (initially `index.html`)

const std::string &	default_uri () const
	Return default file name (initially `index.html`)

void	keep_alive (std::chrono::seconds secs)
	Set timeout value for keep-alive connections.

std::chrono::seconds	keep_alive () const
	Return timeout value for keep-alive connections.

bool	is_protected (const std::string &uri, std::string &realm)
	Find if URI is covered by a protection realm.

virtual bool	verify_authorization (const std::string &realm, const std::string &user, const std::string &password)

Public Member Functions inherited from mlib::tcpserver
	tcpserver (unsigned short port, unsigned int max_conn=0, const std::string &name=std::string())
	Opens the socket and initializes the connections table.

	~tcpserver ()
	Terminate any connection that still exists.

sock &	socket ()
	Provides access to server listening socket.

void	foreach (conn_iter_func f, void *param)
	Invoke an iteration function for each active connection.

thread *	get_connection_thread (const sock &conn_sock)
	Return the thread servicing a connection.

void	close_connection (const sock &conn_sock)
	Closes a connection.

void	terminate ()
	Terminate the tcp server.

size_t	numconn () const
	Return number of active connections.

unsigned int	timeout () const
	Return max interval to wait for an incoming connection (in milliseconds)

void	timeout (DWORD msec)
	Set maximum timeout interval (in milliseconds)

void	maxconn (unsigned int new_max)
	Set maximum number of connections accepted.

unsigned int	maxconn () const
	Return maximum number of connections accepted.

void	set_connfunc (std::function< int(const sock &)> f)
	Set function object that becomes the body of the thread serving a new connection.

Public Member Functions inherited from mlib::thread
	thread (std::function< unsigned int()> func)
	Make a thread with the given function body.

virtual	~thread ()
	Destructor.

virtual void	start ()
	Begin execution of a newly created thread.

void	fork ()
	Another name for start () function.

void	join ()
	Another name for wait () function.

DWORD	wait (DWORD time_limit=INFINITE)
	Wait for thread to finish execution.

DWORD	wait_alertable (DWORD time_limit=INFINITE)
	Wait for thread to finish or an APC, or IO completion routine to occur.

DWORD	wait_msg (DWORD time_limit=INFINITE, DWORD mask=QS_ALLINPUT)
	Wait for thread to finish or a message to be queued.

void	rethrow_exception () const
	Rethrow an exception usually in the context of another thread.

DWORD	id () const
	Return thread's ID.

UINT	result () const
	Return thread's exit code.

bool	is_running () const
	Return true if thread is running.

state	get_state () const
	Return thread's execution status.

int	priority () const
	Return thread's priority.

void	priority (int pri)
	Set thread's priority.

virtual const std::string &	name () const
	Return object's name.

Public Member Functions inherited from mlib::syncbase
	syncbase ()
	Default constructor.

	syncbase (const syncbase &e)
	Copy constructor.

	syncbase (syncbase &&e) noexcept
	Move constructor.

virtual	~syncbase ()
	Destructor.

syncbase &	operator= (const syncbase &rhs)
	Assignment operator.

syncbase &	operator= (syncbase &&rhs) noexcept
	Move assignment operator.

int	operator== (const syncbase &rhs) const
	Equality operator.

virtual void	wait ()
	Wait for object to become signaled.

virtual DWORD	wait (std::chrono::milliseconds limit)
	Wait a number of milliseconds for the object to become signaled.

	operator bool ()
	Check if object is signaled.

virtual bool	is_signaled ()
	Try to wait on the object.

HANDLE	handle () const
	Return OS handle of this object.

Static Public Member Functions
static void	add_mime_type (const std::string &ext, const std::string &type, bool shtml=false)
	Add/change content of table matching MIME types to file extensions.

static void	delete_mime_type (const std::string &ext)
	Remove a file type from the MIME type table.

Protected Types
enum	vtype { VT_UNKNOWN , VT_BOOL , VT_CHAR , VT_STRING , VT_SHORT , VT_USHORT , VT_INT , VT_UINT , VT_LONG , VT_ULONG , VT_FLOAT , VT_DOUBLE }
	SSI variables type. More...

Protected Member Functions
int	invoke_handler (connection &client)
	Invoke a user defined URI handler.

int	invoke_post_handler (connection &client)
	Invoke a user defined handler in response to a POST or PUT request.

bool	find_alias (const std::string &res, std::filesystem::path &path)
	Retrieve the local file path mapped to a resource.

virtual bool	locate_resource (const std::string &res, std::filesystem::path &path)
	Try to map a resource to a local file.

const std::string &	guess_mimetype (const std::filesystem::path &fn, bool &shtml)
	Guess MIME type of a file and if SSI replacement should be enabled based on file extension.

connection *	make_thread (sock &connection)
	Create an new mlib::http::connection object in response to a new client connection request.

void	add_var (const std::string &name, vtype t, const void addr, const char fmt=nullptr, double multiplier=1.)
	Add or modify a user variable.

Protected Member Functions inherited from mlib::tcpserver
bool	init () override
	Binds the server socket to listening address and places it in listen mode.

void	run () override
	Run loop.

virtual bool	idle_action ()
	Called periodically from run loop.

virtual void	initconn (sock &conn_sock, thread *thread)
	Initializes a connection.

virtual void	termconn (sock &conn_sock, thread *thread)
	Finalizes a connection.

Protected Member Functions inherited from mlib::thread
	thread (const std::string &name=std::string(), DWORD stack_size=0, PSECURITY_DESCRIPTOR sd=NULL, bool inherit=false)
	Protected constructor for use of thread-derived objects.

virtual void	term ()
	Finalization function called after run.

Protected Member Functions inherited from mlib::syncbase
	syncbase (const std::string &name)
	Protected constructor.

void	set_handle (HANDLE h)
	Change object's handle. Closes the previous one.

Friends
class	connection

Additional Inherited Members
Public Types inherited from mlib::thread
enum class	state { ready , starting , running , ending , finished }
	Execution state of a thread. More...

Protected Attributes inherited from mlib::thread
unsigned int	exitcode
	exit code

Detailed Description

Small multi-threaded HTTP server.

This class is derived from mlib::tcpserver class and implements a basic HTTP server.

After construction, the main server thread has to be started by calling start() function. When started, the server binds to the listening socket and creates new http::connection objects for each incoming client. All the protocol is then handled by the connection (or derived) object.

A HTTP server can be integrated to an application by adding specific handlers and/or user variables. Handlers are user functions called in response to client requests. There are two types of handlers:

global handlers registered using the add_handler() function. These are called by the client connection thread immediately after validating a client request.
post handlers registered using the add_post_handler() function. These are called only for POST or PUT requests.

User variables can be added by calling the add_var() function. The content of those variables is then returned in response to SSI echo directives.

Member Enumeration Documentation

◆ vtype

enum mlib::http::server::vtype

protected

SSI variables type.

Enumerator
VT_UNKNOWN	illegal
VT_BOOL	bool*
VT_CHAR	char*
VT_STRING	std::string*
VT_SHORT	short int*
VT_USHORT	unsigned short*
VT_INT	int*
VT_UINT	unsigned int*
VT_LONG	long*
VT_ULONG	unsigned long*
VT_FLOAT	float*
VT_DOUBLE	double*

Constructor & Destructor Documentation

◆ server()

mlib::http::server::server	(	unsigned short	port = 0,
		unsigned int	maxconn = 0 )

explicit

Constructor.

Parameters

port	listening port
maxconn	maximum number of incoming connections. If 0 the number of connections is unlimited

If port is 0, when the server is started it will bind to an available port on local interface only.

document root is current folder
default url is HTTP_DEFAULT
server name is HTTP_SERVER_NAME

Member Function Documentation

◆ add_alias()

void mlib::http::server::add_alias	(	const std::string &	uri,
		const std::string &	path )

Maps a local file path to an URI resource path.

Parameters

uri	URI resource path
path	mapped local file path

The mapping is always relative to server's root folder (docroot).

◆ add_handler()

void mlib::http::server::add_handler	(	const std::string &	uri,
		uri_handler	func,
		void *	info = 0 )

Add or modify an URI handler function.

Parameters

uri	URI address
func	handler function
info	handler specific information

When a HTTP client requests the URI, the connection object that services the client connection will invoke the user-defined handler function passing the connection object and the handler specific information.

Example:

int say_hello (http::connection& client, void *)
{
  client.serve_buffer ("Hello world!");
  return HTTP_OK;
}
//...
http::server my_server(8080);
 
my_server.add_handler ("/greeting", say_hello, nullptr);

In response to a request to http://localhost:8080/greeting, the server will display the greeting message.

Note: These handlers are invoked irrespective of the HTTP method (GET, POST, DELETE, etc.).

◆ add_mime_type()

void mlib::http::server::add_mime_type	(	const std::string &	ext,
		const std::string &	type,
		bool	shtml = false )

static

Add/change content of table matching MIME types to file extensions.

Parameters

ext	filename extension
type	MIME type
shtml	true if SSI processing should be enabled for this file type

◆ add_ohdr()

void mlib::http::server::add_ohdr	(	const std::string &	hdr,
		const std::string &	value )

Add or modify a server response header.

Parameters

hdr	Header name
value	Header value

Server response headers are always sent as part of the HTTP answer. In addition each connection object can add it's own headers.

◆ add_post_handler()

void mlib::http::server::add_post_handler	(	const std::string &	uri,
		uri_handler	func,
		void *	info = 0 )

Add or modify an POST handler function.

Parameters

uri	URI address
func	handler function
info	handler specific information

These handlers work just like the handlers defined using the add_handler() function, except that they are invoked only for POST or PUT requests.

◆ add_secured_path()

void mlib::http::server::add_secured_path	(	const std::string &	realm,
		const std::string &	uri )

Add an URI to a protection realm.

Parameters

realm	protection realm
uri	URI path

◆ add_user()

void mlib::http::server::add_user	(	const std::string &	realm,
		const std::string &	username,
		const std::string &	pwd )

Add a new user to a protection realm.

Parameters

realm	access realm
username	user name
pwd	user password

If user already exists, it just modifies the access credentials

◆ add_var() [1/3]

template<typename T>

void mlib::http::server::add_var	(	const std::string &	name,
		const T *	addr,
		const char *	fmt = nullptr )

inline

Add a variable to the dictionary of SSI variables

Template Parameters

T	variable's type (non-floating point)

Parameters

name	variable's SSI name
addr	pointer to variable
fmt	sprintf formatting specifier

◆ add_var() [2/3]

template<typename T>

std::enable_if_t< std::is_floating_point_v< T > > mlib::http::server::add_var	(	const std::string &	name,
		const T *	addr,
		const char *	fmt = nullptr,
		double	multiplier = 1. )

inline

Add a variable to the dictionary of SSI variables

Template Parameters

T	variable's type (floating point)

Parameters

name	variable's SSI name
addr	pointer to variable
fmt	sprintf formatting specifier
multiplier	scaling factor

◆ add_var() [3/3]

void mlib::http::server::add_var	(	const std::string &	name,
		vtype	t,
		const void *	addr,
		const char *	fmt = nullptr,
		double	multiplier = 1. )

protected

Add or modify a user variable.

Parameters

name	name of variable (the name used in SSI construct)
t	type of variable
addr	address of content
fmt	sprintf format string
multiplier	for numeric variables, resulting value is multiplied by this factor

User variables are accessible through SSI constructs like:

When the page is served the SSI construct is replaced by the current value of the named variable, eventually multiplied by multiplier factor and formatted as text using the fmt string. If format string is NULL, a format appropriate for the variable type is used

◆ delete_mime_type()

void mlib::http::server::delete_mime_type ( const std::string & ext )

static

Remove a file type from the MIME type table.

Parameters

ext	filename extension

◆ find_alias()

bool mlib::http::server::find_alias	(	const std::string &	res,
		std::filesystem::path &	path )

protected

Retrieve the local file path mapped to a resource.

Parameters

res	resource path
path	local path

Returns: true if resource was remapped.

After processing the alias table, any part of the original resource that was not mapped is appended to the resulting path. For instance if the alias table contains an entry mapping "doc" to "documentation" and docroot is set as "c:\\local_folder\\", a resource like "/doc/project1/filename.html" will be mapped to "c:\local_folder\documentation\project1\filename.html". Note that mapping is only lexical. The function does not check if the resource exists. Remapping is "greedy". If the alias table contains two mappings for "doc" and "doc/new", a resource like "/doc/new/manual.html" will use the mapping for "/doc/new"

◆ get_var()

const string mlib::http::server::get_var ( const std::string & name )

Return the current string representation of a variable.

Parameters

name	variable name

◆ guess_mimetype()

const std::string & mlib::http::server::guess_mimetype	(	const std::filesystem::path &	fn,
		bool &	shtml )

protected

Guess MIME type of a file and if SSI replacement should be enabled based on file extension.

Parameters

fn	file name
shtml	return true if SSI replacement should be enabled for this file type

Returns: MIME type

◆ invoke_handler()

int mlib::http::server::invoke_handler ( connection & client )

protected

Invoke a user defined URI handler.

Parameters

client connection thread

Returns: the result of calling the user handler or HTTP_NO_HANDLER if there is no handler set for the URI.

◆ invoke_post_handler()

int mlib::http::server::invoke_post_handler ( connection & client )

protected

Invoke a user defined handler in response to a POST or PUT request.

Parameters

client connection thread

Returns: the result of calling the user handler or 0 if there is no handler set for the URI.

◆ is_protected()

bool mlib::http::server::is_protected	(	const std::string &	uri,
		std::string &	realm )

Find if URI is covered by a protection realm.

Parameters

uri	URI to check

Returns: true if URI is covered by a realm

◆ locate_resource()

bool mlib::http::server::locate_resource	(	const std::string &	res,
		std::filesystem::path &	path )

protectedvirtual

Try to map a resource to a local file.

Parameters

res	resource to map
path	local file system path

Returns: true if a local file exists and is a regular file; false otherwise

◆ make_thread()

connection * mlib::http::server::make_thread ( sock & connection )

protectedvirtual

Create an new mlib::http::connection object in response to a new client connection request.

Derived classes can override this function to return objects derived from mlib::http::connection class.

Reimplemented from mlib::tcpserver.

◆ name()

void mlib::http::server::name ( const std::string & name_ )

virtual

Change server name.

Parameters

name_ new server name string

This string is returned in the "Server" HTTP header.

Reimplemented from mlib::thread.

◆ remove_ohdr()

void mlib::http::server::remove_ohdr ( const std::string & hdr )

Remove a server response header.

Parameters

hdr	Header name

◆ try_varlock()

bool mlib::http::server::try_varlock ( )

inline

Try to acquire lock on server's variables.

Returns: true if lock was acquired

The documentation for this class was generated from the following files:

include/mlib/http.h
src/http.cpp

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ vtype

Constructor & Destructor Documentation

◆ server()

Member Function Documentation

◆ add_alias()

◆ add_handler()

◆ add_mime_type()

◆ add_ohdr()

◆ add_post_handler()

◆ add_secured_path()

◆ add_user()

◆ add_var() [1/3]

◆ add_var() [2/3]

◆ add_var() [3/3]

◆ delete_mime_type()

◆ find_alias()

◆ get_var()

◆ guess_mimetype()

◆ invoke_handler()

◆ invoke_post_handler()

◆ is_protected()

◆ locate_resource()

◆ make_thread()

◆ name()

◆ remove_ohdr()

◆ try_varlock()