Package org.microproxy

Interface HttpProxyServer

All Superinterfaces:
AutoCloseable
public interface HttpProxyServer extends AutoCloseable
A running proxy. Obtain one from MicroProxy.bootstrap().

  • Method Details

    • getIdleConnectionTimeout

      Duration getIdleConnectionTimeout()
      Returns the maximum time a connection may remain idle.
      Returns:
      the maximum time a connection may remain idle

    • setIdleConnectionTimeout

      void setIdleConnectionTimeout(Duration idleConnectionTimeout)
      Sets the maximum time a connection may remain idle.
      Parameters:
      idleConnectionTimeout - the maximum time a connection may remain idle

    • getConnectTimeout

      int getConnectTimeout()
      Returns connect timeout for outbound connections in milliseconds (0 = system default).
      Returns:
      connect timeout for outbound connections in milliseconds (0 = system default)

    • setConnectTimeout

      void setConnectTimeout(int connectTimeoutMs)
      Sets the timeout for outbound connection attempts.
      Parameters:
      connectTimeoutMs - the outbound connect timeout in milliseconds; zero uses the system default

    • clone

      HttpProxyServerBootstrap clone()
      Returns a bootstrap preconfigured like this server, listening on the next port (or an ephemeral port if this one is ephemeral).
      Returns:
      a bootstrap with this server's settings and the next listening port

    • stop

      void stop()
      Stops accepting connections and gracefully closes existing ones: idle connections close now, HTTP/2 and HTTP/3 ones are sent GOAWAY, and exchanges in progress get up to the drain time to finish before every connection is closed. The state is then ServerState.STOPPED.

    • abort

      void abort()
      Stops immediately, closing all connections without waiting.

    • state

      default ServerState state()
      Returns where the proxy is in its life: ServerState.LIVE once started, until it drains or stops.
      Returns:
      where the proxy is in its life: ServerState.LIVE once started, until it drains or stops

    • drain

      default void drain(Duration drainTime)
      Drains the proxy, as Envoy's graceful listener drain does, and returns when the drain is over. The state turns ServerState.DRAINING (so the admin /ready fails), the listeners keep accepting, and new requests are told to go elsewhere as the drain strategy says: an HTTP/1 response gets Connection: close, an HTTP/2 or HTTP/3 connection is sent GOAWAY. Exchanges in progress get until drainTime is over; then the listeners close, and so does every connection still open. The proxy stays DRAINING until stop().
      Parameters:
      drainTime - how long the drain lasts
      Throws:
      UnsupportedOperationException - if this server cannot drain

    • stopListeners

      default void stopListeners()
      Stops accepting new connections now, as Envoy's non-graceful /drain_listeners does: the TCP listener closes and the UDP ones (HTTP/3, transparent QUIC) refuse new QUIC connections; open connections are left alone. The state turns ServerState.DRAINING.
      Throws:
      UnsupportedOperationException - if this server cannot

    • getDrainTime

      default Duration getDrainTime()
      Returns how long stop() lets exchanges in progress finish (see HttpProxyServerBootstrap.withDrainTime(java.time.Duration)).
      Returns:
      how long stop() lets exchanges in progress finish (see HttpProxyServerBootstrap.withDrainTime(java.time.Duration))

    • setHealthCheckFailed

      default void setHealthCheckFailed(boolean failed)
      Fails or restores the proxy's health check, as Envoy's admin /healthcheck/fail and /healthcheck/ok do. While it fails, the admin /ready answers 503, the health-check path answers 503, and every new request drains its connection, as when draining with DrainStrategy.IMMEDIATE.
      Parameters:
      failed - whether the health check fails
      Throws:
      UnsupportedOperationException - if this server has no health check

    • isHealthCheckFailed

      default boolean isHealthCheckFailed()
      Returns whether the health check has been failed with setHealthCheckFailed(boolean).
      Returns:
      whether the health check has been failed with setHealthCheckFailed(boolean)

    • getAdminAddress

      default InetSocketAddress getAdminAddress()
      The admin listener's address (HttpProxyServerBootstrap.withAdmin(java.net.InetSocketAddress)), with the port it bound.
      Returns:
      the address, or null without an admin listener

    • closeOnStop

      void closeOnStop(AutoCloseable resource)
      Closes resource when the server stops, after its connections have finished (or been closed): for things that outlive single requests, such as a WARC recorder. Resources close in the reverse order they were added.
      Parameters:
      resource - the resource to close when the server stops

    • getListenAddress

      InetSocketAddress getListenAddress()
      Returns the bound proxy listener address.
      Returns:
      the bound proxy listener address

    • getProtocolPolicy

      default ProtocolPolicy getProtocolPolicy(HttpVersion clientVersion)
      The ProtocolPolicy the server applies to the exchanges of clients that speak clientVersion (HTTP/1.0 and 1.1 alike), every field resolved: the protocol's own policy over the one for all protocols over the protocol's defaults (see ProtocolPolicy). A request's filters may still decide some fields for that request alone.
      Parameters:
      clientVersion - the protocol the client speaks to the proxy
      Returns:
      the effective policy, every field set

    • getTransparentQuicAddress

      default InetSocketAddress getTransparentQuicAddress()
      The UDP address of the transparent QUIC listener (HttpProxyServerBootstrap.withTransparentQuicPort(int)), with the port it bound.
      Returns:
      the address, or null without the listener

    • setThrottle

      void setThrottle(long readThrottleBytesPerSecond, long writeThrottleBytesPerSecond)
      Changes global bandwidth limits for server traffic; 0 means unlimited.
      Parameters:
      readThrottleBytesPerSecond - the inbound bandwidth limit in bytes per second, or zero for unlimited
      writeThrottleBytesPerSecond - the outbound bandwidth limit in bytes per second, or zero for unlimited

    • getServerConnectionPoolMetrics

      default PoolMetrics getServerConnectionPoolMetrics()
      Returns statistics of the shared server connection pool, or null if it is disabled.
      Returns:
      statistics of the shared server connection pool, or null if it is disabled

    • getStats

      default StatsRegistry getStats()
      The proxy's metrics, as HttpProxyServerBootstrap.withStats(org.microproxy.stats.StatsRegistry) or HttpProxyServerBootstrap.withMetrics(boolean) configured them.
      Returns:
      the registry, StatsRegistry.NOOP without metrics

    • close

      default void close()
      Specified by:
      close in interface AutoCloseable