#include <tsRestServer.h>

Public Member Functions
	RestServer (const RestArgs &args, Report &report)
void	addResponseHeader (const UString &name, const UString &value)
bool	getPostJSON (json::ValuePtr &value) const
void	getPostText (UString &data) const
bool	getRequest (TCPConnection &conn)
bool	hasParameter (const UString &name) const
UString	header (const UString &name, const UString &def_value=UString()) const
const UStringToUStringMultiMap &	headers () const
const UString &	method () const
UString	parameter (const UString &name, const UString &def_value=UString()) const
const UStringToUStringMultiMap &	parameters () const
const UString &	path () const
const UString &	postContentType () const
const ByteBlock &	postData () const
void	replaceResponseHeader (const UString &name, const UString &value)
void	reset ()
bool	sendResponse (TCPConnection &conn, int http_status, bool close)
void	setResponse (const ByteBlock &data, const UString &mime_type=u"application/octet-stream")
void	setResponse (const json::Value &value, const UString &mime_type=u"application/json")
void	setResponse (const UString &text, const UString &mime_type=u"text/plain; charset=utf-8")
const UString &	token () const

Static Public Attributes
static constexpr cn::milliseconds	DEFAULT_SERVER_RECEIVE_TIMEOUT = cn::milliseconds(3000)

Detailed Description

Basic helper for REST API servers.

Constructor & Destructor Documentation

◆ RestServer()

ts::RestServer::RestServer	(	const RestArgs &	args,
		Report &	report )

Constructor.

Parameters

[in]	args	Initial REST operation arguments. This instance will keep a copy of it. If no receive timeout is specified for client connection, DEFAULT_SERVER_RECEIVE_TIMEOUT is applied.
[in,out]	report	Where to report errors. This instance will keep a reference to it.

Member Function Documentation

◆ reset()

void ts::RestServer::reset ( )

Cleanup request data, restart from an empty state.

◆ getRequest()

bool ts::RestServer::getRequest ( TCPConnection & conn )

Accept and decode one client request. If the RestArgs contains a non-empty authentication token, this token is checked in the request headers. If there is no matching token in the request, the request is rejected and the connection is closed.

Parameters

[in,out] conn Client connection. This can be any TCPConnection but usually this is a TLSConnection.

Returns: True on success, false on error. In case of error, the connection is closed.

◆ method()

const UString & ts::RestServer::method ( ) const

inline

Return the request method of the previous getRequest().

Returns: A constant reference to the request method, typically "GET" or "POST".

◆ path()

const UString & ts::RestServer::path ( ) const

inline

Get the path of the last received request.

Returns: A constant reference to the path of the last received request.

◆ parameters()

const UStringToUStringMultiMap & ts::RestServer::parameters ( ) const

inline

Get a multimap of all request's query parameters.

Returns: A constant reference to the parameters. Valid until the next request.

◆ hasParameter()

bool ts::RestServer::hasParameter ( const UString & name ) const

Check if the request's query parameters contains a parameter.

Parameters

[in] name Name of the parameter to check.

Returns: True if the parameter name is present, false otherwise.

◆ parameter()

UString ts::RestServer::parameter	(	const UString &	name,
		const UString &	def_value = UString() ) const

Get the value of a given request's query parameter.

Parameters

[in]	name	Name of the parameter to fetch.
[in]	def_value	Value to return if the parameter name is not present.

Returns: The value of the parameter name, or the default value.

◆ headers()

const UStringToUStringMultiMap & ts::RestServer::headers ( ) const

inline

Get a multimap of all request headers.

Returns: A constant reference to the headers. Valid until the next request.

◆ header()

UString ts::RestServer::header	(	const UString &	name,
		const UString &	def_value = UString() ) const

Get the first value of a given request header.

Parameters

[in]	name	Name of the header to fetch.
[in]	def_value	Value to return if the header name is not present.

Returns: The value of the header name, or the default value.

◆ token()

const UString & ts::RestServer::token ( ) const

inline

Get the authentication token of the last received request, if any. Note that if the RestArgs contains a non-empty authentication token, this token was already checked by getRequest() and the request was rejected it the token didn't match.

Returns: A constant reference to the authentication token of the last received request.

◆ postContentType()

const UString & ts::RestServer::postContentType ( ) const

inline

Get the MIME type of the POST data, if specified.

Returns: A constant reference to the MIME type of the POST data or the empty string if unspecified.

◆ postData()

const ByteBlock & ts::RestServer::postData ( ) const

inline

Get the POST data from the request.

Returns: A constant reference to the POST data. Valid until the next request.

◆ getPostText()

void ts::RestServer::getPostText ( UString & data ) const

Get the POST data from the request in text format.

Parameters

[out] data The POST data.

◆ getPostJSON()

bool ts::RestServer::getPostJSON ( json::ValuePtr & value ) const

Get the POST data from the request in JSON format.

Parameters

[out] value The POST data.

Returns: True on success, false on error (typically invalid JSON data).

◆ addResponseHeader()

void ts::RestServer::addResponseHeader	(	const UString &	name,
		const UString &	value )

Add a header which will be sent with the response. If the same header already exists with another value, a new header is added.

Parameters

[in]	name	The header name.
[in]	value	The header value.

◆ replaceResponseHeader()

void ts::RestServer::replaceResponseHeader	(	const UString &	name,
		const UString &	value )

Replace a header which will be sent with the response. If the same header already exists with another value, it is replaced.

Parameters

[in]	name	The header name.
[in]	value	The header value.

◆ setResponse() [1/3]

void ts::RestServer::setResponse	(	const ByteBlock &	data,
		const UString &	mime_type = u"application/octet-stream" )

Store the data to be sent with the response.

Parameters

[in]	data	Returned data in binary form.
[in]	mime_type	Optional MIME type for these data.

◆ setResponse() [2/3]

void ts::RestServer::setResponse	(	const UString &	text,
		const UString &	mime_type = u"text/plain; charset=utf-8" )

Store the data to be sent with the response.

Parameters

[in]	text	Returned data in text format.
[in]	mime_type	Optional MIME type for these data.

◆ setResponse() [3/3]

void ts::RestServer::setResponse	(	const json::Value &	value,
		const UString &	mime_type = u"application/json" )

Store the data to be sent with the response.

Parameters

[in]	value	Returned data in JSON format.
[in]	mime_type	Optional MIME type for these data.

◆ sendResponse()

bool ts::RestServer::sendResponse	(	TCPConnection &	conn,
		int	http_status,
		bool	close )

Send the response to the last client request.

Parameters

[in,out]	conn	Client connection from which the request was received.
[in]	http_status	HTTP status code (200, 404, etc.)
[in]	close	If true, the connection is closed after sending the response.

Returns: True on success, false on error. In case of error, the connection is closed.

Member Data Documentation

◆ DEFAULT_SERVER_RECEIVE_TIMEOUT

cn::milliseconds ts::RestServer::DEFAULT_SERVER_RECEIVE_TIMEOUT = cn::milliseconds(3000)

staticconstexpr

Default receive timeout on the server side. A rest server reads an HTTP request. All lines of the requests are supposed to arrive at once. The server is not expected to wait. On the other hand, a hostile client may want to infinitely wait between request lines as part of a DDoS attack which paralyze the server. Therefore, we impose a strict timeout on reception.

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

tsRestServer.h

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ RestServer()

Member Function Documentation

◆ reset()

◆ getRequest()

◆ method()

◆ path()

◆ parameters()

◆ hasParameter()

◆ parameter()

◆ headers()

◆ header()

◆ token()

◆ postContentType()

◆ postData()

◆ getPostText()

◆ getPostJSON()

◆ addResponseHeader()

◆ replaceResponseHeader()

◆ setResponse() [1/3]

◆ setResponse() [2/3]

◆ setResponse() [3/3]

◆ sendResponse()

Member Data Documentation

◆ DEFAULT_SERVER_RECEIVE_TIMEOUT