Writing H2 Tests

These instructions assume you are already familiar with the testing infrastructure and know how to write a standard HTTP/1.1 test.

On top of the standard main handler that the H1 server offers, the H2 server also offers support for specific frame handlers in the Python scripts. Currently there is support for for handle_headers and handle_data. Unlike the main handler, these are run whenever the server receives a HEADERS frame (RequestReceived event) or a DATA frame (DataReceived event). main can still be used, but it will be run after the server has received the request in its entirety.

Here is what a Python script for a test might look like:

def handle_headers(frame, request, response):
    if request.headers["test"] == "pass":
        response.status = 200
        response.headers.update([('test', 'passed')])
        response.write_status_headers()
    else:
        response.status = 403
        response.headers.update([('test', 'failed')])
        response.write_status_headers()
        response.writer.end_stream()

def handle_data(frame, request, response):
    response.writer.write_data(frame.data[::-1])

def main(request, response):
    response.writer.write_data('\nEnd of File', last=True)

The above script is fairly simple:

  1. Upon receiving the HEADERS frame, handle_headers is run.
    • This checks for a header called ‘test’ and checks if it is set to ‘pass’. If true, it will immediately send a response header, otherwise it responds with a 403 and ends the stream.
  2. Any DATA frames received will then be handled by handle_data. This will simply reverse the data and send it back.
  3. Once the request has been fully received, main is run which will send one last DATA frame and signal its the end of the stream.

Response Writer API

The H2Response API is pretty much the same as the H1 variant, the main API difference lies in the H2ResponseWriter which is accessed through response.writer

write_headers(self, headers, status_code, status_message=None, stream_id=None, last=False):

Write a HEADER frame using the H2 Connection object, will only work if the stream is in a state to send HEADER frames. This will automatically format the headers so that pseudo headers are at the start of the list and correctly prefixed with ‘:’. Since this using the H2 Connection object, it requires that the stream is in the correct state to be sending this frame.

Note: Will raise ProtocolErrors if pseudo headers are missing.

  • Parameters

    • headers: List of (header, value) tuples
    • status_code: The HTTP status code of the response
    • stream_id: Id of stream to send frame on. Will use the request stream ID if None
    • last: Flag to signal if this is the last frame in stream.

write_data(self, item, last=False, stream_id=None):

Write a DATA frame using the H2 Connection object, will only work if the stream is in a state to send DATA frames. Uses flow control to split data into multiple data frames if it exceeds the size that can be in a single frame. Since this using the H2 Connection object, it requires that the stream is in the correct state to be sending this frame.

  • Parameters

    • item: The content of the DATA frame
    • last: Flag to signal if this is the last frame in stream.
    • stream_id: Id of stream to send frame on. Will use the request stream ID if None

write_push(self, promise_headers, push_stream_id=None, status=None, response_headers=None, response_data=None):

This will write a push promise to the request stream. If you do not provide headers and data for the response, then no response will be pushed, and you should send them yourself using the ID returned from this function.

  • Parameters

    • promise_headers: A list of header tuples that matches what the client would use to request the pushed response
    • push_stream_id: The ID of the stream the response should be pushed to. If none given, will use the next available id.
    • status: The status code of the response, REQUIRED if response_headers given
    • response_headers: The headers of the response
    • response_data: The response data.

  • Returns: The ID of the push stream

write_raw_header_frame(self, headers, stream_id=None, end_stream=False, end_headers=False, frame_cls=HeadersFrame):

Unlike write_headers, this does not check to see if a stream is in the correct state to have HEADER frames sent through to it. It also won't force the order of the headers or make sure pseudo headers are prefixed with ‘:’. It will build a HEADER frame and send it without using the H2 Connection object other than to HPACK encode the headers.

Note: The frame_cls parameter is so that this class can be reused by write_raw_continuation_frame, as their construction is identical.

  • Parameters
    • headers: List of (header, value) tuples
    • stream_id: Id of stream to send frame on. Will use the request stream ID if None
    • end_stream: Set to True to add END_STREAM flag to frame
    • end_headers: Set to True to add END_HEADERS flag to frame

write_raw_data_frame(self, data, stream_id=None, end_stream=False):

Unlike write_data, this does not check to see if a stream is in the correct state to have DATA frames sent through to it. It will build a DATA frame and send it without using the H2 Connection object. It will not perform any flow control checks.

  • Parameters
    • data: The data to be sent in the frame
    • stream_id: Id of stream to send frame on. Will use the request stream ID if None
    • end_stream: Set to True to add END_STREAM flag to frame

write_raw_continuation_frame(self, headers, stream_id=None, end_headers=False):

This provides the ability to create and write a CONTINUATION frame to the stream, which is not exposed by write_headers as the h2 library handles the split between HEADER and CONTINUATION internally. Will perform HPACK encoding on the headers. It also ignores the state of the stream.

This calls write_raw_data_frame with frame_cls=ContinuationFrame since the HEADER and CONTINUATION frames are constructed in the same way.

  • Parameters:
    • headers: List of (header, value) tuples
    • stream_id: Id of stream to send frame on. Will use the request stream ID if None
    • end_headers: Set to True to add END_HEADERS flag to frame

end_stream(self, stream_id=None):

Ends the stream with the given ID, or the one that request was made on if no ID given.

  • Parameters
    • stream_id: Id of stream to send frame on. Will use the request stream ID if None