Interface WebsocketSession

public interface WebsocketSession
Minimal websocket session contract needed by the Fluxzero runtime clients.

The contract is binary-frame oriented because Fluxzero runtime traffic is serialized and compressed before it is sent. Implementations should make close and abort callbacks idempotent so higher-level retry logic can safely react to transport races.

  • Field Details

    • DEFAULT_MAX_BINARY_FRAGMENT_BYTES

      static final int DEFAULT_MAX_BINARY_FRAGMENT_BYTES
      Default upper bound for one physical WebSocket binary frame when a message is sent as fragments.
      See Also:

  • Method Details

    • getRequestURI

      URI getRequestURI()
      Returns the URI used to open this session.

    • getUserProperties

      Map<String,Object> getUserProperties()
      Returns mutable metadata associated with this session.

      Fluxzero clients use these properties to store negotiated session identifiers, runtime version information, and selected compression settings.

    • getHandshakeResponseHeaders

      Map<String, List<String>> getHandshakeResponseHeaders()
      Returns the response headers from the successful opening handshake.

    • getOpenSessions

      Set<WebsocketSession> getOpenSessions()
      Returns a snapshot of currently open sessions owned by the same connector.

    • isOpen

      boolean isOpen()
      Returns whether the session is still open for application traffic.

    • sendBinary

      void sendBinary(ByteBuffer data) throws IOException
      Sends one complete binary WebSocket message.
      Parameters:
      data - bytes from the buffer's current position to its limit
      Throws:
      IOException - when the frame cannot be sent

    • sendBinaryAsync

      default CompletableFuture<Void> sendBinaryAsync(ByteBuffer data)
      Sends one complete binary WebSocket message asynchronously.

      Implementations may override this with a non-blocking transport send. The default keeps existing test doubles and simple implementations working by delegating to sendBinary(ByteBuffer).

      Parameters:
      data - bytes from the buffer's current position to its limit
      Returns:
      a future that completes when the transport accepts or fails the frame

    • sendBinaryAsync

      default CompletableFuture<Void> sendBinaryAsync(ByteBuffer data, int maxFragmentBytes)
      Sends one complete binary WebSocket message asynchronously, allowing implementations to split the message into WebSocket continuation frames.

      The default delegates to sendBinaryAsync(ByteBuffer) so existing simple implementations keep working. Implementations that support native WebSocket fragmentation should preserve message ordering and complete the returned future only after the final fragment has been accepted by the transport.

      Parameters:
      data - bytes from the buffer's current position to its limit
      maxFragmentBytes - maximum payload bytes per physical WebSocket frame; non-positive values mean no split
      Returns:
      a future that completes when the full WebSocket message has been accepted or failed

    • sendPing

      void sendPing(ByteBuffer applicationData) throws IOException
      Sends a ping frame.
      Parameters:
      applicationData - ping payload from the buffer's current position to its limit
      Throws:
      IOException - when the frame cannot be sent

    • close

      void close() throws IOException
      Closes the session with a normal close reason.
      Throws:
      IOException - when the close frame cannot be sent

    • close

      void close(WebsocketCloseReason closeReason) throws IOException
      Closes the session with a specific close reason.
      Parameters:
      closeReason - close status and reason to send
      Throws:
      IOException - when the close frame cannot be sent

    • abort

      void abort(WebsocketCloseReason closeReason)
      Immediately aborts the underlying transport and reports the given close reason to the endpoint.
      Parameters:
      closeReason - synthetic close status and reason to report