Events

General

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.
done()	Called once when the script shuts down, either because it’s been unloaded, or because the proxy itself is shutting down.
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”).
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.
tick()	Called at a regular sub-second interval as long as the addon is executing.

Connection

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.proxy.protocol for an explanation what the root layer is), provides transparent access to all attributes of the RootContext. For example, root_layer.client_conn.address gives the remote address of the connecting client.
clientdisconnect(root_layer)	Called when a client disconnects from the proxy. root_layer The root layer object.
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.
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.
serverdisconnect(server_conn)	Called when the proxy has closed the server connection. server_conn A ServerConnection object.

HTTP Events

http_connect(flow)	Called when we receive an HTTP CONNECT request. Setting a non 2xx response on the flow will return the response to the client abort the connection. CONNECT requests and responses do not generate the usual HTTP handler events. CONNECT requests are only valid in regular and upstream proxy modes. flow A models.HTTPFlow object. The flow is guaranteed to have non-None request and requestheaders attributes.
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.
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.
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.
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.
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

These events are called only after a connection made an HTTP upgrade with “101 Switching Protocols”. No further HTTP-related events after the handshake are issued, only new WebSocket messages are called.

websocket_handshake(flow)	Called when a client wants to establish a WebSocket connection. The WebSocket-specific headers can be manipulated to alter 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.
websocket_start(flow)	Called when WebSocket connection is established after a successful handshake. flow A models.WebSocketFlow object.
websocket_message(flow)	Called when a WebSocket message 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. Currently there are two types of messages, corresponding to the BINARY and TEXT frame types. flow A models.WebSocketFlow object.
websocket_end(flow)	Called when WebSocket connection ends. flow A models.WebSocketFlow object.
websocket_error(flow)	Called when a WebSocket error occurs - e.g. the connection closing unexpectedly. flow A models.WebSocketFlow object.

TCP Events

These events are called only if the connection is in TCP mode. So, for instance, TCP events are not called for ordinary HTTP/S connections.

tcp_start(flow)	Called when TCP streaming starts. flow A models.TCPFlow object.
tcp_message(flow)	Called when 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.
tcp_end(flow)	Called when TCP streaming ends. flow A models.TCPFlow object.
tcp_error(flow)	Called when a TCP error occurs - e.g. the connection closing unexpectedly. flow A models.TCPFlow object.