Package org.microproxy

Class HttpFiltersChain.Chained

java.lang.Object

org.microproxy.HttpFiltersChain.Chained

All Implemented Interfaces:

HttpFilters

Enclosing class:

HttpFiltersChain

public static final class HttpFiltersChain.Chained
extends Object
implements HttpFilters

The filters of several sources for one request.

Method Summary

Modifier and Type	Method	Description
RetryBackoff	chainedProxyRetryBackoff()	The backoff between this request's connection attempts when a chained proxy (or the direct fallback) fails and the next route the ChainedProxyManager offered is tried, instead of the server's (HttpProxyServerBootstrap.withChainedProxyRetryBackoff(RetryBackoff)).
HttpResponse	clientToProxyRequest(HttpObject httpObject)	Filters requests on their way from the client to the proxy.
void	exchangeEnded(boolean completed)	Called exactly once when this exchange is over, however it ended, so per-exchange resources (a concurrency permit, a span, a temporary file) can be released: after HttpFilters.proxyToClientResponseSent(org.microproxy.http.HttpResponse, org.microproxy.ResponseSource) for a response written in full, whoever made it (the server, the proxy's failure answer, a filter's short-circuit, the cache); for a CONNECT that became a byte tunnel, or a request upgraded with 101 (WebSocket), when the tunnel closes; for an intercepted CONNECT, once interception starts: the requests inside the session are exchanges of their own; when the exchange was abandoned: the client disconnected, the server failed half-way through the response, a filter returned null, a filter or the proxy threw, or the proxy was stopped.
WebSocketFrame	filterWebSocketFrame(WebSocketFrame frame, boolean fromClient)	Rewrites or drops a WebSocket frame on an upgraded connection, after HttpFilters.webSocketFrameReceived(WebSocketFrame, boolean) has seen it.
WebSocketMessage	filterWebSocketMessage(WebSocketMessage message, boolean fromClient)	Rewrites or drops a whole WebSocket message on an upgraded connection.
List<WebSocketMessage>	filterWebSocketMessages(WebSocketMessage message, boolean fromClient)	The messages to send in place of message, in order.
List<HttpFilters>	members()	Returns the member filters, in order.
HttpObject	proxyToClientResponse(HttpObject httpObject)	Filters responses on their way from the proxy to the client.
void	proxyToClientResponseSent(HttpResponse response, ResponseSource source)	Called once the whole response has been written to the client, whoever made it: the server, the proxy, a filter or the cache.
boolean	proxyToServerAllowMitm()	Whether this CONNECT request may be intercepted when a MitmManager is configured.
boolean	proxyToServerAllowMitm(ClientHello clientHello)	Whether this CONNECT (or transparent TLS connection) may be intercepted, now that the client's TLS ClientHello is known: return false to tunnel the bytes untouched, so the client sees the real server's certificate.
boolean	proxyToServerAllowOfflineMitm()	For a CONNECT that is being intercepted but whose server cannot be reached: return true to intercept it anyway, with a certificate made from the requested host name alone, so these filters can answer the requests inside the session (from a cache, for example).
void	proxyToServerConnectionFailed()	Called when an upstream connection attempt fails.
void	proxyToServerConnectionSSLHandshakeStarted()	Called before the upstream TLS handshake starts.
void	proxyToServerConnectionStarted()	Called before an upstream TCP connection attempt starts.
void	proxyToServerConnectionSucceeded(FullFlowContext serverContext)	Called once the connection to the server (or chained proxy) is ready for traffic.
Duration	proxyToServerConnectTimeout()	The connect timeout for this request's connection attempts: to the server, or to each chained proxy tried.
HttpResponse	proxyToServerFailure(ProxyFailure failure)	Called when the proxy is about to answer this request itself because of failure (the server could not be reached, timed out or answered badly, the request was refused, ...).
MitmServerHandshake	proxyToServerMitmHandshake()	When the proxy runs its TLS handshake with the server for this CONNECT, which it intercepts, instead of what the ProtocolPolicy of the client's protocol says (ProtocolPolicy.mitmServerHandshake()): MitmServerHandshake.DEFERRED after answering it and reading the client's ClientHello, MitmServerHandshake.EAGER before answering it.
HttpResponse	proxyToServerRequest(HttpObject httpObject)	Filters requests on their way from the proxy to the server, after the proxy has rewritten headers.
void	proxyToServerRequestSending()	Called just before the request head is written to the server.
void	proxyToServerRequestSent()	Called after the complete request, including its body, has been written to the server.
void	proxyToServerResolutionFailed(String hostAndPort)	Called when the upstream host name cannot be resolved.
InetSocketAddress	proxyToServerResolutionStarted(String hostAndPort)	Called before the server's host name is resolved.
void	proxyToServerResolutionSucceeded(String serverHostAndPort, InetSocketAddress resolvedRemoteAddress)	Called after the upstream host name is resolved.
Duration	proxyToServerTlsHandshakeTimeout()	The TLS handshake timeout for this request's upstream handshakes: with the server when the proxy speaks TLS to it (an intercepted CONNECT, an absolute https:// URL, HTTP/2 to the server), and with each TLS chained proxy tried (https:// and h2:// ones), including the server's handshake inside a tunnel through one.
TlsServerIdentity	proxyToServerTlsIdentity(String serverHostAndPort)	The TLS identity of this request's connection to serverHostAndPort: the server name sent as SNI and the host the server's certificate is verified against, when they are not the request's host, e.g. for a route that dials an IP address or an internal load balancer (HttpFilters.proxyToServerResolutionStarted(java.lang.String), a resolver, a chained proxy) while the service presents a certificate for its public name.
int	requestBufferSizeInBytes(HttpRequest request)	Asks for this request to be buffered, before HttpFilters.clientToProxyRequest(org.microproxy.http.HttpObject) sees it: return a positive size to receive the head and body as one FullHttpRequest, or 0 to stream.
int	responseBufferSizeInBytes(HttpResponse response)	Asks for this response to be buffered, after seeing its head: return a positive size to receive the head and body as one FullHttpResponse in HttpFilters.serverToProxyResponse(org.microproxy.http.HttpObject), or 0 to stream.
HttpObject	serverToProxyResponse(HttpObject httpObject)	Filters responses on their way from the server to the proxy.
void	serverToProxyResponseReceived()	Called when the server has finished sending a response.
void	serverToProxyResponseReceiving()	Called when the server begins sending a response.
void	serverToProxyResponseTimedOut()	Called when the server did not respond within the idle timeout.
void	webSocketFrameReceived(Supplier<byte[]> frameBytes, boolean fromClient)	LittleProxy-compatible form of HttpFilters.webSocketFrameReceived(WebSocketFrame, boolean): supplies the raw frame bytes as on the wire (header and still-masked payload).
void	webSocketFrameReceived(WebSocketFrame frame, boolean fromClient)	Called for every WebSocket frame relayed after this request was upgraded (101 Switching Protocols with Upgrade: websocket), including inside intercepted TLS sessions.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

members

public List<HttpFilters> members()

Returns the member filters, in order.

Returns:

the member filters, in order

requestBufferSizeInBytes

public int requestBufferSizeInBytes(HttpRequest request)

Description copied from interface: HttpFilters

Asks for this request to be buffered, before HttpFilters.clientToProxyRequest(org.microproxy.http.HttpObject) sees it: return a positive size to receive the head and body as one FullHttpRequest, or 0 to stream. A body larger than the size is answered with 413. Not consulted for CONNECT, or when the source already buffers.

Specified by:

requestBufferSizeInBytes in interface HttpFilters

Parameters:

request - the request being handled

Returns:

the requested body buffer limit in bytes, or zero to stream

clientToProxyRequest

public HttpResponse clientToProxyRequest(HttpObject httpObject)

Description copied from interface: HttpFilters

Filters requests on their way from the client to the proxy. Return a response to answer the client directly ("short-circuit") without contacting the server; only the return value for the request head is honoured.

Specified by:

clientToProxyRequest in interface HttpFilters

Parameters:

httpObject - the request head or body piece

Returns:

a short-circuit response, or null to continue forwarding

proxyToServerRequest

public HttpResponse proxyToServerRequest(HttpObject httpObject)

Description copied from interface: HttpFilters

Filters requests on their way from the proxy to the server, after the proxy has rewritten headers. Return a response to short-circuit; only the return value for the request head is honoured.

Specified by:

proxyToServerRequest in interface HttpFilters

Parameters:

httpObject - the request head or body piece

Returns:

a short-circuit response, or null to continue forwarding

proxyToServerRequestSending

public void proxyToServerRequestSending()

Description copied from interface: HttpFilters

Called just before the request head is written to the server.

Specified by:

proxyToServerRequestSending in interface HttpFilters

proxyToServerRequestSent

public void proxyToServerRequestSent()

Description copied from interface: HttpFilters

Called after the complete request, including its body, has been written to the server.

Specified by:

proxyToServerRequestSent in interface HttpFilters

serverToProxyResponse

public HttpObject serverToProxyResponse(HttpObject httpObject)

Description copied from interface: HttpFilters

Filters responses on their way from the server to the proxy. Return the (possibly modified or replaced) object, or null to abort and disconnect the client. A CONNECT's 200 Connection established, which the proxy makes once the server is connected, comes here too (then to HttpFilters.proxyToClientResponse(org.microproxy.http.HttpObject)), as the server's acceptance: a filter may turn it into a refusal. Not with HttpProxyServerBootstrap.withLittleProxyCompatibility(boolean), as in LittleProxy.

Specified by:

serverToProxyResponse in interface HttpFilters

Parameters:

httpObject - the response head or body piece

Returns:

the object to forward, or null to abort the exchange

responseBufferSizeInBytes

public int responseBufferSizeInBytes(HttpResponse response)

Description copied from interface: HttpFilters

Asks for this response to be buffered, after seeing its head: return a positive size to receive the head and body as one FullHttpResponse in HttpFilters.serverToProxyResponse(org.microproxy.http.HttpObject), or 0 to stream. Unlike HttpFiltersSource.getMaximumResponseBufferSizeInBytes(), a body larger than the size is not an error: it is streamed through as usual. Ignored when the source already buffers.

Specified by:

responseBufferSizeInBytes in interface HttpFilters

Parameters:

response - the response being handled

Returns:

the requested body buffer limit in bytes, or zero to stream

serverToProxyResponseTimedOut

public void serverToProxyResponseTimedOut()

Description copied from interface: HttpFilters

Called when the server did not respond within the idle timeout.

Specified by:

serverToProxyResponseTimedOut in interface HttpFilters

proxyToServerFailure

public HttpResponse proxyToServerFailure(ProxyFailure failure)

Description copied from interface: HttpFilters

Called when the proxy is about to answer this request itself because of failure (the server could not be reached, timed out or answered badly, the request was refused, ...). Return a response to send instead of the proxy's default, or null. It is framed by the proxy and passes HttpFilters.proxyToClientResponse(org.microproxy.http.HttpObject) like any proxy-made response. Filters are asked before the FailureResponder; the more specific callbacks (HttpFilters.proxyToServerResolutionFailed(java.lang.String), HttpFilters.proxyToServerConnectionFailed(), HttpFilters.serverToProxyResponseTimedOut()) are still called as well, before this one.

Not called when the failure happens after the response has started (the client connection is closed instead), or for requests the proxy could not parse.

Specified by:

proxyToServerFailure in interface HttpFilters

Parameters:

failure - the proxy failure to answer

Returns:

a replacement failure response, or null for the default

serverToProxyResponseReceiving

public void serverToProxyResponseReceiving()

Description copied from interface: HttpFilters

Called when the server begins sending a response.

Specified by:

serverToProxyResponseReceiving in interface HttpFilters

serverToProxyResponseReceived

public void serverToProxyResponseReceived()

Description copied from interface: HttpFilters

Called when the server has finished sending a response.

Specified by:

serverToProxyResponseReceived in interface HttpFilters

proxyToClientResponse

public HttpObject proxyToClientResponse(HttpObject httpObject)

Description copied from interface: HttpFilters

Filters responses on their way from the proxy to the client. Return the (possibly modified) object, or null to abort and disconnect the client.

This also sees the responses the proxy answers with itself, its error responses and the short-circuit responses returned from earlier hooks, as the ProtocolPolicy of the client's protocol says (ProtocolPolicy.generatedResponses()): by default a replacement is sent; it may be limited to changes in place (GeneratedResponses.IN_PLACE), or keep them from this hook (GeneratedResponses.SKIP). FlowContext.responseSource() says where the response came from. The proxy's 200 to a CONNECT passes HttpFilters.serverToProxyResponse(org.microproxy.http.HttpObject) and this hook (unless ProtocolPolicy.filterConnectAnswer() is off); its 407 challenge reaches no filter. To change the proxy's own error pages, use HttpFilters.proxyToServerFailure(org.microproxy.ProxyFailure) or a FailureResponder.

Specified by:

proxyToClientResponse in interface HttpFilters

Parameters:

httpObject - the response head or body piece

Returns:

the object to send, or null to abort the exchange

proxyToClientResponseSent

public void proxyToClientResponseSent(HttpResponse response,
 ResponseSource source)

Description copied from interface: HttpFilters

Called once the whole response has been written to the client, whoever made it: the server, the proxy, a filter or the cache. FlowContext.timings() then covers the whole exchange. Not called when the exchange was aborted or failed half-way through the response, or for the 407 challenge sent before filters are created.

Specified by:

proxyToClientResponseSent in interface HttpFilters

Parameters:

response - the response head as it was sent (after every filter)

source - where it came from, as reported to ActivityTracker.responseSentToClient(FlowContext, HttpResponse, ResponseSource)

exchangeEnded

public void exchangeEnded(boolean completed)

Description copied from interface: HttpFilters

Called exactly once when this exchange is over, however it ended, so per-exchange resources (a concurrency permit, a span, a temporary file) can be released:

• after HttpFilters.proxyToClientResponseSent(org.microproxy.http.HttpResponse, org.microproxy.ResponseSource) for a response written in full, whoever made it (the server, the proxy's failure answer, a filter's short-circuit, the cache);
• for a CONNECT that became a byte tunnel, or a request upgraded with 101 (WebSocket), when the tunnel closes;
• for an intercepted CONNECT, once interception starts: the requests inside the session are exchanges of their own;
• when the exchange was abandoned: the client disconnected, the server failed half-way through the response, a filter returned null, a filter or the proxy threw, or the proxy was stopped.

It runs on the connection's thread before the next request on the connection is read. Exceptions it throws are logged and ignored.

Specified by:

exchangeEnded in interface HttpFilters

Parameters:

completed - whether the response was written in full (HttpFilters.proxyToClientResponseSent(org.microproxy.http.HttpResponse, org.microproxy.ResponseSource) was called)

proxyToServerResolutionStarted

public InetSocketAddress proxyToServerResolutionStarted(String hostAndPort)

Description copied from interface: HttpFilters

Called before the server's host name is resolved. Return an address to skip resolution and connect there instead.

Specified by:

proxyToServerResolutionStarted in interface HttpFilters

Parameters:

hostAndPort - the destination host and port being resolved

Returns:

the address to connect to, or null to resolve normally

proxyToServerResolutionFailed

public void proxyToServerResolutionFailed(String hostAndPort)

Description copied from interface: HttpFilters

Called when the upstream host name cannot be resolved.

Specified by:

proxyToServerResolutionFailed in interface HttpFilters

Parameters:

hostAndPort - the destination host and port, or null when unavailable

proxyToServerResolutionSucceeded

public void proxyToServerResolutionSucceeded(String serverHostAndPort,
 InetSocketAddress resolvedRemoteAddress)

Description copied from interface: HttpFilters

Called after the upstream host name is resolved.

Specified by:

proxyToServerResolutionSucceeded in interface HttpFilters

Parameters:

serverHostAndPort - the requested server host and port

resolvedRemoteAddress - the resolved address to connect to

proxyToServerConnectTimeout

public Duration proxyToServerConnectTimeout()

Description copied from interface: HttpFilters

The connect timeout for this request's connection attempts: to the server, or to each chained proxy tried. null (the default), zero or a negative duration keeps the server's (HttpProxyServerBootstrap.withConnectTimeout(int)). Asked when the request needs a new connection, after HttpFilters.proxyToServerRequest(org.microproxy.http.HttpObject); a request that reuses a connection makes none. It bounds the TCP connect only, not name resolution or TLS handshakes (HttpFilters.proxyToServerTlsHandshakeTimeout()). In a HttpFiltersChain the shortest timeout wins.

Specified by:

proxyToServerConnectTimeout in interface HttpFilters

Returns:

the connect timeout override, or null for the server setting

proxyToServerTlsHandshakeTimeout

public Duration proxyToServerTlsHandshakeTimeout()

Description copied from interface: HttpFilters

The TLS handshake timeout for this request's upstream handshakes: with the server when the proxy speaks TLS to it (an intercepted CONNECT, an absolute https:// URL, HTTP/2 to the server), and with each TLS chained proxy tried (https:// and h2:// ones), including the server's handshake inside a tunnel through one. null (the default), zero or a negative duration keeps the server's (HttpProxyServerBootstrap.withTlsHandshakeTimeout(java.time.Duration)); a request cannot turn the limit off. Asked when the request needs a new connection, after HttpFilters.proxyToServerRequest(org.microproxy.http.HttpObject); a request that reuses a connection makes no handshake. A handshake that runs out of time fails the attempt with ProxyFailure.TlsFailed (a SocketTimeoutException cause, response flag UF), and the next chained proxy, if any, is tried, as after other failures. In a HttpFiltersChain the shortest timeout wins.

Upstream HTTP/3 (QUIC) handshakes keep Http3Options.upstreamHandshakeTimeout(): their connections are shared by every client, and one that is not made in time does not fail the request but sends it over TCP, whose TLS handshake this timeout then bounds.

Specified by:

proxyToServerTlsHandshakeTimeout in interface HttpFilters

Returns:

the TLS handshake timeout override, or null for the server setting

proxyToServerMitmHandshake

public MitmServerHandshake proxyToServerMitmHandshake()

Description copied from interface: HttpFilters

When the proxy runs its TLS handshake with the server for this CONNECT, which it intercepts, instead of what the ProtocolPolicy of the client's protocol says (ProtocolPolicy.mitmServerHandshake()): MitmServerHandshake.DEFERRED after answering it and reading the client's ClientHello, MitmServerHandshake.EAGER before answering it. null (the default) keeps the policy's. Asked once the proxy has decided to intercept the CONNECT, after proxy authentication, HttpFilters.clientToProxyRequest(org.microproxy.http.HttpObject) and HttpFilters.proxyToServerAllowMitm(), so the choice can depend on the authenticated user (FlowContext.getClientDetails()) or anything the request says. In a HttpFiltersChain the first filter that returns a choice wins.

Specified by:

proxyToServerMitmHandshake in interface HttpFilters

Returns:

when the server's handshake runs, or null for the policy's choice

chainedProxyRetryBackoff

public RetryBackoff chainedProxyRetryBackoff()

Description copied from interface: HttpFilters

The backoff between this request's connection attempts when a chained proxy (or the direct fallback) fails and the next route the ChainedProxyManager offered is tried, instead of the server's (HttpProxyServerBootstrap.withChainedProxyRetryBackoff(RetryBackoff)). null (the default) keeps the server's; RetryBackoff.none() tries the next route at once. Asked when an attempt has failed and another route remains, so a request that connects on its first attempt never asks. The server's limits apply to it too: no wait before the first attempt or after the last, the policy's budget of waiting in all (by default at most 30 seconds or the connect timeout; see RetryBackoff.withBudget(java.time.Duration) and RetryBackoff.unbudgeted()), and a client that leaves ends the wait. In a HttpFiltersChain the first filter that returns a backoff wins.

Specified by:

chainedProxyRetryBackoff in interface HttpFilters

Returns:

the retry backoff override, or null for the server setting

proxyToServerConnectionStarted

public void proxyToServerConnectionStarted()

Description copied from interface: HttpFilters

Called before an upstream TCP connection attempt starts.

Specified by:

proxyToServerConnectionStarted in interface HttpFilters

proxyToServerConnectionSSLHandshakeStarted

public void proxyToServerConnectionSSLHandshakeStarted()

Description copied from interface: HttpFilters

Called before the upstream TLS handshake starts.

Specified by:

proxyToServerConnectionSSLHandshakeStarted in interface HttpFilters

proxyToServerConnectionFailed

public void proxyToServerConnectionFailed()

Description copied from interface: HttpFilters

Called when an upstream connection attempt fails.

Specified by:

proxyToServerConnectionFailed in interface HttpFilters

proxyToServerConnectionSucceeded

public void proxyToServerConnectionSucceeded(FullFlowContext serverContext)

Description copied from interface: HttpFilters

Called once the connection to the server (or chained proxy) is ready for traffic.

Specified by:

proxyToServerConnectionSucceeded in interface HttpFilters

Parameters:

serverContext - the server connection context

proxyToServerAllowMitm

public boolean proxyToServerAllowMitm()

Description copied from interface: HttpFilters

Whether this CONNECT request may be intercepted when a MitmManager is configured. Return false to tunnel the bytes untouched instead.

Specified by:

proxyToServerAllowMitm in interface HttpFilters

Returns:

whether this CONNECT may be intercepted

proxyToServerAllowMitm

public boolean proxyToServerAllowMitm(ClientHello clientHello)

Description copied from interface: HttpFilters

Whether this CONNECT (or transparent TLS connection) may be intercepted, now that the client's TLS ClientHello is known: return false to tunnel the bytes untouched, so the client sees the real server's certificate. Called once the client has sent its ClientHello, after HttpFilters.proxyToServerAllowMitm(), the host rules (HttpProxyServerBootstrap.withIgnoreHosts(java.lang.String...), HttpProxyServerBootstrap.withAllowHosts(java.lang.String...)) and MitmManager.shouldIntercept(org.microproxy.ClientHello, org.microproxy.FlowContext) have allowed interception; not called for clients that do not speak TLS. True by default.

Specified by:

proxyToServerAllowMitm in interface HttpFilters

Parameters:

clientHello - the client's ClientHello, with its server name (SNI) and ALPN protocols

Returns:

whether the connection may be intercepted

proxyToServerAllowOfflineMitm

public boolean proxyToServerAllowOfflineMitm()

Description copied from interface: HttpFilters

For a CONNECT that is being intercepted but whose server cannot be reached: return true to intercept it anyway, with a certificate made from the requested host name alone, so these filters can answer the requests inside the session (from a cache, for example). Those requests fail as usual if they do need the server.

Specified by:

proxyToServerAllowOfflineMitm in interface HttpFilters

Returns:

whether interception may proceed without an upstream connection

proxyToServerTlsIdentity

public TlsServerIdentity proxyToServerTlsIdentity(String serverHostAndPort)

Description copied from interface: HttpFilters

The TLS identity of this request's connection to serverHostAndPort: the server name sent as SNI and the host the server's certificate is verified against, when they are not the request's host, e.g. for a route that dials an IP address or an internal load balancer (HttpFilters.proxyToServerResolutionStarted(java.lang.String), a resolver, a chained proxy) while the service presents a certificate for its public name. null (the default) keeps both derived from the request's host. The address dialled is not affected, nor is the TLS with a chained proxy itself (ChainedProxy.requiresEncryption()).

Asked for requests that reach the server over TLS (intercepted sessions, TLS origination, a reverse proxy's https:// upstream) before a server connection is chosen, and for an intercepted CONNECT before the proxy's handshake with its target. A connection made with one identity serves only requests with the same identity: it is never reused, pooled or coalesced (RFC 9113 section 9.1.1) for another, and a request with an identity does not go over HTTP/3. The certificate is still validated with the MITM manager's trust; only the names change. In a HttpFiltersChain the first member that returns an identity wins.

Specified by:

proxyToServerTlsIdentity in interface HttpFilters

Parameters:

serverHostAndPort - the server's host:port

Returns:

the identity, or null for the default

webSocketFrameReceived

public void webSocketFrameReceived(WebSocketFrame frame,
 boolean fromClient)

Description copied from interface: HttpFilters

Called for every WebSocket frame relayed after this request was upgraded (101 Switching Protocols with Upgrade: websocket), including inside intercepted TLS sessions. Frames are observed, not modified: they are forwarded unchanged after this returns. The two directions are relayed on separate virtual threads, so this may be called concurrently for client and server frames.

Frames are only parsed when the filters class overrides one of the two webSocketFrameReceived methods; otherwise upgraded connections are relayed as raw bytes.

Frames whose payload exceeds HttpProxyServerBootstrap.withMaxWebSocketFrameBufferSize(int) are streamed through and reported with WebSocketFrame.isTruncated() set.

The default implementation delegates to the LittleProxy-compatible HttpFilters.webSocketFrameReceived(Supplier, boolean).

Specified by:

webSocketFrameReceived in interface HttpFilters

Parameters:

frame - the WebSocket frame

fromClient - true for client-to-server frames

webSocketFrameReceived

public void webSocketFrameReceived(Supplier<byte[]> frameBytes,
 boolean fromClient)

Description copied from interface: HttpFilters

LittleProxy-compatible form of HttpFilters.webSocketFrameReceived(WebSocketFrame, boolean): supplies the raw frame bytes as on the wire (header and still-masked payload).

Specified by:

webSocketFrameReceived in interface HttpFilters

Parameters:

frameBytes - the supplier of raw frame bytes, including the header and masked payload

fromClient - whether the frame came from the client

filterWebSocketFrame

public WebSocketFrame filterWebSocketFrame(WebSocketFrame frame,
 boolean fromClient)

Description copied from interface: HttpFilters

Rewrites or drops a WebSocket frame on an upgraded connection, after HttpFilters.webSocketFrameReceived(WebSocketFrame, boolean) has seen it. Return frame to forward it unchanged, another frame (WebSocketFrame.withText(String), WebSocketFrame.text(String), ...) to send instead, or null to drop it. The proxy masks frames it sends towards the server.

• Frames are rewritten one at a time; a message split across continuation frames is seen piece by piece. HttpFilters.filterWebSocketMessage(org.microproxy.http.WebSocketMessage, boolean) sees whole messages.
• When a filters class overrides this method, payloads compressed with permessage-deflate (RFC 7692) arrive inflated, with RSV1 clear, and the proxy compresses what it forwards again. The proxy keeps only permessage-deflate offers in the upgrade request's Sec-WebSocket-Extensions, since it could not read frames of other extensions.
• A frame larger than HttpProxyServerBootstrap.withMaxWebSocketFrameBufferSize(int) arrives truncated: returning it streams it through, null discards it, and a replacement frame is sent in its place. Compressed frames, and frames of a message that HttpFilters.filterWebSocketMessage(org.microproxy.http.WebSocketMessage, boolean) will see, are buffered up to HttpProxyServerBootstrap.withMaxWebSocketMessageSize(int) instead.
• Like the observer, this is called concurrently for client and server frames.

Specified by:

filterWebSocketFrame in interface HttpFilters

Parameters:

frame - the WebSocket frame

fromClient - true for client-to-server frames

Returns:

the frame to forward, or null to drop it

filterWebSocketMessage

public WebSocketMessage filterWebSocketMessage(WebSocketMessage message,
 boolean fromClient)

Description copied from interface: HttpFilters

Rewrites or drops a whole WebSocket message on an upgraded connection. A text or binary message split across continuation frames arrives joined, and inflated when the connection uses permessage-deflate (RFC 7692). Return message to forward it unchanged, another message (WebSocketMessage.withText(String), WebSocketMessage.text(String, boolean), ...) to send instead, or null to drop it.

• Messages are only joined when a filters class overrides this method or HttpFilters.filterWebSocketMessages(org.microproxy.http.WebSocketMessage, boolean); otherwise frames are relayed one at a time.
• With HttpFilters.filterWebSocketFrame(org.microproxy.http.WebSocketFrame, boolean) as well, the frame hook sees each frame first, and this hook sees the message joined from what the frame hook returned. Control frames (ping, pong, close) that arrive between a message's frames reach the frame hook and are forwarded at once, without waiting for the message.
• A message returned unchanged keeps the fragmentation it arrived with; any other message is sent as a single frame (masked towards the server, compressed when the sender's message was).
• A message larger than HttpProxyServerBootstrap.withMaxWebSocketMessageSize(int), joined or inflated, fails the connection: both peers get a close frame with status 1009 (message too big).
• Like the frame hooks, this is called concurrently for client and server messages.

Specified by:

filterWebSocketMessage in interface HttpFilters

Parameters:

message - the whole message

fromClient - true for client-to-server messages

Returns:

the message to forward, or null to drop it

filterWebSocketMessages

public List<WebSocketMessage> filterWebSocketMessages(WebSocketMessage message,
 boolean fromClient)

Description copied from interface: HttpFilters

The messages to send in place of message, in order. Each goes towards the server when its WebSocketMessage.fromClient() is true and towards the client otherwise, so a filter can answer a message itself (message.withFromClient(!fromClient)) or send extra ones either way. An empty list drops the message.

The default returns what HttpFilters.filterWebSocketMessage(org.microproxy.http.WebSocketMessage, boolean) returns, if anything; override this one instead to send several messages.

Specified by:

filterWebSocketMessages in interface HttpFilters

Parameters:

message - the whole message

fromClient - true for client-to-server messages

Returns:

the messages to send