Package org.mockserver.mock.breakpoint

Class StreamFrameCallbackDispatcher

java.lang.Object

org.mockserver.mock.breakpoint.StreamFrameCallbackDispatcher

public class StreamFrameCallbackDispatcher
extends Object

Dispatches stream-frame breakpoint-held frames to a callback WebSocket client for interactive resolution. This is the per-frame analogue of BreakpointCallbackDispatcher (which handles buffered REQUEST/RESPONSE phases).

Protocol (frozen contract)

• Server to client: a PausedStreamFrameDTO carrying the correlationId, streamId, sequenceNumber, direction, phase, body (Base64), and light request context.
• Client to server: a StreamFrameDecisionDTO carrying the correlationId, action (CONTINUE/MODIFY/DROP/INJECT/CLOSE), and optional body (Base64, for MODIFY/INJECT).

Safety rails

• Timeout: auto-continues after Configuration.breakpointTimeoutMillis().
• Max-held cap: shared with BreakpointCallbackDispatcher.
• Disconnect: all in-flight dispatches for a disconnected client are auto-completed to CONTINUE via autoCompleteForClient(String).

Frame ordering

Frames within a stream are dispatched one at a time: the caller parks the frame and chains its continuation on the returned future. The existing backpressure mechanisms (streaming body requestMore(), autoRead=false, withhold ctx.read()) ensure that the next frame is not delivered until the current one resolves — preserving the same ordering guarantees as the REST-park path.

This class is thread-safe. Correlation handlers are registered before the WS message is sent, and cleaned up on completion/timeout/disconnect.

Constructor Summary

Constructors

Constructor	Description
StreamFrameCallbackDispatcher()

Method Summary

Modifier and Type	Method	Description
int	autoCompleteForClient(String clientId)	Auto-completes all in-flight WS stream frame dispatches for the given client with CONTINUE.
CompletableFuture<StreamFrameDecision>	dispatchFrame(String clientId, String streamId, int sequenceNumber, PausedStreamFrame.Direction direction, BreakpointPhase phase, byte[] capturedBytes, String requestMethod, String requestPath, WebSocketClientRegistry webSocketClientRegistry, Configuration configuration, MockServerLogger logger)	Deprecated. use the overload that includes breakpointId and requestTimestamp
CompletableFuture<StreamFrameDecision>	dispatchFrame(String clientId, String breakpointId, String streamId, int sequenceNumber, PausedStreamFrame.Direction direction, BreakpointPhase phase, byte[] capturedBytes, String requestMethod, String requestPath, Long requestTimestamp, WebSocketClientRegistry webSocketClientRegistry, Configuration configuration, MockServerLogger logger)	Dispatches a stream frame to a callback WebSocket client for interactive resolution, tagging the message with the matched breakpoint id and request timestamp.
CompletableFuture<StreamFrameDecision>	dispatchFrame(String clientId, String breakpointId, String streamId, int sequenceNumber, PausedStreamFrame.Direction direction, BreakpointPhase phase, byte[] capturedBytes, String requestMethod, String requestPath, WebSocketClientRegistry webSocketClientRegistry, Configuration configuration, MockServerLogger logger)	Deprecated. use the overload that includes requestTimestamp
static StreamFrameCallbackDispatcher	getInstance()
int	inFlightCount()	Returns the number of in-flight WS stream frame dispatches.
void	reset()	Resets all in-flight dispatches (auto-continue) — called on server reset.
CompletableFuture<StreamFrameDecision>	tryWsDispatch(BreakpointMatcher matchedBreakpoint, String streamId, int sequenceNumber, PausedStreamFrame.Direction direction, BreakpointPhase phase, byte[] capturedBytes, String requestMethod, String requestPath, Long requestTimestamp, Configuration configuration, MockServerLogger logger, WebSocketClientRegistry webSocketClientRegistry)	Overload of tryWsDispatch(org.mockserver.mock.breakpoint.BreakpointMatcher, java.lang.String, int, org.mockserver.mock.breakpoint.PausedStreamFrame.Direction, org.mockserver.mock.breakpoint.BreakpointPhase, byte[], java.lang.String, java.lang.String, org.mockserver.configuration.Configuration, org.mockserver.logging.MockServerLogger, org.mockserver.closurecallback.websocketregistry.WebSocketClientRegistry) that includes the request timestamp.
CompletableFuture<StreamFrameDecision>	tryWsDispatch(BreakpointMatcher matchedBreakpoint, String streamId, int sequenceNumber, PausedStreamFrame.Direction direction, BreakpointPhase phase, byte[] capturedBytes, String requestMethod, String requestPath, Configuration configuration, MockServerLogger logger, WebSocketClientRegistry webSocketClientRegistry)	Convenience method that checks whether the given matched breakpoint should use WS-callback dispatch (non-null clientId + registry available), and if so, dispatches the frame.

Methods inherited from class java.lang.Object

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

Constructor Details

StreamFrameCallbackDispatcher

public StreamFrameCallbackDispatcher()

Method Details

getInstance

public static StreamFrameCallbackDispatcher getInstance()

dispatchFrame

public CompletableFuture<StreamFrameDecision> dispatchFrame(String clientId,
 String streamId,
 int sequenceNumber,
 PausedStreamFrame.Direction direction,
 BreakpointPhase phase,
 byte[] capturedBytes,
 String requestMethod,
 String requestPath,
 WebSocketClientRegistry webSocketClientRegistry,
 Configuration configuration,
 MockServerLogger logger)

Deprecated.

use the overload that includes breakpointId and requestTimestamp

dispatchFrame

public CompletableFuture<StreamFrameDecision> dispatchFrame(String clientId,
 String breakpointId,
 String streamId,
 int sequenceNumber,
 PausedStreamFrame.Direction direction,
 BreakpointPhase phase,
 byte[] capturedBytes,
 String requestMethod,
 String requestPath,
 WebSocketClientRegistry webSocketClientRegistry,
 Configuration configuration,
 MockServerLogger logger)

Deprecated.

use the overload that includes requestTimestamp

dispatchFrame

public CompletableFuture<StreamFrameDecision> dispatchFrame(String clientId,
 String breakpointId,
 String streamId,
 int sequenceNumber,
 PausedStreamFrame.Direction direction,
 BreakpointPhase phase,
 byte[] capturedBytes,
 String requestMethod,
 String requestPath,
 Long requestTimestamp,
 WebSocketClientRegistry webSocketClientRegistry,
 Configuration configuration,
 MockServerLogger logger)

Dispatches a stream frame to a callback WebSocket client for interactive resolution, tagging the message with the matched breakpoint id and request timestamp.

Parameters:

clientId - the owning callback client

breakpointId - the matched breakpoint's id (may be null)

streamId - the stream this frame belongs to

sequenceNumber - 0-based sequence number within the stream

direction - INBOUND or OUTBOUND

phase - RESPONSE_STREAM or INBOUND_STREAM

capturedBytes - the frame payload bytes (already copied from ByteBuf)

requestMethod - HTTP method of the original request (nullable)

requestPath - path of the original request (nullable)

requestTimestamp - epoch-millis when MockServer first received the request (nullable)

webSocketClientRegistry - the WS registry for sending messages

configuration - for timeout and max-held

logger - for logging

Returns:

a future that completes with the stream frame decision, or null if the max-held cap is reached or the client is not connected

autoCompleteForClient

public int autoCompleteForClient(String clientId)

Auto-completes all in-flight WS stream frame dispatches for the given client with CONTINUE. Called when the client's WebSocket connection closes.

Parameters:

clientId - the disconnecting client

Returns:

the number of in-flight dispatches auto-completed

inFlightCount

public int inFlightCount()

Returns the number of in-flight WS stream frame dispatches.

reset

public void reset()

Resets all in-flight dispatches (auto-continue) — called on server reset.

Takes a snapshot and clears the map BEFORE completing futures, so that asynchronous whenComplete callbacks cannot race with subsequent dispatches that re-populate the map.

tryWsDispatch

public CompletableFuture<StreamFrameDecision> tryWsDispatch(BreakpointMatcher matchedBreakpoint,
 String streamId,
 int sequenceNumber,
 PausedStreamFrame.Direction direction,
 BreakpointPhase phase,
 byte[] capturedBytes,
 String requestMethod,
 String requestPath,
 Configuration configuration,
 MockServerLogger logger,
 WebSocketClientRegistry webSocketClientRegistry)

Convenience method that checks whether the given matched breakpoint should use WS-callback dispatch (non-null clientId + registry available), and if so, dispatches the frame. If WS dispatch is not applicable, returns null so the caller can fall through to the REST-park path.

This consolidates the "should I use WS dispatch?" branching logic in one place so each hold point doesn't need to repeat the clientId/registry checks.

Parameters:

matchedBreakpoint - the matched breakpoint (must not be null)

streamId - the stream this frame belongs to

sequenceNumber - 0-based sequence number within the stream

direction - INBOUND or OUTBOUND

phase - RESPONSE_STREAM or INBOUND_STREAM

capturedBytes - the frame payload bytes

requestMethod - HTTP method of the original request

requestPath - path of the original request

configuration - for timeout and max-held

logger - for logging

webSocketClientRegistry - the WS registry for sending messages (may be null)

Returns:

a future that completes with the decision if WS dispatch was used; null if WS dispatch is not applicable or the dispatch was rejected (cap/client-not-connected — caller should write immediately)

tryWsDispatch

public CompletableFuture<StreamFrameDecision> tryWsDispatch(BreakpointMatcher matchedBreakpoint,
 String streamId,
 int sequenceNumber,
 PausedStreamFrame.Direction direction,
 BreakpointPhase phase,
 byte[] capturedBytes,
 String requestMethod,
 String requestPath,
 Long requestTimestamp,
 Configuration configuration,
 MockServerLogger logger,
 WebSocketClientRegistry webSocketClientRegistry)

Overload of tryWsDispatch(org.mockserver.mock.breakpoint.BreakpointMatcher, java.lang.String, int, org.mockserver.mock.breakpoint.PausedStreamFrame.Direction, org.mockserver.mock.breakpoint.BreakpointPhase, byte[], java.lang.String, java.lang.String, org.mockserver.configuration.Configuration, org.mockserver.logging.MockServerLogger, org.mockserver.closurecallback.websocketregistry.WebSocketClientRegistry) that includes the request timestamp.