Kourier::HttpBroker Class Reference

The HttpBroker class acts as a broker for HTTP-based communication. You can use it to receive the remaining request body and to write the HTTP response. More...

Public Types
enum class	HttpStatusCode {   Continue = 0 ,   SwitchingProtocols ,   OK ,   Created ,   Accepted ,   NonAuthoritativeInformation ,   NoContent ,   ResetContent ,   PartialContent ,   MultipleChoices ,   MovedPermanently ,   Found ,   SeeOther ,   NotModified ,   UseProxy ,   TemporaryRedirect ,   PermanentRedirect ,   BadRequest ,   Unauthorized ,   PaymentRequired ,   Forbidden ,   NotFound ,   MethodNotAllowed ,   NotAcceptable ,   ProxyAuthenticationRequired ,   RequestTimeout ,   Conflict ,   Gone ,   LengthRequired ,   PreconditionFailed ,   ContentTooLarge ,   URITooLong ,   UnsupportedMediaType ,   RangeNotSatisfiable ,   ExpectationFailed ,   MisdirectedRequest ,   UnprocessableContent ,   UpgradeRequired ,   InternalServerError ,   NotImplemented ,   BadGateway ,   ServiceUnavailable ,   GatewayTimeout ,   HTTPVersionNotSupported }
	This enum describes the status for HTTP responses. More...

Signals
void	receivedBodyData (std::string_view data, bool isLastPart)
void	sentData (size_t count)

Public Member Functions
	~HttpBroker () override=default
size_t	bytesToSend () const
void	closeConnectionAfterResponding ()
bool	hasTrailer (std::string_view name) const
bool	hasTrailers () const
void	setQObject (QObject *pObject)
std::string_view	trailer (std::string_view name, int pos=1) const
size_t	trailerCount (std::string_view name) const
size_t	trailersCount () const
void	writeChunk (std::string_view data)
void	writeChunkedResponse (HttpStatusCode statusCode, const std::vector< std::pair< std::string, std::string > > &headers, const std::vector< std::string > &expectedTrailerNames)
void	writeChunkedResponse (HttpStatusCode statusCode=HttpStatusCode::OK, std::initializer_list< std::pair< std::string, std::string > > headers={}, std::initializer_list< std::string > expectedTrailerNames={})
void	writeChunkedResponse (std::string_view mimeType, HttpStatusCode statusCode, const std::vector< std::pair< std::string, std::string > > &headers, const std::vector< std::string > &expectedTrailerNames)
void	writeChunkedResponse (std::string_view mimeType, HttpStatusCode statusCode=HttpStatusCode::OK, std::initializer_list< std::pair< std::string, std::string > > headers={}, std::initializer_list< std::string > expectedTrailerNames={})
void	writeLastChunk (const std::vector< std::pair< std::string, std::string > > &trailers)
void	writeLastChunk (std::initializer_list< std::pair< std::string, std::string > > trailers={})
void	writeResponse (HttpStatusCode statusCode, const std::vector< std::pair< std::string, std::string > > &headers)
void	writeResponse (HttpStatusCode statusCode=HttpStatusCode::OK, std::initializer_list< std::pair< std::string, std::string > > headers={})
void	writeResponse (std::string_view body, HttpStatusCode statusCode, const std::vector< std::pair< std::string, std::string > > &headers)
void	writeResponse (std::string_view body, HttpStatusCode statusCode=HttpStatusCode::OK, std::initializer_list< std::pair< std::string, std::string > > headers={})
void	writeResponse (std::string_view body, std::string_view mimeType, HttpStatusCode statusCode, const std::vector< std::pair< std::string, std::string > > &headers)
void	writeResponse (std::string_view body, std::string_view mimeType, HttpStatusCode statusCode=HttpStatusCode::OK, std::initializer_list< std::pair< std::string, std::string > > headers={})

Detailed Description

The HttpBroker class acts as a broker for HTTP-based communication. You can use it to receive the remaining request body and to write the HTTP response.

HttpBroker cannot be created by you. It is created by HttpServer and passed as an argument to the mapped handler. You can call HttpServer::addRoute to map handlers to HTTP methods and paths.

HttpServer calls the mapped handler right after it parses the request header block. If the request has a body that is not chunked, the server processes all body data available when the header block was fully parsed. You can use the HttpBroker instance that the server passes as an argument to the mapped handler to write the response and to receive any pending body data for the request.

Unlike the HttpRequest argument, which you can only use inside the handler, the HttpBroker argument can be used until you finish writing the response. For example, you may request a NoSQL database and only write the response when you receive the queried data. However, to use the HttpBroker argument outside the handler function, you must call setQObject() with a valid object responsible for processing the remaining body data and writing the HTTP response. HttpServer closes the connection if the called handler neither writes a complete response nor sets an object to write it later after the handler returns.

Member Enumeration Documentation

HttpStatusCode

enum class Kourier::HttpBroker::HttpStatusCode

strong

This enum describes the status for HTTP responses.

Enumerator
Continue	100 Continue
SwitchingProtocols	101 SwitchingProtocols
OK	200 OK
Created	201 Created
Accepted	202 Accepted
NonAuthoritativeInformation	203 Non Authoritative Information
NoContent	204 No Content
ResetContent	205 Reset Content
PartialContent	206 Partial Content
MultipleChoices	300 Multiple Choices
MovedPermanently	301 Moved Permanently
Found	302 Found
SeeOther	303 See Other
NotModified	304 Not Modified
UseProxy	305 Use Proxy
TemporaryRedirect	307 Temporary Redirect
PermanentRedirect	308 Permanent Redirect
BadRequest	400 Bad Request
Unauthorized	401 Unauthorized
PaymentRequired	402 Payment Required
Forbidden	403 Forbidden
NotFound	404 Not Found
MethodNotAllowed	405 Method Not Allowed
NotAcceptable	406 Not Acceptable
ProxyAuthenticationRequired	407 Proxy Authentication Required
RequestTimeout	408 Request Timeout
Conflict	409 Conflict
Gone	410 Gone
LengthRequired	411 Length Required
PreconditionFailed	412 Precondition Failed
ContentTooLarge	413 Content Too Large
URITooLong	414 URI Too Long
UnsupportedMediaType	415 Unsupported Media Type
RangeNotSatisfiable	416 Range Not Satisfiable
ExpectationFailed	417 Expectation Failed
MisdirectedRequest	421 Misdirected Request
UnprocessableContent	422 Unprocessable Content
UpgradeRequired	426 Upgrade Required
InternalServerError	500 Internal Server Error
NotImplemented	501 Not Implemented
BadGateway	502 Bad Gateway
ServiceUnavailable	503 Service Unavailable
GatewayTimeout	504 Gateway Timeout
HTTPVersionNotSupported	505 HTTP Version Not Supported

Constructor & Destructor Documentation

~HttpBroker()

Kourier::HttpBroker::~HttpBroker ( )

overridedefault

Destroys the object.

Member Function Documentation

bytesToSend()

size_t Kourier::HttpBroker::bytesToSend

(

)

const

Returns the bytes pending to be sent to the peer. You can use sentData() and bytesToSend() to write well-behaved peers that write data according to the peer's capacity to process it.

closeConnectionAfterResponding()

void Kourier::HttpBroker::closeConnectionAfterResponding

(

)

Makes the broker write the Connection: close field line on the response header block and close the connection after sending it to the peer. This method will be applied to the next response you write. For example, if you call this method in the middle of writing a chunked response, it will take effect on the next written response.

hasTrailer()

bool Kourier::HttpBroker::hasTrailer

(

std::string_view

name

)

const

Returns true if the request trailer section contains at least one field line with the given name.

hasTrailers()

bool Kourier::HttpBroker::hasTrailers

(

)

const

Returns true if the last chunk of the request has a trailer section.

receivedBodyData

Kourier::HttpBroker::receivedBodyData ( std::string_view  data, bool  isLastPart  )

signal

HttpBroker emits this signal when it receives pending data for the request body. HttpBroker sets isLastPart to true if the request body has been fully received. For chunked requests, the last chunk is empty. Thus, data will be empty for chunked requests when isLastPart is true. In this case, you can call hasTrailers() to know if the peer sent a trailer section after the last chunk of the request.

sentData

Kourier::HttpBroker::sentData ( size_t  count )

signal

HttpBroker emits this signal whenever data is sent, at the socket level, to the connected peer. You can use this signal and bytesToSend() to write well-behaved peers that write data according to the connected peer's capacity to process them.

setQObject()

void Kourier::HttpBroker::setQObject

(

QObject *

pObject

)

Sets the object responsible for receiving any pending body data for the request and writing the response. HttpBroker takes ownership of pObject and deletes it after the set object finishes writing the response.

You should set a non-null object if you want to receive any pending body data and write a response after the handler returns. HttpServer closes the connection if the called handler does not write the response and does not set any object responsible for doing so.

trailer()

std::string_view Kourier::HttpBroker::trailer	(	std::string_view	name,
		int	pos = 1
	)		const

Returns the field line's field value with the given name at position pos in the request trailer section. Position is relative to field lines having the same name.

trailerCount()

size_t Kourier::HttpBroker::trailerCount

(

std::string_view

name

)

const

Returns the number of field lines with the given name in the request trailer section.

trailersCount()

size_t Kourier::HttpBroker::trailersCount

(

)

const

Returns the number of field lines in the request trailer section.

writeChunk()

void Kourier::HttpBroker::writeChunk

(

std::string_view

data

)

Writes data chunk to the peer if you initiated a chunked response by calling writeChunkedResponse() and if data is not empty. You can call writeLastChunk() to write the last chunk and finish writing the chunked response.

writeChunkedResponse() [1/4]

void Kourier::HttpBroker::writeChunkedResponse	(	HttpStatusCode	statusCode,
		const std::vector< std::pair< std::string, std::string > > &	headers,
		const std::vector< std::string > &	expectedTrailerNames
	)

Writes status line and header block of the chunked response with statusCode and headers to the peer. HttpBroker writes the server, date, and transfer encoding headers. If expectedTrailerNames is not empty, HttpBroker writes to the header block a field line named Trailer containing as value all names given in expectedTrailerNames. HttpBroker writes the Connection: close field line to the header block if you called closeConnectionAfterResponding() before calling this method.

After calling this method to initiate a chunked response, you can call writeChunk() to write non-empty chunks and writeLastChunk() to write the last chunk of the response.

If you call this method after writing the response, HttpBroker returns without writing another response. If you call this method while writing a chunked response, HttpBroker finishes the current chunked response and returns without writing another one.

writeChunkedResponse() [2/4]

void Kourier::HttpBroker::writeChunkedResponse	(	HttpStatusCode	statusCode = HttpStatusCode::OK,
		std::initializer_list< std::pair< std::string, std::string > >	headers = {},
		std::initializer_list< std::string >	expectedTrailerNames = {}
	)

Writes status line and header block of the chunked response with statusCode and headers to the peer. HttpBroker writes the server, date, and transfer encoding headers. If expectedTrailerNames is not empty, HttpBroker writes to the header block a field line named Trailer containing as value all names given in expectedTrailerNames. HttpBroker writes the Connection: close field line to the header block if you called closeConnectionAfterResponding() before calling this method.

After calling this method to initiate a chunked response, you can call writeChunk() to write non-empty chunks and writeLastChunk() to write the last chunk of the response.

If you call this method after writing the response, HttpBroker returns without writing another response. If you call this method while writing a chunked response, HttpBroker finishes the current chunked response and returns without writing another one.

writeChunkedResponse() [3/4]

void Kourier::HttpBroker::writeChunkedResponse	(	std::string_view	mimeType,
		HttpStatusCode	statusCode,
		const std::vector< std::pair< std::string, std::string > > &	headers,
		const std::vector< std::string > &	expectedTrailerNames
	)

Writes status line and header block of the chunked response with statusCode and headers to the peer. HttpBroker writes the server, date, and transfer encoding headers. If expectedTrailerNames is not empty, HttpBroker writes to the header block a field line named Trailer containing as value all names given in expectedTrailerNames. If mimeType is not empty, HttpBroker writes the Content-Type header. HttpBroker writes the Connection: close field line to the header block if you called closeConnectionAfterResponding() before calling this method.

After calling this method to initiate a chunked response, you can call writeChunk() to write non-empty chunks and writeLastChunk() to write the last chunk of the response.

If you call this method after writing the response, HttpBroker returns without writing another response. If you call this method while writing a chunked response, HttpBroker finishes the current chunked response and returns without writing another one.

writeChunkedResponse() [4/4]

void Kourier::HttpBroker::writeChunkedResponse	(	std::string_view	mimeType,
		HttpStatusCode	statusCode = HttpStatusCode::OK,
		std::initializer_list< std::pair< std::string, std::string > >	headers = {},
		std::initializer_list< std::string >	expectedTrailerNames = {}
	)

Writes status line and header block of the chunked response with statusCode and headers to the peer. HttpBroker writes the server, date, and transfer encoding headers. If expectedTrailerNames is not empty, HttpBroker writes to the header block a field line named Trailer containing as value all names given in expectedTrailerNames. If mimeType is not empty, HttpBroker writes the Content-Type header. HttpBroker writes the Connection: close field line to the header block if you called closeConnectionAfterResponding() before calling this method.

After calling this method to initiate a chunked response, you can call writeChunk() to write non-empty chunks and writeLastChunk() to write the last chunk of the response.

If you call this method after writing the response, HttpBroker returns without writing another response. If you call this method while writing a chunked response, HttpBroker finishes the current chunked response and returns without writing another one.

writeLastChunk() [1/2]

void Kourier::HttpBroker::writeLastChunk

(

const std::vector< std::pair< std::string, std::string > > &

trailers

)

Writes the last chunk to the peer if you initiated a chunked response by calling writeChunkedResponse(). If trailers is not empty, HttpBroker writes a trailer section after the last chunk.

writeLastChunk() [2/2]

void Kourier::HttpBroker::writeLastChunk

(

std::initializer_list< std::pair< std::string, std::string > >

trailers = {}

)

Writes the last chunk to the peer if you initiated a chunked response by calling writeChunkedResponse(). If trailers is not empty, HttpBroker writes a trailer section after the last chunk.

writeResponse() [1/6]

void Kourier::HttpBroker::writeResponse	(	HttpStatusCode	statusCode,
		const std::vector< std::pair< std::string, std::string > > &	headers
	)

Writes response with statusCode and headers to the peer. HttpBroker writes the server, date, and content length headers. HttpBroker writes the Connection: close field line to the header block if you called closeConnectionAfterResponding() before calling this method.

If you call this method after writing the response, HttpBroker returns without writing another response. If you call this method while writing a chunked response, HttpBroker finishes the current chunked response and returns without writing another one.

writeResponse() [2/6]

void Kourier::HttpBroker::writeResponse	(	HttpStatusCode	statusCode = HttpStatusCode::OK,
		std::initializer_list< std::pair< std::string, std::string > >	headers = {}
	)

Writes response with statusCode and headers to the peer. HttpBroker writes the server, date, and content length headers. HttpBroker writes the Connection: close field line to the header block if you called closeConnectionAfterResponding() before calling this method.

If you call this method after writing the response, HttpBroker returns without writing another response. If you call this method while writing a chunked response, HttpBroker finishes the current chunked response and returns without writing another one.

writeResponse() [3/6]

void Kourier::HttpBroker::writeResponse	(	std::string_view	body,
		HttpStatusCode	statusCode,
		const std::vector< std::pair< std::string, std::string > > &	headers
	)

Writes a response with statusCode, headers, and body to the peer. HttpBroker writes the server, date, and content-length headers. HttpBroker writes, as the Content-Length field line's field value, the size of the body if it is not empty, or zero otherwise. HttpBroker writes the Connection: close field line to the header block if you called closeConnectionAfterResponding() before calling this method.

If you call this method after writing the response, HttpBroker returns without writing another response. If you call this method while writing a chunked response, HttpBroker finishes the current chunked response and returns without writing another one.

writeResponse() [4/6]

void Kourier::HttpBroker::writeResponse	(	std::string_view	body,
		HttpStatusCode	statusCode = HttpStatusCode::OK,
		std::initializer_list< std::pair< std::string, std::string > >	headers = {}
	)

Writes a response with statusCode, headers, and body to the peer. HttpBroker writes the server, date, and content-length headers. HttpBroker writes, as the Content-Length field line's field value, the size of the body if it is not empty, or zero otherwise. HttpBroker writes the Connection: close field line to the header block if you called closeConnectionAfterResponding() before calling this method.

If you call this method after writing the response, HttpBroker returns without writing another response. If you call this method while writing a chunked response, HttpBroker finishes the current chunked response and returns without writing another one.

writeResponse() [5/6]

void Kourier::HttpBroker::writeResponse	(	std::string_view	body,
		std::string_view	mimeType,
		HttpStatusCode	statusCode,
		const std::vector< std::pair< std::string, std::string > > &	headers
	)

Writes a response with statusCode, headers, and body to the peer. HttpBroker writes the server, date, and content-length headers. HttpBroker writes, as the Content-Length field line's field value, the size of the body if it is not empty, or zero otherwise. If mimeType is not empty, HttpBroker writes the Content-Type header. HttpBroker writes the Connection: close field line to the header block if you called closeConnectionAfterResponding() before calling this method.

If you call this method after writing the response, HttpBroker returns without writing another response. If you call this method while writing a chunked response, HttpBroker finishes the current chunked response and returns without writing another one.

writeResponse() [6/6]

void Kourier::HttpBroker::writeResponse	(	std::string_view	body,
		std::string_view	mimeType,
		HttpStatusCode	statusCode = HttpStatusCode::OK,
		std::initializer_list< std::pair< std::string, std::string > >	headers = {}
	)

Writes a response with statusCode, headers, and body to the peer. HttpBroker writes the server, date, and content-length headers. HttpBroker writes, as the Content-Length field line's field value, the size of the body if it is not empty, or zero otherwise. If mimeType is not empty, HttpBroker writes the Content-Type header. HttpBroker writes the Connection: close field line to the header block if you called closeConnectionAfterResponding() before calling this method.

If you call this method after writing the response, HttpBroker returns without writing another response. If you call this method while writing a chunked response, HttpBroker finishes the current chunked response and returns without writing another one.