Package org.microproxy

Class FlowRecord

java.lang.Object
org.microproxy.FlowRecord
public final class FlowRecord extends Object
What an access log needs to know about one finished exchange or flow, handed to ActivityTracker.flowEnded(org.microproxy.FlowRecord) once it is over: an HTTP exchange once its response has been written (or it was abandoned), a CONNECT tunnel, a SOCKS client's tunnel, a WebSocket session, a tunnel seen by the TCP hooks, a CONNECT-UDP flow, and a QUIC flow the transparent QUIC listener relayed or intercepted stream by stream, each when it closes.

Records are immutable, except for the unique id, which is made the first time it is asked for. Values the proxy does not know are null, or -1 for numbers.

  • Method Details

    • builder

      public static FlowRecord.Builder builder(FlowContext context, FlowRecord.Kind kind)
      Starts a record of an exchange or flow on context.
      Parameters:
      context - the client's context of the exchange or flow
      kind - what kind of exchange or flow it is
      Returns:
      a builder

    • context

      public FlowContext context()
      Returns the client's context of the exchange or flow.
      Returns:
      the client's context of the exchange or flow

    • kind

      public FlowRecord.Kind kind()
      Returns what kind of exchange or flow this is.
      Returns:
      what kind of exchange or flow this is

    • request

      public HttpRequest request()
      The request as the client sent it, before the proxy and filters rewrote it; for a tunnel or a flow, the CONNECT (real, or made up for a SOCKS client, a transparent connection or a QUIC flow) that opened it. Null when the request could not be read.
      Returns:
      the client's request head, or null

    • response

      public HttpResponse response()
      Returns the response head the client got (or that a SOCKS or transparent client's tunnel was answered with), or null.
      Returns:
      the response head the client got (or that a SOCKS or transparent client's tunnel was answered with), or null

    • trailers

      public HttpHeaders trailers()
      Returns the response's trailers, or null when it had none.
      Returns:
      the response's trailers, or null when it had none

    • source

      public ResponseSource source()
      Returns where the response came from, or null when there was none.
      Returns:
      where the response came from, or null when there was none

    • responseCode

      public int responseCode()
      Returns the status of the response the client got, or 0 when it got none.
      Returns:
      the status of the response the client got, or 0 when it got none

    • startEpochMillis

      public long startEpochMillis()
      Returns when the exchange or flow started (wall clock, epoch milliseconds); 0 when unknown.
      Returns:
      when the exchange or flow started (wall clock, epoch milliseconds); 0 when unknown

    • duration

      public Optional<Duration> duration()
      How long the exchange or flow lasted: for HTTP, from the first byte of the request to the last byte of the response (or until it was abandoned); for a tunnel or a flow, until it closed.
      Returns:
      the duration, or empty when unknown

    • durationNanos

      public long durationNanos()
      Returns the duration in nanoseconds, or -1 when unknown.
      Returns:
      the duration in nanoseconds, or -1 when unknown

    • timings

      public FlowTimings timings()
      Returns the exchange's phase timings (see FlowContext.timings()).
      Returns:
      the exchange's phase timings (see FlowContext.timings())

    • bytesReceived

      public long bytesReceived()
      Bytes received from the client: the request body for HTTP, the client's payload for a tunnel or a flow.
      Returns:
      the byte count, or -1 when unknown

    • bytesSent

      public long bytesSent()
      Bytes sent to the client: the response body for HTTP, the server's payload for a tunnel or a flow.
      Returns:
      the byte count, or -1 when unknown

    • upstreamBytesSent

      public long upstreamBytesSent()
      Returns the bytes written to the server connection, heads and framing included, or -1 when unknown.
      Returns:
      the bytes written to the server connection, heads and framing included, or -1 when unknown

    • upstreamBytesReceived

      public long upstreamBytesReceived()
      Returns the bytes read from the server connection, heads and framing included, or -1 when unknown.
      Returns:
      the bytes read from the server connection, heads and framing included, or -1 when unknown

    • upstreamAddress

      public InetSocketAddress upstreamAddress()
      Returns the address the proxy was connected to for the exchange: the server, or a chained proxy; or null.
      Returns:
      the address the proxy was connected to for the exchange: the server, or a chained proxy; or null

    • upstreamLocalAddress

      public InetSocketAddress upstreamLocalAddress()
      Returns the proxy's local address on its connection to the server, or null.
      Returns:
      the proxy's local address on its connection to the server, or null

    • downstreamLocalAddress

      public InetSocketAddress downstreamLocalAddress()
      Returns the proxy's local address on the client connection, or null.
      Returns:
      the proxy's local address on the client connection, or null

    • upstreamCluster

      public String upstreamCluster()
      The name of where the exchange went: the chained proxy it went through (host:port), or else the server's host:port.
      Returns:
      the upstream's name, or null

    • upstreamProtocol

      public String upstreamProtocol()
      The protocol the proxy spoke to upstreamCluster(): to the chained proxy the exchange went through, HTTP/1.1 or HTTP/2 (for a tunnel, the protocol its CONNECT went in), SOCKS4 or SOCKS5; else to the server, HTTP/1.1, HTTP/2 or HTTP/3.
      Returns:
      the protocol, or null when the exchange reached no upstream, or was a tunnel straight to the server

    • upstreamSslSession

      public SSLSession upstreamSslSession()
      Returns the TLS session with the server (or a TLS chained proxy), or null.
      Returns:
      the TLS session with the server (or a TLS chained proxy), or null

    • upstreamTransportFailureReason

      public String upstreamTransportFailureReason()
      Returns why the TLS handshake with the server failed, or null.
      Returns:
      why the TLS handshake with the server failed, or null

    • responseFlags

      public Set<ResponseFlag> responseFlags()
      Returns the response flags (see FlowContext.responseFlags()), unmodifiable.
      Returns:
      the response flags (see FlowContext.responseFlags()), unmodifiable

    • failure

      public Optional<ProxyFailure> failure()
      Returns why the proxy had to answer itself (see FlowContext.failure()), or empty.
      Returns:
      why the proxy had to answer itself (see FlowContext.failure()), or empty

    • responseCodeDetails

      public String responseCodeDetails()
      Returns the response code details (see FlowContext.responseCodeDetails()), or null.
      Returns:
      the response code details (see FlowContext.responseCodeDetails()), or null

    • trace

      public FlowTrace trace()
      The exchange's distributed trace (FlowTracer), whose ids access logs show as %TRACE_ID% and %SPAN_ID%; FlowTrace.NONE when nothing traced it.
      Returns:
      the trace

    • uniqueId

      public String uniqueId()
      An id unique to this exchange or flow: its trace's request id (X-Request-Id) when it has one, else a random UUID made the first time it is asked for.
      Returns:
      the unique id

    • toString

      public String toString()
      Overrides:
      toString in class Object