.. _alc_dot_http:

HTTP
====

The system provides the following Python APIs to inspect and modify HTTP/2 messages.


.. method:: alc.http.get_message(*, check_binary=None)

    Returns the current HTTP message object of type :class:`alc.http.Request` or :class:`alc.http.Response`.
    In case HTTP processing is currently not active, *none* is returned.

    :param set check_binary: When provided a set of content types, the function returns *bytes* if the message's content type is in the set, otherwise returns *str*. See :ref:`alc_http_binary_content_types` for more details.
    :rtype: bytes | str | None    

.. _alc_dot_http_request:

The :data:`alc.http.Request` class
----------------------------------

.. class:: alc.http.Request

    Class representing an HTTP request.
   
    .. attribute:: method

        HTTP method (GET/POST/PUT/...), value of the :method pseudo-header.

    .. attribute:: scheme
    
        HTTP scheme, value of the :scheme pseudo-header.
        The only valid values are "http" and "https".

    .. attribute:: authority
    
        HTTP authority, value of the :authority pseudo-header.

    .. attribute:: path
    
        HTTP path, value of the :path pseudo-header.

    .. attribute:: headers
    
        A *dict* of headers where the keys are the header names (in lowercase) and the values are the header values; both are *str*.
        Pseudo-headers are not included.


    .. attribute:: body
    
        Body of the request: a str or bytes in case of a regular message or a tuple of MessagePart in case of a multipart message

    .. attribute:: client

        The client endpoint, a *str* formatted as "ip:port".

    .. attribute:: server

        The server endpoint, a *str* formatted as "ip:port".

    .. attribute:: ingress

        A boolean indicating whether this request is ingressing (*True*) or egressing (*False*).

    .. describe:: str(request)

        The string representation of a request contains the headers (including :method and :path pseudo-headers) and body
        of the request, formatted similarly to how an HTTP/1.x message is transmitted.
        
        This can be used for debugging purposes, but should not be used in production scripts to obtain any of the information
        in the request, as the specialized methods are much more performant.

.. _alc_dot_http_response:

The :data:`alc.http.Response` class
-----------------------------------

.. class:: alc.http.Response

    Class representing an HTTP response.
   
    .. attribute:: status

        HTTP status (200/404/501/...), value of the :status pseudo-header.


    .. attribute:: headers

        A *dict* of headers where the keys are the header names (in lowercase) and the values are the header values; both are *str*.
        Pseudo-headers are not included.

        This attribute is read-only, but the object can be modified.

    .. attribute:: body
    
        Body of the response: a str or bytes in case of a regular message or a tuple of MessagePart in case of a multipart message.

    .. attribute:: client

        The client endpoint, a *str* formatted as "ip:port".

    .. attribute:: server

        The server endpoint, a *str* formatted as "ip:port".

    .. attribute:: ingress

        A boolean indicating whether this response is ingressing (*True*) or egressing (*False*).

    .. describe:: str(response)

        The string representation of a response contains the headers (including :status pseudo-header) and body
        of the response, formatted similarly to how an HTTP/1.x message is transmitted.
        
        This can be used for debugging purposes, but should not be used in production scripts to obtain any of the information
        in the response, as the specialized methods are much more performant.

The :data:`alc.http.MessagePart` class
--------------------------------------

.. class:: alc.http.MessagePart

    Class representing a single part of a multipart request/response.

    .. attribute:: headers

        A *dict* of headers where the keys are the header names (in lowercase) and the values are the header values; both are *str*.
        Pseudo-headers are not included.

        This attribute is read-only; the dict cannot be modified.
        
    .. attribute:: body

        Body of the message part as a *str* or *bytes*. If the message part contains binary content, the type of the body attribute is automatically determined based on the Content-Type header.

    .. describe:: str(part)

        The string representation of a message part contains the headers and body
        of the part, formatted similarly to how an HTTP/1.x message is transmitted.
        
        This can be used for debugging purposes, but should not be used in production scripts to obtain any of the information
        in the message part, as the specialized methods are much more performant.

.. _alc_http_binary_content_types:   

Binary vs textual content
-------------------------

The body of HTTP messages is by default represented as a str object. However, if the HTTP message contains binary content, the type of the body attribute is automatically determined based on the Content-Type header of the HTTP message.

To opt in to this behavior, provide a set of content-types to the check_binary argument of the get_message() function. When this argument is passed, the Content-Type header of the HTTP message will be inspected and compared against the values in the provided set. If a match is found, the content is identified as binary and the body of the message will be a bytes object instead of a str (the default).

In case of multi-part bodies, this checking is applied to each part individually.


Examples
--------

Example 1: Check for Request/Response and modify body
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. literalinclude:: ./examples/http-modify-request-body.py
    :language: python
    :linenos:

Example 2: Modify the Request path
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. literalinclude:: ./examples/http-modify-path.py
    :language: python
    :linenos:

Example 3: More complex script to add QOS data
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. literalinclude:: ./examples/http-add-qos-data.py
    :language: python
    :linenos: