NAME

Net::Inspect::L7::HTTP - guesses and handles HTTP traffic

SYNOPSIS

 my $req = Net::Inspect::L7::HTTP::Request::Simple->new(..);
 my $http = Net::Inspect::L7::HTTP->new($req);
 my $guess = Net::Inspect::L5::GuessProtocol->new;
 $guess->attach($http);
 ...

DESCRIPTION

This class extracts HTTP requests from TCP connections. It provides all hooks required for Net::Inspect::L4::TCP and is usually used together with it. It provides the guess_protocol hook so it can be used with Net::Inspect::L5::GuessProtocol.

Attached flow is usually a Net::Inspect::L7::HTTP::Request::* object.

Hooks provided:

guess_protocol($guess,$dir,$data,$eof,$time,$meta)

new_connection($meta) - this returns an object for the connection

$connection->in($dir,$data,$eof,$time)

$data are the data as string.

In some cases $data can be <[ 'gap' = $len ]>>, e.g. only the information, that there would be $len bytes of data w/o submitting the data. These should only be submitted in request and response bodies and only if the attached layer can handle these gaps in the in_request_body and in_response_body methods.

Gaps on other places are not allowed, because all other data are needed for interpreting the placement of request, response and data inside the connection.

$connection->fatal($reason,$dir,$time)

Hooks called:

new_request(\%meta,$conn)

This should return an request object. The reference to the connection object is given in case the request object likes to call fatal to end the connection.

The function should not get hold of $conn, e.g. only store a weak reference, otherwise memory might leak.

$request->in_request_header($header,$time)

Called when the full request header is read. $header is the string of the header.

$request->in_response_header($header,$time)

Called when the full response header is read. $header is the string of the header.

$request->in_request_body($data,$eof,$time)

Called for a chunk of data of the request body. $eof is true if this is the last chunk. If no request body is given it will be once called with '' as data, except for CONNECT, Upgrade etc where there cannot be a body.

$data can be <[ 'gap' = $len ]>> if the input to this layer were gaps.

$request->in_response_body($data,$eof,$time)

Called for a chunk of data of the response body. $eof is true if this is the last chunk. It will be called with data '' and eof true if no body is given or if the last chunk of chunked encoding was found, except for CONNECT, Upgrade etc where there cannot be a body.

$data can be <[ 'gap' = $len ]>> if the input to this layer were gaps.

$request->in_chunk_header($header,$time)

will be called with the chunk header for chunked encoding. Usually one is not interested in the chunk framing, only in the content so that this method will be empty. Will be called before the chunk data.

$request->in_chunk_trailer($trailer,$time)

will be called with the chunk trailer for chunked encoding. Usually one is not interested in the chunk framing, only in the content so that this method will be empty. Will be called after in_response_body got called with eof true.

$request->in_data($dir,$data,$eof,$time)

Will be called for any data after successful CONNECT or Upgrade, Websockets... $dir is 0 for data from client, 1 for data from server.

$request->fatal($reason,$dir,$time)

will be called on fatal errors, mostly protocol iregularities.

Methods suitable for overwriting:

new_request(\%meta)

default implementation will just call new_request from the attached flow

Helpful methods

$connection->dump_state

dumps the state of the open connections via xdebug

$connection->offset($dir)

returns the current offset in the data stream, that is the position behind the within the in_* methods forwarded data.

$connection->open_requests

returns the number of open requests, if any.

LIMITS

100 Continue, 101 Upgrade are not yet implemented.