Luasec HTTP 2 Module

The HTTP/2 module (http2.lua) of Luasec was part of the project I worked on during GSoC'17. The RFC followed can be found here. I also took a lot of template code from lua-http which can be found here. Certain modules from lua-http were imported without much changes but have been modified to work with luasec. The connection:methods and stream:methods are mostly based on lua-http module which I have worked on to work with luasocket. The HTTP/2 module right now can be used for basic tasks and is a work in progress.

The default settings is initialised in the beginning of the stream module. It contains a set of variables which are assigned according to this spec.

The stream can have 7 valid states and they are defined using the valid_states table. The stream can be in the following states:

• idle
• open
• reserved(local)
• reserved (remote)
• half closed(local)
• half closed(remote)
• closed

There are also ten frame types. They are:

• Data
• Headers
• Priority
• Window update
• Ping
• Push promise
• Goaway
• Settings
• RST_stream
• Continuation.

The following functions have been included in the module using which we can write more complex functions in the future.

Reading and Writing HTTP/2 frames to the socket

write_http2_frame is the function which is the most basic handler for sending all types of frames. It get's called from within all other send_*_frame functions. It takes four parameters, they are:

• stream_id. An integer which specifies the id of the stream. For the settings frame this value should be 0.
• frame_types. Value for this is derived from the frame_types table from above.
• flags. Set this value to indicate things like SETTINGS ACK, END_STREAM etc.
• payload. The binary payload which has to sent.

read_http2_frame is the function which is used to read binary data from the socket. It interprets the frames, decodes it and passes on the data. It takes one parameter:

• timeout

Auxiliary frame definition functions

The following are the functions implemented for supporting sending various types of frames:

send_settings_frame is the function used for sending the settings table after the HTTP/2 connection is negotiated. The payload of a SETTINGS frame consists of zero or more parameters, each consisting of an unsigned 16-bit setting identifier and an unsigned 32-bit value. It takes two parameters:

• ACK. If this is set, the function would send a Settings acknowledgement frame.
• Settings payload. The settings table that is supposed to be sent.

send_window_update_frame is the function used for sending packets which help us control the flow of the connection. We can also control the flow for a particular stream or for an entire connection. Both types of flow control are hop by hop, that is, only between the two endpoints. Intermediaries do not forward WINDOW_UPDATE frames between dependent connections. However, throttling of data transfer by any receiver can indirectly cause the propagation of flow-control information toward the original sender. The function takes

send_continuation_frame is the function used for sending continuous header block segments split in multiple frames. Any number of these frames can be sent as long as the previous frame is on the same stream and is HEADERS, PUSH_PROMISE or CONTINUATION frame.

send_headers_frame is the connection used for sending the HTTP headers to the endpoint and additionally carries a header block fragment. HEADERS frames can be sent on a stream in the "idle", "reserved (local)", "open", or "half-closed (remote)" state car. It can also be used to start a HTTP/2 connection along with the send_settings_frame function.

send_priority_frame is the connection used for advertising the sender assigned priority of the stream. It can sent in any stream state, idle or closed streams.

send_goaway_frame is the function used to initiate shutdown of a connection or to signal serious error conditions. GOAWAY allows an endpoint to gracefully stop accepting new streams while still finishing processing of previously established streams. This enables administrative actions, like server maintenance. It takes four parameters:

• last_stream_id
• err_code
• debug_msg
• timeout

send_data_frame is the function used for sending DATA frames which convey arbitrary, variable-length sequences of octets associated with a stream. One or more DATA frames are used, for instance, to carry HTTP request or response payloads.

send_rst_stream_frame is the function used for immediate termination of a stream. RST_STREAM is sent to request cancellation of a stream or to indicate that an error condition has occurred

send_push_promise_frame is the function used to notify the peer endpoint in advance of streams the sender intends to initiate. The PUSH_PROMISE frame includes the unsigned 31-bit identifier of the stream the endpoint plans to create along with a set of headers that provide additional context for the stream.

send_ping_frame is the function used for measuring a minimal round-trip time from the sender, as well as determining whether an idle connection is still functional. PING frames can be sent from any endpoint. It takes one parameter:

• timeout

The stream module can be testing using a sample request table which is already included in the module itself. The stream has various states which can be set using set_state function.