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