Overview

This documentation chapter contains information on the HTTP web application framework and the predefiend HTTP web applications currently available in the Balau library. Developers may also define their own HTTP web applications.

Framework

Creation

The HTTP web application framework is based around the HttpWebApp base class. All HTTP web applications are derived from this base class. HTTP web applications must be registered with the HTTP server framework. Predefined Balau HTTP web applications are automatically registered at application startup. Custom HTTP web applications may be registered by calling HttpWebApp::registerHttpWebApp<WebAppT>(name) before creating the application injector.

Each HTTP web application implements the three request call methods:

			void handleGetRequest(HttpSession & session,
			                      const StringRequest & request,
			                      std::map<std::string, std::string> & variables) override;

			void handleHeadRequest(HttpSession & session,
			                      const StringRequest & request,
			                      std::map<std::string, std::string> & variables) override;

			void handlePostRequest(HttpSession & session,
			                      const StringRequest & request,
			                      std::map<std::string, std::string> & variables) override;

HTTP session

The HttpSession passed during a request call references the active HTTP session for the request in progress. The session object is active on a single thread and may handle multiple keep-alive round trips. The session object provides access to:

the HTTP server's main configuration;
the remote IP address for logging;
the client session;
the cookies sent in the request;
the sendResponse method used to send the response.

Client session

The client session referenced within the HTTP session is a long lived session that is obtained on each request by examining the session cookie sent by the client. The name of this session cookie may be specified in the HTTP server's global configuration. By default, the name of the session cookie is session.

The client session Id is present for web applications to use in order to allow stateful sessions such as logins and carts.

Request object

The request object passed during a request call is the full Boost Beast request. Web applications can access request fields and other information available from the Beast request message API.

Request variables

The request variables map passed during a request call are variables that are created and consumed by filters and web applications during the request. They are not related to the request HTTP fields. An example of request variables can be seen in the redirections HTTP web application, which creates temporary request variables named $1, $2, $2, etc. for regular expression groupings in the redirection matches.

Configuration

Each web application must have a location parameter in its configuration. The value of this parameter is a space delimited set of location prefixes that the web application will handle. During instantiation, the HTTP server will read this parameter on each web application's configuration and use the location prefixes within to construct the request routing.

Web applications

File server

#include <Balau/Network/Http/Server/HttpWebApps/FileServingHttpWebApp.hpp>

Environment configuration: files

The file serving HTTP web application serves files from a directory on the local file system.

See the files environment configuration for details on how to configure the file serving HTTP web application.

Email sender

#include <Balau/Network/Http/Server/HttpWebApps/EmailSendingHttpWebApp.hpp>

Environment configuration: email.sender

The email sending HTTP web application sends an email with a body generated from the form parameters of a POST request. This can be useful for creating a contact page.

See the email.sender environment configuration for details on how to configure the email sending HTTP web application.

Redirector

#include <Balau/Network/Http/Server/HttpWebApps/RedirectingHttpWebApp.hpp>

Environment configuration: redirections

The redirecting HTTP web application performs 301 or 302 redirections for specified locations.

See the redirections environment configuration for details on how to configure the redirecting HTTP web application.

Canned

#include <Balau/Network/Http/Server/HttpWebApps/CannedHttpWebApp.hpp>

Environment configuration: canned

The canned HTTP web application serves fixed responses for GET, HEAD, and POST requests.

See the canned environment configuration for details on how to configure the canned HTTP web application.

Failing

#include <Balau/Network/Http/Server/HttpWebApps/FailingHttpWebApp.hpp>

Environment configuration: failing

The failing HTTP web application returns HTTP 404 responses for all requests.

See the failing environment configuration for details on how to configure the failing HTTP web application.

Routing

#include <Balau/Network/Http/Server/HttpWebApps/RoutingHttpWebApp.hpp>

Environment configuration: n/a

The current routing web application may be replaced by a regular expression based routing web application in the future.

The routing HTTP web application contains a trie data structure used to route HTTP requests to different HTTP web applications.

The routing HTTP web application is normally used implicitly via environment configuration. The HTTP server will instantiate a routing HTTP web application when creating the HTTP web application tree. When defining the HTTP server HTTP web applications via environment configuration, it is thus not necessary to explicitly define a routing HTTP web application.

The routing HTTP web application may be explicitly used when manually building an HTTP web application routing tree in code. Simple examples of this are available in the Balau unit tests. For example, one of the email sender unit tests defines the following routing HTTP web application.

			// Create the routing HTTP web app, specifying the root node.
			RoutingHttpWebApp::Routing routing(routingNode<FailingHttpWebApp>(""));

			// Add the email sender handler at path "/1/send-message".
			routing.add(
				  routingNode("1")
				, RoutingHttpWebApp::Node::child(
					RoutingHttpWebApp::Value(
						"send-message", emailHandler, emailHandler, emailHandler
					)
				)
			);

In order to facilitate the manual building of routing trees, the RoutingHttpWebApp.hpp header contains the following helper methods and type.

Name	Description
routingNode	Make a routing node (3 overloads).
RoutingHttpWebApp::Node::child	Add a child of the child being added, plus descendants of the child (2 overloads).
RoutingHttpWebApp::Value	The tuple type representing a routing node.