Kea: isc::http::HttpRequestParser Class Reference

| Kea 3.0.2-git

isc::http::HttpRequestParser Class Reference

A generic parser for HTTP requests. More...

`#include <request_parser.h>`

Inheritance diagram for isc::http::HttpRequestParser:
[legend]

## States supported by the HttpRequestParser.
static const int | RECEIVE_START_ST = SM_DERIVED_STATE_MIN + 1
| State indicating a beginning of parsing.
static const int | HTTP_METHOD_ST = SM_DERIVED_STATE_MIN + 2
| Parsing HTTP method, e.g. GET, POST etc.
static const int | HTTP_URI_ST = SM_DERIVED_STATE_MIN + 3
| Parsing URI.
static const int | HTTP_VERSION_H_ST = SM_DERIVED_STATE_MIN + 4
| Parsing letter "H" of "HTTP".
static const int | HTTP_VERSION_T1_ST = SM_DERIVED_STATE_MIN + 5
| Parsing first occurrence of "T" in "HTTP".
static const int | HTTP_VERSION_T2_ST = SM_DERIVED_STATE_MIN + 6
| Parsing second occurrence of "T" in "HTTP".
static const int | HTTP_VERSION_P_ST = SM_DERIVED_STATE_MIN + 7
| Parsing letter "P" in "HTTP".
static const int | HTTP_VERSION_SLASH_ST = SM_DERIVED_STATE_MIN + 8
| Parsing slash character in "HTTP/Y.X".
static const int | HTTP_VERSION_MAJOR_START_ST = SM_DERIVED_STATE_MIN + 9
| Starting to parse major HTTP version number.
static const int | HTTP_VERSION_MAJOR_ST = SM_DERIVED_STATE_MIN + 10
| Parsing major HTTP version number.
static const int | HTTP_VERSION_MINOR_START_ST = SM_DERIVED_STATE_MIN + 11
| Starting to parse minor HTTP version number.
static const int | HTTP_VERSION_MINOR_ST = SM_DERIVED_STATE_MIN + 12
| Parsing minor HTTP version number.
static const int | EXPECTING_NEW_LINE1_ST = SM_DERIVED_STATE_MIN + 13
| Parsing first new line (after HTTP version number).
static const int | HEADER_LINE_START_ST = SM_DERIVED_STATE_MIN + 14
| Starting to parse a header line.
static const int | HEADER_LWS_ST = SM_DERIVED_STATE_MIN + 15
| Parsing LWS (Linear White Space), i.e.
static const int | HEADER_NAME_ST = SM_DERIVED_STATE_MIN + 16
| Parsing header name.
static const int | SPACE_BEFORE_HEADER_VALUE_ST = SM_DERIVED_STATE_MIN + 17
| Parsing space before header value.
static const int | HEADER_VALUE_ST = SM_DERIVED_STATE_MIN + 18
| Parsing header value.
static const int | EXPECTING_NEW_LINE2_ST = SM_DERIVED_STATE_MIN + 19
| Expecting new line after parsing header value.
static const int | EXPECTING_NEW_LINE3_ST = SM_DERIVED_STATE_MIN + 20
| Expecting second new line marking end of HTTP headers.
static const int | HTTP_BODY_ST = SM_DERIVED_STATE_MIN + 21
| Parsing body of a HTTP message.
| HttpRequestParser (HttpRequest &request)
| Constructor.
void | initModel ()
| Initialize the state model for parsing.

## Additional Inherited Members
| HttpMessageParserBase (HttpMessage &message)
| Constructor.
void | poll ()
| Run the parser as long as the amount of data is sufficient.
bool | needData () const
| Returns true if the parser needs more data to continue.
bool | httpParseOk () const
| Returns true if the message has been parsed successfully.
std::string | getErrorMessage () const
| Returns error message.
void | postBuffer (const void *buf, const size_t buf_size)
| Provides more input data to the parser.
std::string | getBufferAsString (const size_t limit=0) const
| Returns parser's input buffer as string.
Public Member Functions inherited from isc::util::StateModel
| StateModel ()
| Constructor.
virtual | ~StateModel ()
| Destructor.
bool | didModelFail () const
| Returns whether or not the model failed.
void | endModel ()
| Conducts a normal transition to the end of the model.
std::string | getContextStr () const
| Convenience method which returns a string rendition of the current state and next event.
unsigned int | getCurrState () const
| Fetches the model's current state.
std::string | getEventLabel (const int event) const
| Fetches the label associated with an event value.
unsigned int | getLastEvent () const
| Fetches the model's last event.
unsigned int | getNextEvent () const
| Fetches the model's next event.
std::string | getPrevContextStr () const
| Convenience method which returns a string rendition of the previous state and last event.
unsigned int | getPrevState () const
| Fetches the model's previous state.
std::string | getStateLabel (const int state) const
| Fetches the label associated with an state value.
bool | isModelDone () const
| Returns whether or not the model has finished execution.
bool | isModelNew () const
| Returns whether or not the model is new.
bool | isModelPaused () const
| Returns whether or not the model is paused.
bool | isModelRunning () const
| Returns whether or not the model is running.
bool | isModelWaiting () const
| Returns whether or not the model is waiting.
void | nopStateHandler ()
| An empty state handler.
virtual void | runModel (unsigned int event)
| Processes events through the state model.
void | startModel (const int start_state)
| Begins execution of the model.
void | unpauseModel ()
| Unpauses state model.
static std::string | logFormatHttpMessage (const std::string &message, const size_t limit=0)
| Formats provided HTTP message for logging.
Static Public Attributes inherited from isc::http::HttpMessageParserBase
static const int | HTTP_PARSE_OK_ST = SM_DERIVED_STATE_MIN + 1000
| Parsing successfully completed.
static const int | HTTP_PARSE_FAILED_ST = SM_DERIVED_STATE_MIN + 1001
| Parsing failed.
static const int | DATA_READ_OK_EVT = SM_DERIVED_EVENT_MIN + 1
| Chunk of data successfully read and parsed.
static const int | NEED_MORE_DATA_EVT = SM_DERIVED_EVENT_MIN + 2
| Unable to proceed with parsing until new data is provided.
static const int | MORE_DATA_PROVIDED_EVT = SM_DERIVED_EVENT_MIN + 3
| New data provided and parsing should continue.
static const int | HTTP_PARSE_OK_EVT = SM_DERIVED_EVENT_MIN + 1000
| Parsing HTTP request successful.
static const int | HTTP_PARSE_FAILED_EVT = SM_DERIVED_EVENT_MIN + 1001
| Parsing HTTP request failed.
Static Public Attributes inherited from isc::util::StateModel
static const int | END_EVT = 2
| Event issued to end the model execution.
static const int | END_ST = 1
| Final state, all the state model has reached its conclusion.
static const int | FAIL_EVT = 3
| Event issued to abort the model execution.
static const int | NEW_ST = 0
| State that a state model is in immediately after construction.
static const int | NOP_EVT = 0
| Signifies that no event has occurred.
static const int | SM_DERIVED_EVENT_MIN = 11
| Value at which custom events in a derived class should begin.
static const int | SM_DERIVED_STATE_MIN = 11
| Value at which custom states in a derived class should begin.
static const int | START_EVT = 1
| Event issued to start the model execution.
virtual void | defineEvents () override
| Define events used by the parser.
virtual void | verifyEvents () override
| Verifies events used by the parser.
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.
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.
void | parseFailure (const std::string &error_msg)
| Transition parser to failure state.
virtual void | onModelFailure (const std::string &explanation) override
| A method called when parsing fails.
void | getNextFromBuffer (std::string &bytes, const size_t limit=1)
| Retrieves next bytes of data from the buffer.
void | invalidEventError (const std::string &handler_name, const unsigned int event)
| This method is called when invalid event occurred in a particular parser state.
void | parseEndedHandler ()
| Handler for HTTP_PARSE_OK_ST and HTTP_PARSE_FAILED_ST.
bool | popNextFromBuffer (std::string &next, const size_t limit=1)
| Tries to read next byte from buffer.
bool | isChar (const signed char c) const
| Checks if specified value is a character.
bool | isCtl (const signed char c) const
| Checks if specified value is a control value.
bool | isSpecial (const signed char c) const
| Checks if specified value is a special character.
Protected Member Functions inherited from isc::util::StateModel
void | abortModel (const std::string &explanation)
| Aborts model execution.
void | defineEvent (unsigned int value, const std::string &label)
| Adds an event value and associated label to the set of events.
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.
bool | doOnEntry ()
| Checks if on entry flag is true.
bool | doOnExit ()
| Checks if on exit flag is true.
const EventPtr & | getEvent (unsigned int value)
| Fetches the event referred to by value.
const StatePtr | getState (unsigned int value)
| Fetches the state referred to by value.
const StatePtr | getStateInternal (unsigned int value)
| Fetches the state referred to by value.
void | initDictionaries ()
| Initializes the event and state dictionaries.
void | postNextEvent (unsigned int event)
| Sets the next event to the given event value.
void | setState (unsigned int state)
| Sets the current state to the given state value.
void | transition (unsigned int state, unsigned int event)
| Sets up the model to transition into given state with a given event.
virtual void | verifyStates ()
| Validates the contents of the set of states.
HttpMessage & | message_
| Reference to the parsed HTTP message.
std::string | buffer_
| Internal buffer from which parser reads data.
size_t | buffer_pos_
| Position of the next character to read from the buffer.
std::string | error_message_
| Error message set by onModelFailure.

## Detailed Description

A generic parser for HTTP requests.

This class implements a parser for HTTP requests. The parser derives from HttpMessageParserBase class and implements its own state machine on top of it. The states of the parser reflect various parts of the HTTP message being parsed, e.g. parsing HTTP method, parsing URI, parsing message body etc. The descriptions of all parser states are provided below together with the constants defining these states.

The request parser validates the syntax of the received message as it progresses with parsing the data. Though, it doesn't interpret the received data until the whole message is parsed. In most cases we want to apply some restrictions on the message content, e.g. Kea Control API requires that commands are sent using HTTP POST, with a JSON command being carried in a message body. The parser doesn't verify if the message meets these restrictions until the whole message is parsed, i.e. stored in the HttpRequestContext object. This object is associated with a HttpRequest object (or its derivation). When the parsing is completed, the HttpRequest::create method is called to retrieve the data from the HttpRequestContext and interpret the data. In particular, the HttpRequest or its derivation checks if the received message meets desired restrictions.

Kea Control API uses PostHttpRequestJson class (which derives from the HttpRequest) to interpret received request. This class requires that the HTTP request uses POST method and contains the following headers:

- Content-Type: application/json,
- Content-Length

If any of these restrictions is not met in the received message, an exception will be thrown, thereby HttpRequestParser will fail parsing the message.

Definition at line 54 of file request_parser.h.

## Constructor & Destructor Documentation

## ◆ HttpRequestParser()

isc::http::HttpRequestParser::HttpRequestParser | ( | HttpRequest & | request | ) |
| explicit

Constructor.

Creates new instance of the parser.

Parameters

  request | Reference to the HttpRequest object or its derivation that should be used to validate the parsed request and to be used as a container for the parsed request.

Definition at line 40 of file request_parser.cc.

References isc::http::HttpMessageParserBase::HttpMessageParserBase().

Here is the call graph for this function:

## Member Function Documentation

## ◆ initModel()

void isc::http::HttpRequestParser::initModel | ( |  | ) |

Initialize the state model for parsing.

This method must be called before parsing the request, i.e. before calling HttpRequestParser::poll. It initializes dictionaries of states and events, and sets the initial model state to RECEIVE_START_ST.

Definition at line 46 of file request_parser.cc.

References isc::util::StateModel::initDictionaries(), isc::util::StateModel::postNextEvent(), RECEIVE_START_ST, isc::util::StateModel::setState(), and isc::util::StateModel::START_EVT.

Here is the call graph for this function:

## Member Data Documentation

## ◆ EXPECTING_NEW_LINE1_ST

const int isc::http::HttpRequestParser::EXPECTING_NEW_LINE1_ST = SM_DERIVED_STATE_MIN + 13
| static

Parsing first new line (after HTTP version number).

Definition at line 98 of file request_parser.h.

## ◆ EXPECTING_NEW_LINE2_ST

const int isc::http::HttpRequestParser::EXPECTING_NEW_LINE2_ST = SM_DERIVED_STATE_MIN + 19
| static

Expecting new line after parsing header value.

Definition at line 117 of file request_parser.h.

## ◆ EXPECTING_NEW_LINE3_ST

const int isc::http::HttpRequestParser::EXPECTING_NEW_LINE3_ST = SM_DERIVED_STATE_MIN + 20
| static

Expecting second new line marking end of HTTP headers.

Definition at line 120 of file request_parser.h.

## ◆ HEADER_LINE_START_ST

const int isc::http::HttpRequestParser::HEADER_LINE_START_ST = SM_DERIVED_STATE_MIN + 14
| static

Starting to parse a header line.

Definition at line 101 of file request_parser.h.

## ◆ HEADER_LWS_ST

const int isc::http::HttpRequestParser::HEADER_LWS_ST = SM_DERIVED_STATE_MIN + 15
| static

Parsing LWS (Linear White Space), i.e.

new line with a space or tab character while parsing a HTTP header.

Definition at line 105 of file request_parser.h.

## ◆ HEADER_NAME_ST

const int isc::http::HttpRequestParser::HEADER_NAME_ST = SM_DERIVED_STATE_MIN + 16
| static

Parsing header name.

Definition at line 108 of file request_parser.h.

## ◆ HEADER_VALUE_ST

const int isc::http::HttpRequestParser::HEADER_VALUE_ST = SM_DERIVED_STATE_MIN + 18
| static

Parsing header value.

Definition at line 114 of file request_parser.h.

## ◆ HTTP_BODY_ST

const int isc::http::HttpRequestParser::HTTP_BODY_ST = SM_DERIVED_STATE_MIN + 21
| static

Parsing body of a HTTP message.

Definition at line 123 of file request_parser.h.

## ◆ HTTP_METHOD_ST

const int isc::http::HttpRequestParser::HTTP_METHOD_ST = SM_DERIVED_STATE_MIN + 2
| static

Parsing HTTP method, e.g. GET, POST etc.

Definition at line 65 of file request_parser.h.

## ◆ HTTP_URI_ST

const int isc::http::HttpRequestParser::HTTP_URI_ST = SM_DERIVED_STATE_MIN + 3
| static

Parsing URI.

Definition at line 68 of file request_parser.h.

## ◆ HTTP_VERSION_H_ST

const int isc::http::HttpRequestParser::HTTP_VERSION_H_ST = SM_DERIVED_STATE_MIN + 4
| static

Parsing letter "H" of "HTTP".

Definition at line 71 of file request_parser.h.

## ◆ HTTP_VERSION_MAJOR_ST

const int isc::http::HttpRequestParser::HTTP_VERSION_MAJOR_ST = SM_DERIVED_STATE_MIN + 10
| static

Parsing major HTTP version number.

Definition at line 89 of file request_parser.h.

## ◆ HTTP_VERSION_MAJOR_START_ST

const int isc::http::HttpRequestParser::HTTP_VERSION_MAJOR_START_ST = SM_DERIVED_STATE_MIN + 9
| static

Starting to parse major HTTP version number.

Definition at line 86 of file request_parser.h.

## ◆ HTTP_VERSION_MINOR_ST

const int isc::http::HttpRequestParser::HTTP_VERSION_MINOR_ST = SM_DERIVED_STATE_MIN + 12
| static

Parsing minor HTTP version number.

Definition at line 95 of file request_parser.h.

## ◆ HTTP_VERSION_MINOR_START_ST

const int isc::http::HttpRequestParser::HTTP_VERSION_MINOR_START_ST = SM_DERIVED_STATE_MIN + 11
| static

Starting to parse minor HTTP version number.

Definition at line 92 of file request_parser.h.

## ◆ HTTP_VERSION_P_ST

const int isc::http::HttpRequestParser::HTTP_VERSION_P_ST = SM_DERIVED_STATE_MIN + 7
| static

Parsing letter "P" in "HTTP".

Definition at line 80 of file request_parser.h.

## ◆ HTTP_VERSION_SLASH_ST

const int isc::http::HttpRequestParser::HTTP_VERSION_SLASH_ST = SM_DERIVED_STATE_MIN + 8
| static

Parsing slash character in "HTTP/Y.X".

Definition at line 83 of file request_parser.h.

## ◆ HTTP_VERSION_T1_ST

const int isc::http::HttpRequestParser::HTTP_VERSION_T1_ST = SM_DERIVED_STATE_MIN + 5
| static

Parsing first occurrence of "T" in "HTTP".

Definition at line 74 of file request_parser.h.

## ◆ HTTP_VERSION_T2_ST

const int isc::http::HttpRequestParser::HTTP_VERSION_T2_ST = SM_DERIVED_STATE_MIN + 6
| static

Parsing second occurrence of "T" in "HTTP".

Definition at line 77 of file request_parser.h.

## ◆ RECEIVE_START_ST

const int isc::http::HttpRequestParser::RECEIVE_START_ST = SM_DERIVED_STATE_MIN + 1
| static

State indicating a beginning of parsing.

Definition at line 62 of file request_parser.h.

Referenced by initModel().

## ◆ SPACE_BEFORE_HEADER_VALUE_ST

const int isc::http::HttpRequestParser::SPACE_BEFORE_HEADER_VALUE_ST = SM_DERIVED_STATE_MIN + 17
| static

Parsing space before header value.

Definition at line 111 of file request_parser.h.

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

- request_parser.h
- request_parser.cc