kong.websocket.upstream

    Warning: The WebSocket PDK is under active development and is considered unstable at this time. Backwards-incompatible changes may be made to these functions.

    Retrieve the current frame.

    This returns the payload, type, and status code (for close frames) of the in-flight frame/message.

    This function is useful in contexts like the pre-function or post-function plugins where execution is sandboxed, and the caller has no access to these variables in the plugin handler scope.

    Phases

    Returns

    • string: The frame payload.

    • number: The frame status code (only returned for close frames)

    Usage

    kong.websocket.upstream.set_frame_data(data)

    Set the current frame’s payload.

    This allows the caller to overwrite the contents of the in-flight WebSocket frame before it is forwarded to the client.

    Phases

    • ws_upstream_frame

    Parameters

    • data (string): The desired frame payload

    Usage

    1. kong.websocket.upstream.set_frame_data("updated!")

    Set the status code for a close frame.

    This allows the caller to overwrite the status code of close frame before it is forwarded to the client.

    See the for a list of valid status codes.

    Plugin handlers that execute after this has been called will see the updated version of the status code.

    Calling this function when the in-flight frame is not a close frame will result in an exception.

    Parameters

    • status (): The desired status code

    Usage

    kong.websocket.upstream.drop_frame()

    Drop the current frame.

    This causes the in-flight frame to be dropped, meaning it will not be forwarded to the client.

    Close frames cannot be dropped. Calling this function for a close frame will result in an exception.

    Usage

    1. kong.websocket.upstream.drop_frame()

    Close the WebSocket connection.

    Calling this function immediately sends a close frame to the client and the upstream before terminating the connection.

    The in-flight frame will not be forwarded to the client, and plugin handlers that are set to execute after the current one will not be executed.

    Parameters

    • status (number, optional): Status code of the upstream close frame
    • message (string, optional): Payload of the upstream close frame
    • client_payload (string, optional): Payload of the client close frame

    Usage

    kong.set_max_payload_size

    Set the maximum allowed payload size for upstream frames.

    This limit is applied to all data frame types:

    • text
    • binary
    • continuation

    The limit is also assessed during aggregation of frames. For example, if the limit is 1024, and a upstream sends 3 continuation frames of size 500 each, the third frame will exceed the limit.

    If a upstream sends a message that exceeds the limit, a close frame with status code 1009 is sent to the upstream, and the connection is closed.

    This limit does not apply to control frames (close/ping/pong).

    • size (): The limit (0 resets to the default limit)
    1. -- set a max payload size of 1KB
    2. kong.websocket.upstream.set_max_payload_size(1024)
    4. kong.websocket.upstream.set_max_payload_size(0)