Net::Inspect::L7::HTTP::WebSocket - implements WebSocket-upgrade
package myRequest; use base 'Net::Inspect::Flow'; # define methods needed by Net::Inspect::L7::HTTP sub in_request_header { ... } ... use base 'Net::Inspect::L7::HTTP::WebSocket'; # define the methods needed for WebSockets sub in_wsctl { ... } sub in_wsdata { ... }
This module implements the upgrade_websocket method which gets called by Net::Inspect::L7::HTTP if an upgrade to websockets is encountered:
upgrade_websocket
If this function is implemented in the request object by deriving from this class it will check if the current upgrade is a valid websocket upgrade by inspecting $request and <$response>. These hashes are a the result of parse_reqhdr and parse_rsphdr in Net::Inspect::L7::HTTP.
$request
parse_reqhdr
parse_rsphdr
The Net::Inspect::L7::HTTP object is also given, because it will be used (as a weak reference) in the callback $sub which gets returned if the connection upgrade was considered is valid.
$sub
This callback $sub will then be called as $sub->($dir,$data,$eof,$time) similar to in_data as documented in Net:Inspect::L7::HTTP. Based on the input $sub will then forward to in_wsctl or in_wsdata which need to be defined by the request object.
$sub->($dir,$data,$eof,$time)
in_data
in_wsctl
in_wsdata
If the upgrade fails because the information sent in the headers are not correct the function will throw an error (i.e. die()) which will be catched by the caller $conn and will cause the connection to be declared bad.
$conn
The following functions will be called on new data and will need to be defined by the request object:
This will be called after a Websocket upgrade when receiving a control frame. $dir is 0 for data from client, 1 for data from server. $data is the unmasked payload of the frame. $frameinfo is a blessed hash reference which contains the opcode of the frame, the mask (binary) and header for the frame header. For a close frame it will also contain the extracted status code and the reason.
$dir
$data
$frameinfo
opcode
mask
header
status
reason
To get the unmasked payload call $frameinfo->unmask($masked_data).
$frameinfo->unmask($masked_data)
in_wsctl will be called on connection close with $data of '' and no \%frameinfo (i.e. no hash reference).
''
\%frameinfo
This will be called after a Websocket upgrade when receiving data inside a data frame. Contrary to (the short) control frames the data frame must not be read fully before calling in_wsdata.
$dir is 0 for data from client, 1 for data from server. $data is the unmasked payload of the frame. $eom is true if the message is done with this call, that is if the data frame is done and the FIN bit was set on the frame. $frameinfo is a blessed hash reference which contains the data type as opcode. This will be the original opcode of the starting frame in case of fragmented transfer. It will also contain the mask (binary) of the current frame.
$eom
If this is the initial part of the data (i.e. initial frame in possibly fragmented data and initial data inside this frame) it will also have init set to true inside $frameinfo.
init
If there are still unread data within the frame $frameinfo will contain bytes_left as <[hi,low]> where hi and low are the upper and lower 32 bit parts of the number of outstanding bytes.
bytes_left
<[hi,low]
hi
low
If this call to in_wsdata was caused by the start of a new frame and not further data in the same frame header will be set to the header of this new frame. In all other cases header is not set.
To install Net::Inspect, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Net::Inspect
CPAN shell
perl -MCPAN -e shell install Net::Inspect
For more information on module installation, please visit the detailed CPAN module installation guide.