An asynchronous HTTP/WebSocket server. More...

#include <HttpServer.hpp>

Public Member Functions
	HttpServer (std::shared_ptr< System::Clock > clock, const std::shared_ptr< EnvironmentProperties > &configuration, bool registerSignalHandler=true)
	Create an HTTP server configured with the HTTP server configuration pointed to by the URI. More...

	HttpServer (std::shared_ptr< System::Clock > clock, const std::string &serverIdentification, const TCP::endpoint &endpoint, std::string threadNamePrefix_, size_t workerCount_, std::shared_ptr< HttpWebApp > httpHandler, std::shared_ptr< WsWebApp > wsHandler=std::shared_ptr< WsWebApp >(nullptr), const std::string &loggingNamespace="balau.network.server", std::string sessionCookieName="session", std::shared_ptr< MimeTypes > mimeTypes=MimeTypes::defaultMimeTypes, bool registerSignalHandler=true)
	Create an HTTP server with HTTP and optional WebSocket handlers. More...

	HttpServer (std::shared_ptr< System::Clock > clock, const std::string &serverIdentification, const TCP::endpoint &endpoint, std::string threadNamePrefix_, size_t workerCount_, const Resource::File &documentRoot, const std::string &defaultFile="index.html", const std::string &loggingNamespace="balau.network.server", std::string sessionCookieName="session", std::shared_ptr< MimeTypes > mimeTypes=MimeTypes::defaultMimeTypes, bool registerSignalHandler=true)
	Create an HTTP server using the file serving HTTP handler. More...

	~HttpServer ()
	Destroy the HTTP server, stopping it if it is running. More...

std::string	getAddress () const
	Get the address being listened on. More...

unsigned short	getPort () const
	Get the port being listened on. More...

bool	isRunning ()
	Returns true if the server is running. More...

void	startAsync ()
	Start the HTTP server and return once the worker threads are running. More...

void	startSync ()
	Start the HTTP server and block until the server is stopped. More...

void	stop (bool warn=false)
	Stop the HTTP server. More...

Detailed Description

An asynchronous HTTP/WebSocket server.

HTTP and WebSocket messages are handled by the web application handlers supplied to the server's constructor. Complex handler infrastructure may be created by using HTTP and WebSocket routing web application instances, either in code or via text based server configuration.

As WebSocket connections are initiated via an HTTP upgrade, the HttpServer class also manages WebSocket connections via upgrades initiated from created HttpSessions.

In order to use automatic thread naming, leave the thread name prefix empty. In order to use one worker thread per CPU core, set the worker count to zero.

The HTTP server registers signal handlers via a Boost Asio signal set in order to ensure a graceful shut down. If the application subsequently calls signal() or sigaction(), these handlers will be overridden. In order to avoid this, use Boost Asio signal sets for all signal handler registrations in the application.

The HTTP server and web application framework supports the use of injectors. The server shared state that is supplied to the web application handlers contains a shared pointer to an injector. If an injector is supplied to the constructor of the HTTP server, the injector will be available to handlers.

Application developers are responsible for ensuring that a suitable injector is supplied to the HTTP server instance when one or more of the handlers require one. Otherwise, the application will be defective and will cause a segmentation fault when the injector nullptr is accessed.

Constructor & Destructor Documentation

◆ HttpServer() [1/3]

HttpServer	(	std::shared_ptr< System::Clock >	clock,
		const std::shared_ptr< EnvironmentProperties > &	configuration,
		bool	registerSignalHandler = `true`
	)

Create an HTTP server configured with the HTTP server configuration pointed to by the URI.

The supplied injector will be used by the handlers during requests to obtain injected instances.

This constructor can be used within an injector configuration in order to bind an HTTP server that is configured via complex configuration.

By default, the HTTP server installs its own signal handler in order to provide graceful shutdown in SIGINT and SIGTERM. If this is not required, the registerSignalHandler parameter can be set to false. This is set by default to true in the Balau environment configuration specification.

Parameters

injector	the injector to use in the web apps
clock	the clock to be used in the server
configuration	the server configuration
registerSignalHandler	(default = true) set to false in order to prevent signal handler installation

◆ HttpServer() [2/3]

HttpServer	(	std::shared_ptr< System::Clock >	clock,
		const std::string &	serverIdentification,
		const TCP::endpoint &	endpoint,
		std::string	threadNamePrefix_,
		size_t	workerCount_,
		std::shared_ptr< HttpWebApp >	httpHandler,
		std::shared_ptr< WsWebApp >	wsHandler = `std::shared_ptr< WsWebApp >(nullptr)`,
		const std::string &	loggingNamespace = `"balau.network.server"`,
		std::string	sessionCookieName = `"session"`,
		std::shared_ptr< MimeTypes >	mimeTypes = `MimeTypes::defaultMimeTypes`,
		bool	registerSignalHandler = `true`
	)

Create an HTTP server with HTTP and optional WebSocket handlers.

In addition to direct instantiation, this constructor can be used within an injector provider.

Parameters

clock	the clock to be used in the server
serverIdentification	the server string to return
endpoint	the network address and port to listen on
threadNamePrefix_	the prefix of the worker thread names (used for logging)
workerCount_	the number of worker threads to use
httpHandler	the HTTP request handler to use
wsHandler	the WebSocket message handler to use (default is no WebSocket handler)
loggingNamespace	the logging namespace to use (default = "balau.network.server")
sessionCookieName	the name of the cookie in which the session id is stored (default = "session")
mimeTypes	the mime type map to use
registerSignalHandler	(default = true) set to false in order to prevent signal handler installation

◆ HttpServer() [3/3]

HttpServer	(	std::shared_ptr< System::Clock >	clock,
		const std::string &	serverIdentification,
		const TCP::endpoint &	endpoint,
		std::string	threadNamePrefix_,
		size_t	workerCount_,
		const Resource::File &	documentRoot,
		const std::string &	defaultFile = `"index.html"`,
		const std::string &	loggingNamespace = `"balau.network.server"`,
		std::string	sessionCookieName = `"session"`,
		std::shared_ptr< MimeTypes >	mimeTypes = `MimeTypes::defaultMimeTypes`,
		bool	registerSignalHandler = `true`
	)

Create an HTTP server using the file serving HTTP handler.

The mime type map can be specified or left as the default mime type map.

Parameters

clock	the clock to be used in the server
serverIdentification	the server string to return
endpoint	the network address and port to listen on
threadNamePrefix_	the prefix of the worker thread names (used for logging)
workerCount_	the number of worker threads to use
mimeTypes	the mime type map to use
documentRoot	the root file system path for serving files
loggingNamespace	the logging namespace to use (default = "balau.network.server")
sessionCookieName	the name of the cookie in which the session id is stored (default = "session")
defaultFile	the default file to return if no file is specified in the request
registerSignalHandler	(default = true) set to false in order to prevent signal handler installation

◆ ~HttpServer()

~HttpServer ( )

Destroy the HTTP server, stopping it if it is running.

Member Function Documentation

◆ getAddress()

std::string getAddress ( ) const

inline

Get the address being listened on.

◆ getPort()

unsigned short getPort ( ) const

inline

Get the port being listened on.

◆ isRunning()

bool isRunning ( )

Returns true if the server is running.

Returns: true if the server is running

◆ startAsync()

void startAsync ( )

Start the HTTP server and return once the worker threads are running.

This call should be used to start the server when the calling thread should not be used as one of the workers.

If the server is already running, this call is a NOP.

Exceptions

NetworkException if there was an issue initialising the listener

◆ startSync()

void startSync ( )

Start the HTTP server and block until the server is stopped.

This call should be used to start the server when the calling thread should be used as one of the workers.

Exceptions

NetworkException if there was an issue initialising the listener

◆ stop()

void stop ( bool warn = false )

Stop the HTTP server.

If the server is already stopped, this call is a NOP.

Parameters

warn	warn if the server is already stopped (default = false)

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

HttpServer.hpp (9)

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ HttpServer() [1/3]

◆ HttpServer() [2/3]

◆ HttpServer() [3/3]

◆ ~HttpServer()

Member Function Documentation

◆ getAddress()

◆ getPort()

◆ isRunning()

◆ startAsync()

◆ startSync()

◆ stop()