.. _alc_dot_http:

HTTP
====

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


.. method:: alc.http.get_message()

    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.

.. _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.

        This attribute is read-only.

    .. 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 *str*.
        Pseudo-headers are not included.

        This attribute is read-only, the dict can not be modified.

    .. attribute:: body
    
        Body of the request: a *str* in case of a regular message or a *tuple* of :class:`alc.http.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 similar to how a 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.

        This attribute is read-only.

    .. attribute:: headers

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

        This attribute is read-only, the dict can not be modified.

    .. attribute:: body
    
        Body of the response: a *str* in case of a regular message or a *tuple* of :class:`alc.http.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 request contains the headers (including :method and :path pseudo-headers) and body
        of the request, formatted similar to how a 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.

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 *str*.
        Pseudo-headers are not included.

        This attribute is read-only, the dict can also not be modified.
        
    .. method:: body

        Body of the message part as a *str*. Can be modified to be a *str* or *bytes*.

    .. describe:: str(part)

        The string representation of a request contains the headers (including :method and :path pseudo-headers) and body
        of the request, formatted similar to how a 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.
        

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: