The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Protocol::HTTP::ResponseParser - HTTP response parser

SYNOPSIS

    use Protocol::HTTP::ResponseParser;

    my $parser = Protocol::HTTP::ResponseParser->new;
    $parser->set_context_request(Protocol::HTTP::Request->new({method => METHOD_GET}));
    my $buffer =
        "HTTP/1.0 200 OK\r\n".
        "Host: host1\r\n".
        "Content-Length: 0\r\n".
        "\r\n";

    my ($res, $state, $pos, $err) = $parser->parse($buffer);
    if ($err) {
        die "http error: $err";
    }
    
    if ($state < Protocol::HTTP::Message::STATE_DONE) {
        # wait for more data
    }
    
    process($req);

DESCRIPTION

This class represents client HTTP request parser. Parser is incremental so that you don't need to pass the whole http packet at once.

Parser is an FSM so it's really fast.

The context request should be set to help parser on validation, for example if the request method was HEAD and the response contains chunks, this is violation of HTTP protocol and error is emitted, despite the fact that the response by itself is valid.

METHODS

new()

Constructs new response parser instance.

set_context_request($request)

Sets context request for which response will be parsed. This property is automatically cleared after each sucessfull parsing (STATE_DONE) so that you need to set next context request before you start parsing next response.

context_request()

Returns current context request.

parse($buffer)

parse_shift($buffer)

    $parser->set_context_request($request);
    my ($res, $state, $pos, $err) = $parser->parse($buffer);

The behaviour is the same as for request parser, see Protocol::HTTP::RequestParser.

You must set a context request via set_context_request() after each successfull parsing (STATE_DONE) and before you start parsing next response.

reset()

Resets internal parser state, so it is ready to parse new responses.

Parser automatically resets itself after each successfully parsed message, so you only need to call this method if you plan to re-use parser after errors, or you decided to stop parsing not yet fully parsed message and begin parsing another one.

reset() drops current context request as well, so that you need to set another context request before you start parsing next response.

eof()

    my ($res, $state, $err) = $parser->eof();
    

Tells the parser that peer (server) has closed the connection and no more data should be awaited.

The result may be either success or fail.

If we were parsing a message without Content-Length header and not chunked (that is "read-body-until-eof" message), and we were in "parsing body" state, then the result would be success, $state == STATE_DONE, $err is absent, and $res would contain a complete Protocol::HTTP::Response object.

If we were not expecting a response (i.e. we were between "request-response" series: nothing was parsing at the moment, and no context request was set), the result would be success, $state == STATE_HEADERS (initial state), $err is absent and $res would contain an empty Protocol::HTTP::Response object.

Otherwise the result is a fail, $state == STATE_ERROR, $err == Protocol::HTTP::Error::unexpected_eof and $res will contain a non-complete Protocol::HTTP::Response object.

SEE ALSO

Protocol::HTTP

Protocol::HTTP::Message

Protocol::HTTP::Request

Protocol::HTTP::Response