mitmproxy/docs/scripting/events.rst

.. _events:

Events
=======

General
-------

.. list-table::
    :widths: 40 60
    :header-rows: 0

    *   - .. py:function:: configure(options, updated)
        - Called once on startup, and whenever options change.

          *options*
            An ``options.Options`` object with the total current configuration
            state of mitmproxy.
          *updated*
            A set of strings indicating which configuration options have been
            updated. This contains all options when *configure* is called on
            startup, and only changed options subsequently.

    *   - .. py:function:: done()
        - Called once when the script shuts down, either because it's been
          unloaded, or because the proxy itself is shutting down.

    *   - .. py:function:: log(entry)
        - Called whenever an event log is added.

          *entry*
            An ``controller.LogEntry`` object - ``entry.msg`` is the log text,
            and ``entry.level`` is the urgency level ("debug", "info", "warn",
            "error").

    *   - .. py:function:: start()
        - Called once on startup, before any other events. If you return a
          value  from this event, it will replace the current addon. This
          allows you to, "boot into" an addon implemented as a class instance
          from the module level.

    *   - .. py:function:: tick()
        - Called at a regular sub-second interval as long as the addon is
          executing.


Connection
----------

.. list-table::
    :widths: 40 60
    :header-rows: 0

    *   - .. py:function:: clientconnect(root_layer)
        - Called when a client initiates a connection to the proxy. Note that a
          connection can correspond to multiple HTTP requests.

          *root_layer*
            The root layer (see `mitmproxy.protocol` for an explanation what
            the root layer is), provides transparent access to all attributes
            of the :py:class:`~mitmproxy.proxy.RootContext`. For example,
            ``root_layer.client_conn.address`` gives the remote address of the
            connecting client.

    *   - .. py:function:: clientdisconnect(root_layer)
        - Called when a client disconnects from the proxy.

          *root_layer*
            The root layer object.

    *   - .. py:function:: next_layer(layer)

        - Called whenever layers are switched. You may change which layer will
          be used by returning a new layer object from this event.

          *layer*
            The next layer, as determined by mitmpmroxy.

    *   - .. py:function:: serverconnect(server_conn)
        - Called before the proxy initiates a connection to the target server.
          Note that a connection can correspond to multiple HTTP requests.

          *server_conn*
            A ``ServerConnection`` object. It is guaranteed to have a non-None
            ``address`` attribute.

    *   - .. py:function:: serverdisconnect(server_conn)
        - Called when the proxy has closed the server connection.

          *server_conn*
            A ``ServerConnection`` object.


HTTP Events
-----------

.. list-table::
    :widths: 40 60
    :header-rows: 0

    *   - .. py:function:: request(flow)
        - Called when a client request has been received.

          *flow*
            A ``models.HTTPFlow`` object. At this point, the flow is
            guaranteed to have a non-None ``request`` attribute.

    *   - .. py:function:: requestheaders(flow)
        - Called when the headers of a client request have been received, but
          before the request body is read.

          *flow*
            A ``models.HTTPFlow`` object. At this point, the flow is
            guaranteed to have a non-None ``request`` attribute.

    *   - .. py:function:: responseheaders(flow)

        - Called when the headers of a server response have been received, but
          before the response body is read.

          *flow*
            A ``models.HTTPFlow`` object. At this point, the flow is
            guaranteed to have a non-none ``request`` and ``response``
            attributes, however the response will have no content.

    *   - .. py:function:: response(flow)

        - Called when a server response has been received.

          *flow*
            A ``models.HTTPFlow`` object. At this point, the flow is
            guaranteed to have a non-none ``request`` and ``response``
            attributes. The raw response body will be in ``response.body``,
            unless response streaming has been enabled.

    *   - .. py:function:: error(flow)
        - Called when a flow error has occurred, e.g. invalid server responses,
          or interrupted connections. This is distinct from a valid server HTTP
          error response, which is simply a response with an HTTP error code.

          *flow*
            The flow containing the error. It is guaranteed to have
            non-None ``error`` attribute.


WebSocket Events
-----------------

.. list-table::
    :widths: 40 60
    :header-rows: 0

    *   - .. py:function:: websockets_handshake(flow)

        - Called when a client wants to establish a WebSockets connection. The
          WebSockets-specific headers can be manipulated to manipulate the
          handshake. The ``flow`` object is guaranteed to have a non-None
          ``request`` attribute.

          *flow*
            The flow containing the HTTP websocket handshake request. The
            object is guaranteed to have a non-None ``request`` attribute.


TCP Events
----------

These events are called only if the connection is in :ref:`TCP mode
<tcpproxy>`. So, for instance, TCP events are not called for ordinary HTTP/S
connections.

.. list-table::
    :widths: 40 60
    :header-rows: 0

    *   - .. py:function:: tcp_end(flow)
        - Called when TCP streaming ends.

          *flow*
            A ``models.TCPFlow`` object.

    *   - .. py:function:: tcp_error(flow)
        - Called when a TCP error occurs - e.g. the connection closing
          unexpectedly.

          *flow*
            A ``models.TCPFlow`` object.

    *   - .. py:function:: tcp_message(flow)

        - Called a TCP payload is received from the client or server. The
          sender and receiver are identifiable. The most recent message will be
          ``flow.messages[-1]``. The message is user-modifiable.

          *flow*
            A ``models.TCPFlow`` object.

    *   - .. py:function:: tcp_start(flow)
        - Called when TCP streaming starts.

          *flow*
            A ``models.TCPFlow`` object.