Package org.microproxy.http

Class WebSocketFrame

java.lang.Object
org.microproxy.http.WebSocketFrame
public final class WebSocketFrame extends Object
A WebSocket frame (RFC 6455 section 5.2). Frames the proxy relays after an upgrade are shown to HttpFilters.webSocketFrameReceived(WebSocketFrame, boolean) and HttpFilters.filterWebSocketFrame(WebSocketFrame, boolean); the latter may return a frame built with text(String), binary(byte[]), withPayload(byte[]) and the like to send instead. Frames are immutable.

Built frames carry an unmasked payload. The proxy masks a frame when it sends it towards the server and leaves it unmasked towards the client, as RFC 6455 requires (toWire(boolean)).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    OPCODE_BINARY
    The opcode for a binary message.
    static final int
    OPCODE_CLOSE
    The opcode for closing the WebSocket connection.
    static final int
    OPCODE_CONTINUATION
    The opcode for a continuation of a fragmented message.
    static final int
    OPCODE_PING
    The opcode for a PING control frame.
    static final int
    OPCODE_PONG
    The opcode for a PONG control frame.
    static final int
    OPCODE_TEXT
    The opcode for a text message.

  • Constructor Summary

    Constructors
    Constructor
    Description
    WebSocketFrame(byte[] header, byte[] wirePayload, long payloadLength)
    Creates a frame from wire data, retaining the supplied arrays without copying.

  • Method Summary

    Modifier and Type
    Method
    Description
    static WebSocketFrame
    binary(byte[] data)
    A final binary frame.
    static WebSocketFrame
    close(int code, String reason)
    A close frame with a status code (RFC 6455 section 7.4) and a reason.
    boolean
    isBinary()
    Checks the frame opcode.
    boolean
    isClose()
    Checks the frame opcode.
    boolean
    isContinuation()
    Checks the frame opcode.
    boolean
    isFinal()
    Checks whether this frame ends the message.
    boolean
    isMasked()
    Whether the payload is masked (always true for client-to-server frames).
    boolean
    isPing()
    Checks the frame opcode.
    boolean
    isPong()
    Checks the frame opcode.
    boolean
    isText()
    Checks the frame opcode.
    boolean
    isTruncated()
    Whether the payload was too large to buffer, in which case payload() is null.
    static WebSocketFrame
    of(boolean fin, int rsv, int opcode, byte[] payload)
    A frame with the given fields and an unmasked payload.
    int
    opcode()
    Returns the frame opcode.
    byte[]
    payload()
    The unmasked application payload, or null if isTruncated().
    String
    payloadAsText()
    The payload decoded as UTF-8 (meaningful for text frames), or null if truncated.
    long
    payloadLength()
    Returns the declared payload length, even when the payload was not buffered.
    byte[]
    rawBytes()
    The frame exactly as on the wire: header plus (masked) payload, or just the header if truncated.
    int
    rsv()
    The RSV1-3 bits (bit 2 = RSV1, used by permessage-deflate).
    static WebSocketFrame
    text(String text)
    A final text frame.
    String
    toString()
     
    byte[]
    toWire(boolean masked)
    The frame encoded for sending: masked with a fresh random key when masked (frames towards a server), unmasked otherwise.
    WebSocketFrame
    withPayload(byte[] payload)
    This frame's FIN bit, RSV bits and opcode with a new payload.
    WebSocketFrame
    withText(String text)
    This frame's FIN bit, RSV bits and opcode with a new payload, encoded as UTF-8.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • OPCODE_CONTINUATION

      public static final int OPCODE_CONTINUATION
      The opcode for a continuation of a fragmented message.
      See Also:

    • OPCODE_TEXT

      public static final int OPCODE_TEXT
      The opcode for a text message.
      See Also:

    • OPCODE_BINARY

      public static final int OPCODE_BINARY
      The opcode for a binary message.
      See Also:

    • OPCODE_CLOSE

      public static final int OPCODE_CLOSE
      The opcode for closing the WebSocket connection.
      See Also:

    • OPCODE_PING

      public static final int OPCODE_PING
      The opcode for a PING control frame.
      See Also:

    • OPCODE_PONG

      public static final int OPCODE_PONG
      The opcode for a PONG control frame.
      See Also:

  • Constructor Details

    • WebSocketFrame

      public WebSocketFrame(byte[] header, byte[] wirePayload, long payloadLength)
      Creates a frame from wire data, retaining the supplied arrays without copying.
      Parameters:
      header - the frame header as on the wire (2-14 bytes)
      wirePayload - the payload as on the wire (still masked), or null if the frame was too large to buffer
      payloadLength - the payload length declared in the header

  • Method Details

    • of

      public static WebSocketFrame of(boolean fin, int rsv, int opcode, byte[] payload)
      A frame with the given fields and an unmasked payload.
      Parameters:
      fin - whether this is the final frame of the message
      rsv - the RSV1-3 bits (0 unless an extension defines them)
      opcode - the four-bit frame opcode
      payload - the unmasked payload bytes, copied into the frame
      Returns:
      a frame with the supplied flags and payload

    • text

      public static WebSocketFrame text(String text)
      A final text frame.
      Parameters:
      text - the text to encode as UTF-8
      Returns:
      a final text frame

    • binary

      public static WebSocketFrame binary(byte[] data)
      A final binary frame.
      Parameters:
      data - the binary payload bytes, copied into the frame
      Returns:
      a final binary frame

    • close

      public static WebSocketFrame close(int code, String reason)
      A close frame with a status code (RFC 6455 section 7.4) and a reason.
      Parameters:
      code - the status code to encode in two octets
      reason - the close reason to encode as UTF-8
      Returns:
      a final close frame containing the status and reason

    • withPayload

      public WebSocketFrame withPayload(byte[] payload)
      This frame's FIN bit, RSV bits and opcode with a new payload.
      Parameters:
      payload - the replacement unmasked payload, copied into the new frame
      Returns:
      a new frame preserving FIN, RSV bits, and opcode

    • withText

      public WebSocketFrame withText(String text)
      This frame's FIN bit, RSV bits and opcode with a new payload, encoded as UTF-8.
      Parameters:
      text - the replacement payload text to encode as UTF-8
      Returns:
      a new frame preserving FIN, RSV bits, and opcode

    • isFinal

      public boolean isFinal()
      Checks whether this frame ends the message.
      Returns:
      whether the FIN bit is set

    • rsv

      public int rsv()
      The RSV1-3 bits (bit 2 = RSV1, used by permessage-deflate).
      Returns:
      the three reserved bits, with RSV1 in bit 2

    • opcode

      public int opcode()
      Returns the frame opcode.
      Returns:
      the unsigned four-bit opcode

    • isText

      public boolean isText()
      Checks the frame opcode.
      Returns:
      whether the opcode is OPCODE_TEXT

    • isBinary

      public boolean isBinary()
      Checks the frame opcode.
      Returns:
      whether the opcode is OPCODE_BINARY

    • isContinuation

      public boolean isContinuation()
      Checks the frame opcode.
      Returns:
      whether the opcode is OPCODE_CONTINUATION

    • isClose

      public boolean isClose()
      Checks the frame opcode.
      Returns:
      whether the opcode is OPCODE_CLOSE

    • isPing

      public boolean isPing()
      Checks the frame opcode.
      Returns:
      whether the opcode is OPCODE_PING

    • isPong

      public boolean isPong()
      Checks the frame opcode.
      Returns:
      whether the opcode is OPCODE_PONG

    • isMasked

      public boolean isMasked()
      Whether the payload is masked (always true for client-to-server frames).
      Returns:
      whether the frame header sets the MASK bit

    • payloadLength

      public long payloadLength()
      Returns the declared payload length, even when the payload was not buffered.
      Returns:
      the payload length declared by the wire header, in octets

    • isTruncated

      public boolean isTruncated()
      Whether the payload was too large to buffer, in which case payload() is null.
      Returns:
      whether the payload was omitted from the buffered frame

    • payload

      public byte[] payload()
      The unmasked application payload, or null if isTruncated().
      Returns:
      a copy of the unmasked payload, or null if truncated

    • payloadAsText

      public String payloadAsText()
      The payload decoded as UTF-8 (meaningful for text frames), or null if truncated.
      Returns:
      the UTF-8-decoded payload, or null if truncated

    • toWire

      public byte[] toWire(boolean masked)
      The frame encoded for sending: masked with a fresh random key when masked (frames towards a server), unmasked otherwise.
      Parameters:
      masked - whether to mask the payload with a fresh random key
      Returns:
      the encoded header and payload
      Throws:
      IllegalStateException - if the frame is truncated

    • rawBytes

      public byte[] rawBytes()
      The frame exactly as on the wire: header plus (masked) payload, or just the header if truncated.
      Returns:
      a new array containing the original header and any buffered wire payload

    • toString

      public String toString()
      Overrides:
      toString in class Object