Base class for the HTTP message parsers. More...

#include <http_message_parser_base.h>

Inheritance diagram for isc::http::HttpMessageParserBase:

Public Member Functions
	HttpMessageParserBase (HttpMessage &message)
	Constructor. More...

std::string	getBufferAsString (const size_t limit=0) const
	Returns parser's input buffer as string. More...

std::string	getErrorMessage () const
	Returns error message. More...

bool	httpParseOk () const
	Returns true if the message has been parsed successfully. More...

bool	needData () const
	Returns true if the parser needs more data to continue. More...

void	poll ()
	Run the parser as long as the amount of data is sufficient. More...

void	postBuffer (const void *buf, const size_t buf_size)
	Provides more input data to the parser. More...

Public Member Functions inherited from isc::util::StateModel
	StateModel ()
	Constructor. More...

virtual	~StateModel ()
	Destructor. More...

bool	didModelFail () const
	Returns whether or not the model failed. More...

void	endModel ()
	Conducts a normal transition to the end of the model. More...

std::string	getContextStr () const
	Convenience method which returns a string rendition of the current state and next event. More...

unsigned int	getCurrState () const
	Fetches the model's current state. More...

std::string	getEventLabel (const int event) const
	Fetches the label associated with an event value. More...

unsigned int	getLastEvent () const
	Fetches the model's last event. More...

unsigned int	getNextEvent () const
	Fetches the model's next event. More...

std::string	getPrevContextStr () const
	Convenience method which returns a string rendition of the previous state and last event. More...

unsigned int	getPrevState () const
	Fetches the model's previous state. More...

std::string	getStateLabel (const int state) const
	Fetches the label associated with an state value. More...

bool	isModelDone () const
	Returns whether or not the model has finished execution. More...

bool	isModelNew () const
	Returns whether or not the model is new. More...

bool	isModelPaused () const
	Returns whether or not the model is paused. More...

bool	isModelRunning () const
	Returns whether or not the model is running. More...

bool	isModelWaiting () const
	Returns whether or not the model is waiting. More...

void	nopStateHandler ()
	An empty state handler. More...

virtual void	runModel (unsigned int event)
	Processes events through the state model. More...

void	startModel (const int start_state)
	Begins execution of the model. More...

void	unpauseModel ()
	Unpauses state model. More...

Static Public Member Functions
static std::string	logFormatHttpMessage (const std::string &message, const size_t limit=0)
	Formats provided HTTP message for logging. More...

Static Public Attributes
States supported by the HttpMessageParserBase.
static const int	HTTP_PARSE_OK_ST = SM_DERIVED_STATE_MIN + 1000
	Parsing successfully completed. More...

static const int	HTTP_PARSE_FAILED_ST = SM_DERIVED_STATE_MIN + 1001
	Parsing failed. More...

Events used during HTTP message parsing.
static const int	DATA_READ_OK_EVT = SM_DERIVED_EVENT_MIN + 1
	Chunk of data successfully read and parsed. More...

static const int	NEED_MORE_DATA_EVT = SM_DERIVED_EVENT_MIN + 2
	Unable to proceed with parsing until new data is provided. More...

static const int	MORE_DATA_PROVIDED_EVT = SM_DERIVED_EVENT_MIN + 3
	New data provided and parsing should continue. More...

static const int	HTTP_PARSE_OK_EVT = SM_DERIVED_EVENT_MIN + 1000
	Parsing HTTP request successful. More...

static const int	HTTP_PARSE_FAILED_EVT = SM_DERIVED_EVENT_MIN + 1001
	Parsing HTTP request failed. More...

Static Public Attributes inherited from isc::util::StateModel
static const int	NEW_ST = 0
	State that a state model is in immediately after construction. More...

static const int	END_ST = 1
	Final state, all the state model has reached its conclusion. More...

static const int	SM_DERIVED_STATE_MIN = 11
	Value at which custom states in a derived class should begin. More...

static const int	NOP_EVT = 0
	Signifies that no event has occurred. More...

static const int	START_EVT = 1
	Event issued to start the model execution. More...

static const int	END_EVT = 2
	Event issued to end the model execution. More...

static const int	FAIL_EVT = 3
	Event issued to abort the model execution. More...

static const int	SM_DERIVED_EVENT_MIN = 11
	Value at which custom events in a derived class should begin. More...

Protected Member Functions
virtual void	defineEvents ()
	Define events used by the parser. More...

virtual void	defineStates ()
	Defines states of the parser. More...

void	getNextFromBuffer (std::string &bytes, const size_t limit=1)
	Retrieves next bytes of data from the buffer. More...

void	invalidEventError (const std::string &handler_name, const unsigned int event)
	This method is called when invalid event occurred in a particular parser state. More...

bool	isChar (const char c) const
	Checks if specified value is a character. More...

bool	isCtl (const char c) const
	Checks if specified value is a control value. More...

bool	isSpecial (const char c) const
	Checks if specified value is a special character. More...

virtual void	onModelFailure (const std::string &explanation)
	A method called when parsing fails. More...

void	parseEndedHandler ()
	Handler for HTTP_PARSE_OK_ST and HTTP_PARSE_FAILED_ST. More...

void	parseFailure (const std::string &error_msg)
	Transition parser to failure state. More...

bool	popNextFromBuffer (std::string &next, const size_t limit=1)
	Tries to read next byte from buffer. More...

void	stateWithMultiReadHandler (const std::string &handler_name, std::function< void(const std::string &)> after_read_logic)
	Generic parser handler which reads multiple bytes of data and parses it using specified callback function. More...

void	stateWithReadHandler (const std::string &handler_name, std::function< void(const char c)> after_read_logic)
	Generic parser handler which reads a single byte of data and parses it using specified callback function. More...

virtual void	verifyEvents ()
	Verifies events used by the parser. More...

Protected Member Functions inherited from isc::util::StateModel
void	abortModel (const std::string &explanation)
	Aborts model execution. More...

void	defineEvent (unsigned int value, const std::string &label)
	Adds an event value and associated label to the set of events. More...

void	defineState (unsigned int value, const std::string &label, StateHandler handler, const StatePausing &state_pausing=STATE_PAUSE_NEVER)
	Adds an state value and associated label to the set of states. More...

bool	doOnEntry ()
	Checks if on entry flag is true. More...

bool	doOnExit ()
	Checks if on exit flag is true. More...

const EventPtr &	getEvent (unsigned int value)
	Fetches the event referred to by value. More...

const StatePtr	getState (unsigned int value)
	Fetches the state referred to by value. More...

const StatePtr	getStateInternal (unsigned int value)
	Fetches the state referred to by value. More...

void	initDictionaries ()
	Initializes the event and state dictionaries. More...

void	postNextEvent (unsigned int event)
	Sets the next event to the given event value. More...

void	setState (unsigned int state)
	Sets the current state to the given state value. More...

void	transition (unsigned int state, unsigned int event)
	Sets up the model to transition into given state with a given event. More...

virtual void	verifyStates ()
	Validates the contents of the set of states. More...

Protected Attributes
std::string	buffer_
	Internal buffer from which parser reads data. More...

size_t	buffer_pos_
	Position of the next character to read from the buffer. More...

std::string	error_message_
	Error message set by onModelFailure. More...

HttpMessage &	message_
	Reference to the parsed HTTP message. More...

Detailed Description

Base class for the HTTP message parsers.

This is a base class for HttpRequestParser and HttpResponseParser classes. It provides common states, events and functionality for processing the received HTTP messages.

This class must not be used directly. Instead, an instance of the derived class should be used.

HTTP uses TCP as a transport which is asynchronous in nature, i.e. the HTTP message is received in chunks and multiple TCP connections can be established at the same time. Multiplexing between these connections requires providing a separate state machine per connection to "remember" the state of each transaction when the parser is waiting for asynchronous data to be delivered. While the parser is waiting for the data, it can parse requests received over other connections. This class provides means for parsing partial data received over the specific connection and interrupting data parsing to switch to a different context.

A new method HttpMessageParserBase::poll has been created to run the parser's state machine as long as there are unparsed data in the parser's internal buffer. This method returns control to the caller when the parser runs out of data in this buffer. The caller must feed the buffer by calling HttpMessageParserBase::postBuffer and then run HttpMessageParserBase::poll again.

In case, the caller provides more data than indicated by the "Content-Length" header the parser will return from poll() after parsing the data which constitute the HTTP request and not parse the extraneous data. The caller should test the HttpMessageParserBase::needData and HttpMessageParserBase::httpParseOk to determine whether parsing has completed.

The util::StateModel::runModel must not be used to run the parser state machine, thus it is made private method.

Definition at line 64 of file http_message_parser_base.h.

Constructor & Destructor Documentation

isc::http::HttpMessageParserBase::HttpMessageParserBase ( HttpMessage & message )

Constructor.

Parameters

message Reference to the HTTP request or response message.

Definition at line 28 of file http_message_parser_base.cc.

Member Function Documentation

void isc::http::HttpMessageParserBase::defineEvents ( )

protectedvirtual

Define events used by the parser.

Reimplemented from isc::util::StateModel.

Definition at line 101 of file http_message_parser_base.cc.

References DATA_READ_OK_EVT, isc::util::StateModel::defineEvent(), HTTP_PARSE_FAILED_EVT, HTTP_PARSE_OK_EVT, MORE_DATA_PROVIDED_EVT, and NEED_MORE_DATA_EVT.

Here is the call graph for this function:

void isc::http::HttpMessageParserBase::defineStates ( )

protectedvirtual

Defines states of the parser.

Reimplemented from isc::util::StateModel.

Definition at line 124 of file http_message_parser_base.cc.

References isc::util::StateModel::defineState(), HTTP_PARSE_FAILED_ST, HTTP_PARSE_OK_ST, and parseEndedHandler().

Here is the call graph for this function:

std::string isc::http::HttpMessageParserBase::getBufferAsString ( const size_t limit = 0 ) const

Returns parser's input buffer as string.

Parameters

limit Maximum length of the buffer to be output. If the limit is 0, the length of the output is unlimited.

Returns: Textual representation of the input buffer.

Definition at line 76 of file http_message_parser_base.cc.

References buffer_, and logFormatHttpMessage().

Here is the call graph for this function:

std::string isc::http::HttpMessageParserBase::getErrorMessage ( ) const

inline

Returns error message.

Definition at line 127 of file http_message_parser_base.h.

References error_message_.

void isc::http::HttpMessageParserBase::getNextFromBuffer	(	std::string &	bytes,
		const size_t	limit = `1`
	)

protected

Retrieves next bytes of data from the buffer.

During normal operation, when there is no more data in the buffer, the parser sets NEED_MORE_DATA_EVT as next event to signal the need for calling HttpMessageParserBase::postBuffer.

Parameters

[out]	bytes	Reference to the variable where read data should be stored.
	limit	Maximum number of bytes to be read.

Exceptions

HttpMessageParserBaseError If current event is already set to NEED_MORE_DATA_EVT or MORE_DATA_PROVIDED_EVT. In the former case, it indicates that the caller failed to provide new data using HttpMessageParserBase::postBuffer. The latter case is highly unlikely as it indicates that no new data were provided but the state of the parser was changed from NEED_MORE_DATA_EVT or the data were provided but the data buffer is empty. In both cases, it is an internal server error.

Definition at line 187 of file http_message_parser_base.cc.

References isc::util::StateModel::getNextEvent(), isc_throw, MORE_DATA_PROVIDED_EVT, NEED_MORE_DATA_EVT, popNextFromBuffer(), and isc::util::StateModel::postNextEvent().

Referenced by stateWithMultiReadHandler(), and stateWithReadHandler().

Here is the call graph for this function:

bool isc::http::HttpMessageParserBase::httpParseOk ( ) const

Returns true if the message has been parsed successfully.

Definition at line 55 of file http_message_parser_base.cc.

References isc::util::StateModel::END_EVT, isc::util::StateModel::getLastEvent(), isc::util::StateModel::getNextEvent(), and HTTP_PARSE_OK_EVT.

Here is the call graph for this function:

void isc::http::HttpMessageParserBase::invalidEventError	(	const std::string &	handler_name,
		const unsigned int	event
	)

protected

This method is called when invalid event occurred in a particular parser state.

This method simply throws HttpParseError informing about invalid event occurring for the particular parser state. The error message includes the name of the handler in which the exception has been thrown. It also includes the event which caused the exception.

Parameters

handler_name	Name of the handler in which the exception is thrown.
event	An event which caused the exception.

Exceptions

HttpMessageParserBaseError.

Definition at line 223 of file http_message_parser_base.cc.

References isc::util::StateModel::getEventLabel(), and isc_throw.

Referenced by parseEndedHandler(), stateWithMultiReadHandler(), and stateWithReadHandler().

Here is the call graph for this function:

bool isc::http::HttpMessageParserBase::isChar ( const char c ) const

protected

Checks if specified value is a character.

Returns: true, if specified value is a character.

Definition at line 264 of file http_message_parser_base.cc.

bool isc::http::HttpMessageParserBase::isCtl ( const char c ) const

protected

Checks if specified value is a control value.

Returns: true, if specified value is a control value.

Definition at line 270 of file http_message_parser_base.cc.

bool isc::http::HttpMessageParserBase::isSpecial ( const char c ) const

protected

Checks if specified value is a special character.

Returns: true, if specified value is a special character.

Definition at line 275 of file http_message_parser_base.cc.

std::string isc::http::HttpMessageParserBase::logFormatHttpMessage	(	const std::string &	message,
		const size_t	limit = `0`
	)

static

Formats provided HTTP message for logging.

This method is useful in cases when there is a need to log a HTTP message (as text). If the limit is specified the message output is limited to this size. If the limit is set to 0 (default), the whole message is output. The getBufferAsString method calls this method internally.

Parameters

message	HTTP message to be logged.
limit	Maximum length of the buffer to be output. If the limit is 0, the length of the output is unlimited.

Returns: HTTP message formatted for logging.

Definition at line 82 of file http_message_parser_base.cc.

Referenced by getBufferAsString(), and isc::http::HttpConnection::socketReadCallback().

bool isc::http::HttpMessageParserBase::needData ( ) const

Returns true if the parser needs more data to continue.

Returns: true if the next event is NEED_MORE_DATA_EVT.

Definition at line 49 of file http_message_parser_base.cc.

References isc::util::StateModel::getNextEvent(), NEED_MORE_DATA_EVT, and isc::util::StateModel::START_EVT.

Here is the call graph for this function:

void isc::http::HttpMessageParserBase::onModelFailure ( const std::string & explanation )

protectedvirtual

A method called when parsing fails.

Parameters

explanation Error message explaining the reason for parsing failure.

Reimplemented from isc::util::StateModel.

Definition at line 180 of file http_message_parser_base.cc.

References error_message_.

void isc::http::HttpMessageParserBase::parseEndedHandler ( )

protected

Handler for HTTP_PARSE_OK_ST and HTTP_PARSE_FAILED_ST.

If parsing is successful, it calls HttpRequest::create to validate the HTTP request. In both cases it transitions the parser to the END_ST.

Definition at line 230 of file http_message_parser_base.cc.

References isc::util::StateModel::abortModel(), isc::util::StateModel::END_EVT, isc::util::StateModel::END_ST, isc::http::HttpMessage::finalize(), isc::util::StateModel::getNextEvent(), HTTP_PARSE_FAILED_EVT, HTTP_PARSE_OK_EVT, invalidEventError(), message_, and isc::util::StateModel::transition().

Referenced by defineStates().

Here is the call graph for this function:

void isc::http::HttpMessageParserBase::parseFailure ( const std::string & error_msg )

protected

Transition parser to failure state.

This method transitions the parser to HTTP_PARSE_FAILED_ST and sets next event to HTTP_PARSE_FAILED_EVT.

Parameters

error_msg Error message explaining the failure.

Definition at line 174 of file http_message_parser_base.cc.

References error_message_, isc::util::StateModel::getContextStr(), HTTP_PARSE_FAILED_EVT, HTTP_PARSE_FAILED_ST, and isc::util::StateModel::transition().

Here is the call graph for this function:

void isc::http::HttpMessageParserBase::poll ( )

Run the parser as long as the amount of data is sufficient.

The data to be parsed should be provided by calling HttpMessageParserBase::postBuffer. When the parser reaches the end of the data buffer the HttpMessageParserBase::poll sets the next event to NEED_MORE_DATA_EVT and returns. The caller should then invoke HttpMessageParserBase::postBuffer again to provide more data to the parser, and call HttpMessageParserBase::poll to continue parsing.

This method also returns when parsing completes or fails. The last event can be examined to check whether parsing was successful or not.

Definition at line 34 of file http_message_parser_base.cc.

References isc::util::StateModel::abortModel(), isc::util::StateModel::getCurrState(), isc::util::StateModel::getNextEvent(), isc::util::StateModel::getState(), isc::util::StateModel::isModelDone(), NEED_MORE_DATA_EVT, and isc::util::StateModel::NOP_EVT.

Here is the call graph for this function:

bool isc::http::HttpMessageParserBase::popNextFromBuffer	(	std::string &	next,
		const size_t	limit = `1`
	)

protected

Tries to read next byte from buffer.

Parameters

[out]	next	A reference to the variable where read data should be stored.
	limit	Maximum number of characters to be read.

Returns: true if data was successfully read, false otherwise.

Definition at line 246 of file http_message_parser_base.cc.

References buffer_, and buffer_pos_.

Referenced by getNextFromBuffer().

void isc::http::HttpMessageParserBase::postBuffer	(	const void *	buf,
		const size_t	buf_size
	)

Provides more input data to the parser.

This method must be called prior to calling HttpMessageParserBase::poll to deliver data to be parsed. HTTP messages are received over TCP and multiple reads may be necessary to retrieve the entire request. There is no need to accumulate the entire request to start parsing it. A chunk of data can be provided to the parser using this method and parsed right away using HttpMessageParserBase::poll.

Parameters

buf	A pointer to the buffer holding the data.
buf_size	Size of the data within the buffer.

Definition at line 61 of file http_message_parser_base.cc.

References buffer_, isc::util::StateModel::getCurrState(), isc::util::StateModel::getNextEvent(), MORE_DATA_PROVIDED_EVT, NEED_MORE_DATA_EVT, and isc::util::StateModel::transition().

Here is the call graph for this function:

void isc::http::HttpMessageParserBase::stateWithMultiReadHandler	(	const std::string &	handler_name,
		std::function< void(const std::string &)>	after_read_logic
	)

protected

Generic parser handler which reads multiple bytes of data and parses it using specified callback function.

This handler is mostly used for parsing body of the HTTP message, where we don't validate the content read. Reading multiple bytes is the most efficient. If there is no more data it simply returns. Otherwise, if the next event is DATA_READ_OK_EVT or MORE_DATA_PROVIDED_EVT, it calls the provided callback function to parse the new byte of data.

Parameters

handler_name	Name of the handler function which called this method.
after_read_logic	Callback function to parse multiple bytes of data. This callback function implements state specific logic.

Exceptions

HttpRequestParserError when invalid event occurred.

Definition at line 155 of file http_message_parser_base.cc.

References DATA_READ_OK_EVT, isc::util::StateModel::getNextEvent(), getNextFromBuffer(), invalidEventError(), MORE_DATA_PROVIDED_EVT, and NEED_MORE_DATA_EVT.

Here is the call graph for this function:

void isc::http::HttpMessageParserBase::stateWithReadHandler	(	const std::string &	handler_name,
		std::function< void(const char c)>	after_read_logic
	)

protected

Generic parser handler which reads a single byte of data and parses it using specified callback function.

This generic handler is used in most of the parser states to parse a single byte of input data. If there is no more data it simply returns. Otherwise, if the next event is DATA_READ_OK_EVT or MORE_DATA_PROVIDED_EVT, it calls the provided callback function to parse the new byte of data. For all other states it throws an exception.

Parameters

handler_name	Name of the handler function which called this method.
after_read_logic	Callback function to parse the byte of data. This callback function implements state specific logic.

Exceptions

HttpRequestParserError when invalid event occurred.

Definition at line 136 of file http_message_parser_base.cc.

References DATA_READ_OK_EVT, isc::util::StateModel::getNextEvent(), getNextFromBuffer(), invalidEventError(), MORE_DATA_PROVIDED_EVT, and NEED_MORE_DATA_EVT.

Here is the call graph for this function: