http_box::http1::Parser provides the guts of the HTTP/1.x parsing capabilities.
Implementing http_box::http1::HttpHandler is how you provide a custom callback implementation. You can implement none, or as many functions as you want.
Each Parser instance can be tied to only one instance of HttpHandler. Often
times, it's easiest to provide an HttpHandler implementation for each type of
data being processed: head, chunked transfer-encoded, multipart, URL encoded. In
doing so, you will also have a Parser instance for each of your HttpHandler
implementations. This helps keep code clean at the cost of a bit more memory
being used by multiple Parser instances. This is not to say that you are
unable to write a single HttpHandler implementation that handles all methods
of parsing.
In a typical application, callbacks receive arguments that are complete pieces
of data. However, Parser parses data byte-by-byte, and because of this, it can
operate one byte at a time. Moreover, the data being parsed is often coming from
a network connection, and is received as incomplete segments of data. To stick
to the zero-copy philosophy, and to avoid buffering, callbacks are executed as
frequent as necessary.
Some callbacks are executed during multiple states. For example,
HttpHandler::on_header_name() is called during head parsing, chunked
transfer-encoded parsing, and multipart parsing. This is precisely why it makes
sense to split up HttpHandler implementation by method of parsing. Otherwise
you will be juggling too much state, and your implementation might end up
resembling Chet from the movie Weird Science when Lisa turns him into a steaming
pile of crap.
Sometimes multiple states need to work together to produce a single result. A good example of this is when headers are being parsed. The callback for the header name may be called multiple times in order to receive the full header name. And the same is true for the header value. It isn't until the header value is complete, that the header name/value pair can be collectively handled.
This is where the http_box::http1::State enum comes into play. You can use this to track the current state when a callback is executed. There is nothing mysterious about this enum. It's just a helper type with the objective of simplifying state tracking.