Package org.microproxy

Interface ActivityTracker

All Known Implementing Classes:
ActivityLogger, ActivityTrackerAdapter
public interface ActivityTracker
Observes proxy activity, e.g. for metrics or access logs. Callbacks run on the connection's virtual thread and should be quick; every method has a no-op default.

  • Method Details

    • clientConnected

      default void clientConnected(FlowContext flowContext)
      Called when the proxy accepts a client connection.
      Parameters:
      flowContext - the client connection or exchange context

    • clientSSLHandshakeStarted

      default void clientSSLHandshakeStarted(FlowContext flowContext)
      Called before the TLS handshake with the client starts.
      Parameters:
      flowContext - the client connection or exchange context

    • clientSSLHandshakeSucceeded

      default void clientSSLHandshakeSucceeded(FlowContext flowContext, SSLSession sslSession)
      Called after the TLS handshake with the client succeeds.
      Parameters:
      flowContext - the client connection or exchange context
      sslSession - the client TLS session, or null for a plaintext connection

    • tlsHandshakeFailed

      default void tlsHandshakeFailed(FlowContext flowContext, boolean clientSide, Throwable cause)
      Called when a TLS handshake failed or timed out, before the failure is handled.
      Parameters:
      flowContext - the client's context for a handshake with the client (the TLS listener or an intercepted session); for one with a server or a TLS chained proxy, a FullFlowContext naming it
      clientSide - whether the handshake was with the client
      cause - the handshake's error, e.g. an SSLHandshakeException or a SocketTimeoutException

    • clientDisconnected

      default void clientDisconnected(FlowContext flowContext, SSLSession sslSession)
      Called when the client connection closes.
      Parameters:
      flowContext - the client connection or exchange context
      sslSession - the client TLS session, or null for a plaintext connection

    • bytesReceivedFromClient

      default void bytesReceivedFromClient(FlowContext flowContext, int numberOfBytes)
      Called after bytes are read from the client.
      Parameters:
      flowContext - the client connection or exchange context
      numberOfBytes - the number of bytes transferred

    • requestReceivedFromClient

      default void requestReceivedFromClient(FlowContext flowContext, HttpRequest httpRequest)
      Called when a request head arrives from the client.
      Parameters:
      flowContext - the client connection or exchange context
      httpRequest - the request head

    • bytesSentToServer

      default void bytesSentToServer(FullFlowContext flowContext, int numberOfBytes)
      Called after bytes are written to the server.
      Parameters:
      flowContext - the server connection context
      numberOfBytes - the number of bytes transferred

    • requestSentToServer

      default void requestSentToServer(FullFlowContext flowContext, HttpRequest httpRequest)
      Called when a request head is sent to the server.
      Parameters:
      flowContext - the server connection context
      httpRequest - the request head

    • bytesReceivedFromServer

      default void bytesReceivedFromServer(FullFlowContext flowContext, int numberOfBytes)
      Called after bytes are read from the server.
      Parameters:
      flowContext - the server connection context
      numberOfBytes - the number of bytes transferred

    • responseReceivedFromServer

      default void responseReceivedFromServer(FullFlowContext flowContext, HttpResponse httpResponse)
      Called when a response head arrives from the server.
      Parameters:
      flowContext - the server connection context
      httpResponse - the response head

    • bytesSentToClient

      default void bytesSentToClient(FlowContext flowContext, int numberOfBytes)
      Called after bytes are written to the client.
      Parameters:
      flowContext - the client connection or exchange context
      numberOfBytes - the number of bytes transferred

    • responseSentToClient

      default void responseSentToClient(FlowContext flowContext, HttpResponse httpResponse)
      Called when a response head is sent to the client.
      Parameters:
      flowContext - the client connection or exchange context
      httpResponse - the response head

    • responseSentToClient

      default void responseSentToClient(FlowContext flowContext, HttpResponse httpResponse, ResponseSource source)
      Called when a response head has been sent to the client, with where the response came from. The default calls responseSentToClient(FlowContext, HttpResponse), so override one or the other. The status the server sent, if any, is FlowContext.upstreamStatus().
      Parameters:
      flowContext - the client connection or exchange context
      httpResponse - the response head
      source - where the response originated

    • responseCompleted

      default void responseCompleted(FlowContext flowContext, HttpResponse httpResponse)
      Called when the whole response to a request, body included, has been written to the client (for a CONNECT or a protocol upgrade: once the response head has, before the tunnel starts). FlowContext.timings() is complete then. Not called when the exchange is abandoned half-way, e.g. because the server or the client failed.
      Parameters:
      flowContext - the client connection or exchange context
      httpResponse - the response head

    • flowEnded

      default void flowEnded(FlowRecord record)
      Called once when an exchange or a flow is over, with what an access log needs to know about it: an HTTP exchange whose response has been written or that was abandoned (after responseCompleted(org.microproxy.FlowContext, org.microproxy.http.HttpResponse), when that was called), and a CONNECT tunnel, a SOCKS client's tunnel, a WebSocket session, a TCP-hook tunnel, a CONNECT-UDP flow, or a transparent QUIC flow that was relayed or intercepted stream by stream, when it closes. FlowRecord.context()'s FlowContext.failure() and FlowContext.responseFlags() are final then.
      Parameters:
      record - the finished exchange or flow

    • serverConnected

      default void serverConnected(FullFlowContext flowContext, InetSocketAddress serverAddress)
      Called when the proxy connects to a server.
      Parameters:
      flowContext - the server connection context
      serverAddress - the connected server address

    • serverDisconnected

      default void serverDisconnected(FullFlowContext flowContext, InetSocketAddress serverAddress)
      Called when the server connection closes.
      Parameters:
      flowContext - the server connection context
      serverAddress - the connected server address

    • connectionTimedOut

      default void connectionTimedOut(FlowContext flowContext)
      Called when the client connection reaches its idle timeout.
      Parameters:
      flowContext - the client connection or exchange context

    • connectionExceptionCaught

      default void connectionExceptionCaught(FlowContext flowContext, Throwable cause)
      Called when something failed on the client side of a flow: client I/O errors, and unexpected exceptions while serving the connection (which is then closed).
      Parameters:
      flowContext - the client connection or exchange context
      cause - the failure that triggered this event

    • serverConnectionExceptionCaught

      default void serverConnectionExceptionCaught(FullFlowContext serverContext, Throwable cause)
      Called once for each failure on the server side of a flow: a failed connection attempt (unresolved name, refused or timed-out connect, failed TLS handshake, a chained proxy that refused; with several chained proxies, once per proxy tried), a server that timed out or answered badly, or an unexpected exception while a server connection was in use (also reported to connectionExceptionCaught(org.microproxy.FlowContext, java.lang.Throwable), as the client connection closes too). serverContext names the server or chained proxy; its remote address is null when the name did not resolve. A keep-alive connection that turned out to be closed, and is retried transparently, is not reported.
      Parameters:
      serverContext - the server connection context
      cause - the failure that triggered this event

    • transparentQuicFlowDecided

      default void transparentQuicFlowDecided(FlowContext flowContext, ClientHello clientHello, boolean intercepted, String reason)
      Called when the transparent QUIC listener (HttpProxyServerBootstrap.withTransparentQuicPort(int)) has decided what to do with a new client flow, from its ClientHello: intercept it (its HTTP/3 requests then come as for any client), or relay its datagrams to the server untouched. clientConnected(org.microproxy.FlowContext) came before, with the same context; clientDisconnected(org.microproxy.FlowContext, javax.net.ssl.SSLSession) comes when the flow ends.
      Parameters:
      flowContext - the flow's context, whose FlowContext.isTransparentQuic() is true
      clientHello - the ClientHello the client sent in its Initial packets
      intercepted - whether the proxy intercepts the flow; false when it relays it
      reason - why the flow is relayed (an ignored host, no HTTP/3 offered, a filter declined, ...), or null when it is intercepted