.. index:: single: http_websocket_messages(TextRepresentation)
.. _http_websocket_messages/1:

.. rst-class:: right

**object**

``http_websocket_messages(TextRepresentation)``
===============================================

* ``TextRepresentation`` - Text representation to be used for text messages and close reasons. Possible values are ``atom`` (default), ``chars``, and ``codes``.


Transport-neutral WebSocket message predicates built on top of the http_websocket frame layer.

| **Availability:** 
|    ``logtalk_load(http_websocket_messages(loader))``

| **Author:** Paulo Moura
| **Version:** 1:0:0
| **Date:** 2026-06-26

| **Compilation flags:**
|    ``static, context_switching_calls``


| **Uses:**
|    :ref:`http_websocket_frames <http_websocket_frames/0>`
|    :ref:`list <list/0>`
|    :ref:`utf_8 <utf_8/0>`

| **Remarks:**

   - Fragmentation model: This layer reassembles fragmented text and binary messages only when all continuation frames arrive contiguously. Interleaved control frames during fragmented messages raise ``http_websocket_message_sequence``. Use ``http_websocket_session`` for RFC 6455 live-stream processing that must surface interleaved control frames while reassembling data messages.

| **Inherited public predicates:**
|    (none)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: message/3
.. _http_websocket_messages/1::message/3:

``message/3``
^^^^^^^^^^^^^

Constructs a validated normalized WebSocket message term from the message type atom and payload term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``message(Type,Payload,Message)``
| **Mode and number of proofs:**
|    ``message(+atom,+term,-compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Type`` is not a supported WebSocket message type:
|        ``domain_error(http_websocket_message_type,Type)``
|    ``Payload`` is not valid for the requested WebSocket message type:
|        ``domain_error(http_websocket_message,Message)``
|    ``Payload`` is not a valid WebSocket close payload:
|        ``domain_error(http_websocket_close_payload,Payload)``
|    ``Payload`` contains an invalid WebSocket close code:
|        ``domain_error(http_websocket_close_code,Code)``
|    ``Payload`` is not valid text for the selected text representation:
|        ``domain_error(http_websocket_message_text,Text)``

| **Remarks:**

    - Type ``text``: Payload is text in the selected text representation.
    - Type ``binary``: Payload is a list of bytes.
    - Type ``ping`` or ``pong``: Payload is a list of bytes.
    - Type ``close``: Payload is one of ``empty``, ``status(Code)``, or ``status(Code, Reason)``.


------------

.. index:: is_message/1
.. _http_websocket_messages/1::is_message/1:

``is_message/1``
^^^^^^^^^^^^^^^^

True when the argument is a valid normalized WebSocket message term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``is_message(Message)``
| **Mode and number of proofs:**
|    ``is_message(@term)`` - ``zero_or_one``


------------

.. index:: read_message/2
.. _http_websocket_messages/1::read_message/2:

``read_message/2``
^^^^^^^^^^^^^^^^^^

Reads one WebSocket message from a binary stream. Continuation frames are reassembled for text and binary messages when they arrive contiguously. Returns ``end_of_file`` when the stream is already exhausted.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``read_message(Stream,Message)``
| **Mode and number of proofs:**
|    ``read_message(+stream_or_alias,-term)`` - ``one_or_error``

| **Exceptions:**
|    ``Stream`` is a variable:
|        ``instantiation_error``
|    The inbound frames do not form a valid normalized WebSocket message sequence:
|        ``domain_error(http_websocket_message_sequence,Frame)``
|    The inbound frame is invalid:
|        ``domain_error(http_websocket_frame,Frame)``
|    The inbound message payload is invalid:
|        ``domain_error(http_websocket_message,Message)``
|    The inbound message text is invalid for the selected text representation:
|        ``domain_error(http_websocket_message_text,Text)``

| **Remarks:**

    - Interleaved control frames: Control frames interleaved in the middle of a fragmented data message are not surfaced by this simplified layer and instead raise ``http_websocket_message_sequence``. Use ``http_websocket_session`` when interleaved control frames must be handled while a fragmented message is in progress.


------------

.. index:: write_message/2
.. _http_websocket_messages/1::write_message/2:

``write_message/2``
^^^^^^^^^^^^^^^^^^^

Writes one validated WebSocket message as a single final frame to a binary stream and flushes the stream.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``write_message(Stream,Message)``
| **Mode and number of proofs:**
|    ``write_message(+stream_or_alias,+compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Stream`` is a variable:
|        ``instantiation_error``
|    ``Message`` is not a valid normalized WebSocket message term:
|        ``domain_error(http_websocket_message,Message)``
|    ``Message`` has an unsupported message type:
|        ``domain_error(http_websocket_message_type,Type)``
|    ``Message`` has an invalid close payload:
|        ``domain_error(http_websocket_close_payload,Payload)``
|    ``Message`` has invalid text for the selected text representation:
|        ``domain_error(http_websocket_message_text,Text)``


------------

.. index:: type/2
.. _http_websocket_messages/1::type/2:

``type/2``
^^^^^^^^^^

Returns the type atom of a validated WebSocket message term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``type(Message,Type)``
| **Mode and number of proofs:**
|    ``type(+compound,-atom)`` - ``one_or_error``

| **Exceptions:**
|    ``Message`` is not a valid normalized WebSocket message term:
|        ``domain_error(http_websocket_message,Message)``
|    ``Message`` has an unsupported message type:
|        ``domain_error(http_websocket_message_type,Type)``


------------

.. index:: payload/2
.. _http_websocket_messages/1::payload/2:

``payload/2``
^^^^^^^^^^^^^

Returns the payload term of a validated WebSocket message term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``payload(Message,Payload)``
| **Mode and number of proofs:**
|    ``payload(+compound,-term)`` - ``one_or_error``

| **Exceptions:**
|    ``Message`` is not a valid normalized WebSocket message term:
|        ``domain_error(http_websocket_message,Message)``
|    ``Message`` has an unsupported message type:
|        ``domain_error(http_websocket_message_type,Type)``


------------

Protected predicates
--------------------

.. index:: encode_message/4
.. _http_websocket_messages/1::encode_message/4:

``encode_message/4``
^^^^^^^^^^^^^^^^^^^^

Protected helper that normalizes a WebSocket message term and returns the normalized term together with the corresponding frame opcode and payload bytes.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``encode_message(Message,NormalizedMessage,Opcode,PayloadBytes)``
| **Mode and number of proofs:**
|    ``encode_message(+compound,-compound,-atom,-list(byte))`` - ``one_or_error``

| **Exceptions:**
|    ``Message`` is not a valid normalized WebSocket message term:
|        ``domain_error(http_websocket_message,Message)``
|    ``Message`` has an unsupported message type:
|        ``domain_error(http_websocket_message_type,Type)``
|    ``Message`` has an invalid close payload:
|        ``domain_error(http_websocket_close_payload,Payload)``
|    ``Message`` has invalid text for the selected text representation:
|        ``domain_error(http_websocket_message_text,Text)``


------------

.. index:: decode_message/3
.. _http_websocket_messages/1::decode_message/3:

``decode_message/3``
^^^^^^^^^^^^^^^^^^^^

Protected helper that decodes payload bytes for the given message type atom into a normalized WebSocket message term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``decode_message(Type,PayloadBytes,Message)``
| **Mode and number of proofs:**
|    ``decode_message(+atom,+list(byte),-compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Type`` is not a supported WebSocket message type:
|        ``domain_error(http_websocket_message_type,Type)``
|    ``PayloadBytes`` is not a valid close payload:
|        ``domain_error(http_websocket_close_payload,PayloadBytes)``
|    ``PayloadBytes`` contains an invalid close code:
|        ``domain_error(http_websocket_close_code,Code)``
|    ``PayloadBytes`` does not decode to valid text for the selected text representation:
|        ``domain_error(http_websocket_message_text,PayloadBytes)``


------------

Private predicates
------------------

(no local declarations; see entity ancestors if any)

Operators
---------

(none)