.. index:: single: http_websocket_frames
.. _http_websocket_frames/0:

.. rst-class:: right

**object**

``http_websocket_frames``
=========================

Transport-neutral WebSocket frame predicates for constructing, parsing, generating, reading, and writing normalized frame terms.

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

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

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


| **Imports:**
|    ``public`` :ref:`options <options/0>`
| **Uses:**
|    :ref:`list <list/0>`
|    :ref:`reader <reader/0>`

| **Remarks:**
|    (none)

| **Inherited public predicates:**
|     :ref:`options_protocol/0::check_option/1`  :ref:`options_protocol/0::check_options/1`  :ref:`options_protocol/0::default_option/1`  :ref:`options_protocol/0::default_options/1`  :ref:`options_protocol/0::option/2`  :ref:`options_protocol/0::option/3`  :ref:`options_protocol/0::valid_option/1`  :ref:`options_protocol/0::valid_options/1`  

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

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

.. index:: frame/5
.. _http_websocket_frames/0::frame/5:

``frame/5``
^^^^^^^^^^^

Constructs a validated normalized WebSocket frame term from the fragmentation state atom, opcode atom, payload bytes, and frame properties.

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

| **Template:**
|    ``frame(Final,Opcode,Payload,Properties,Frame)``
| **Mode and number of proofs:**
|    ``frame(+atom,+atom,+list(byte),+list(compound),-compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Final`` is not a valid WebSocket final flag:
|        ``domain_error(http_websocket_final,Final)``
|    ``Opcode`` is not a valid WebSocket opcode:
|        ``domain_error(http_websocket_opcode,Opcode)``
|    ``Payload`` is a variable or a partial list:
|        ``instantiation_error``
|    ``Payload`` is not a valid WebSocket payload byte list:
|        ``domain_error(http_websocket_payload,Payload)``
|    ``Properties`` is a variable or a partial list:
|        ``instantiation_error``
|    ``Properties`` is not a valid WebSocket frame property list:
|        ``domain_error(http_websocket_properties,Properties)``
|    A frame property is invalid:
|        ``domain_error(http_websocket_property,Property)``
|    A masking key is invalid:
|        ``domain_error(http_websocket_masking_key,Key)``
|    Reserved bits are invalid:
|        ``domain_error(http_websocket_reserved_bits,Bits)``
|    The frame violates WebSocket frame semantics:
|        ``domain_error(http_websocket_frame,Frame)``

| **Remarks:**

    - Final atoms: Use ``final`` for FIN=1 and ``more`` for FIN=0.
    - Opcode atoms: Supported opcodes are ``continuation``, ``text``, ``binary``, ``close``, ``ping``, and ``pong``.
    - Property ``masking_key(Key)``: Requests masking on the wire using a list of four mask bytes.
    - Property ``reserved_bits(Bits)``: Preserves reserved bits as an ordered list containing any of ``rsv1``, ``rsv2``, and ``rsv3``.


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

.. index:: is_frame/1
.. _http_websocket_frames/0::is_frame/1:

``is_frame/1``
^^^^^^^^^^^^^^

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

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

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


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

.. index:: parse/2
.. _http_websocket_frames/0::parse/2:

``parse/2``
^^^^^^^^^^^

Parses one WebSocket frame from a source term. Supported sources are ``bytes(Bytes)``, ``codes(Bytes)``, ``file(File)``, and ``stream(Stream)``. Empty sources return ``end_of_file``.

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

| **Template:**
|    ``parse(Source,Frame)``
| **Mode and number of proofs:**
|    ``parse(++compound,-term)`` - ``one_or_error``

| **Exceptions:**
|    ``Source`` is a variable:
|        ``instantiation_error``
|    ``Source`` is neither a variable nor a valid WebSocket frame source term:
|        ``domain_error(http_websocket_source,Source)``
|    The source bytes are not a valid WebSocket byte sequence:
|        ``domain_error(http_websocket_byte_sequence,Bytes)``
|    The source bytes contain an invalid WebSocket opcode:
|        ``domain_error(http_websocket_opcode,Opcode)``
|    The source bytes contain an invalid WebSocket frame length:
|        ``domain_error(http_websocket_frame_length,PayloadLength)``
|    The source bytes do not encode a valid normalized WebSocket frame:
|        ``domain_error(http_websocket_frame,Frame)``


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

.. index:: generate/2
.. _http_websocket_frames/0::generate/2:

``generate/2``
^^^^^^^^^^^^^^

Generates one validated WebSocket frame to a sink term. Supported sinks are ``bytes(Bytes)``, ``codes(Bytes)``, ``file(File)``, and ``stream(Stream)``.

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

| **Template:**
|    ``generate(Sink,Frame)``
| **Mode and number of proofs:**
|    ``generate(++compound,+compound)`` - ``one_or_error``

| **Exceptions:**
|    ``Sink`` is a variable:
|        ``instantiation_error``
|    ``Sink`` is neither a variable nor a valid WebSocket frame sink term:
|        ``domain_error(http_websocket_sink,Sink)``
|    ``Frame`` is not a valid normalized WebSocket frame term:
|        ``domain_error(http_websocket_frame,Frame)``


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

.. index:: read_frame/2
.. _http_websocket_frames/0::read_frame/2:

``read_frame/2``
^^^^^^^^^^^^^^^^

Reads one WebSocket frame from a binary stream without requiring end-of-file. Returns ``end_of_file`` when the stream is already exhausted.

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

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

| **Exceptions:**
|    ``Stream`` is a variable:
|        ``instantiation_error``
|    The inbound bytes are not a valid WebSocket byte sequence:
|        ``domain_error(http_websocket_byte_sequence,Bytes)``
|    The inbound payload length exceeds the configured limit:
|        ``domain_error(http_websocket_payload_length_limit,PayloadLength)``
|    The inbound bytes do not encode a valid normalized WebSocket frame:
|        ``domain_error(http_websocket_frame,Frame)``


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

.. index:: read_frame/3
.. _http_websocket_frames/0::read_frame/3:

``read_frame/3``
^^^^^^^^^^^^^^^^

Reads one WebSocket frame from a binary stream using the given read options. Returns ``end_of_file`` when the stream is already exhausted.

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

| **Template:**
|    ``read_frame(Stream,Frame,Options)``
| **Mode and number of proofs:**
|    ``read_frame(+stream_or_alias,-term,+list)`` - ``one_or_error``

| **Exceptions:**
|    ``Stream`` is a variable:
|        ``instantiation_error``
|    ``Options`` is a variable or a partial list:
|        ``instantiation_error``
|    ``Options`` is neither a variable nor a list:
|        ``type_error(list,Options)``
|    An element ``Option`` of the list ``Options`` is neither a variable nor a compound term:
|        ``type_error(compound,Option)``
|    An element ``Option`` of the list ``Options`` is a compound term but not a valid option:
|        ``domain_error(option,Option)``
|    The inbound payload length exceeds the configured limit:
|        ``domain_error(http_websocket_payload_length_limit,PayloadLength)``
|    The inbound bytes are not a valid WebSocket byte sequence:
|        ``domain_error(http_websocket_byte_sequence,Bytes)``
|    The inbound bytes do not encode a valid normalized WebSocket frame:
|        ``domain_error(http_websocket_frame,Frame)``

| **Remarks:**

    - Repeated options: When the same read option is given multiple times, the first occurrence is used.
    - Option ``max_payload_length(Bytes)``: Rejects frames whose declared payload length is greater than ``Bytes`` before allocating payload storage. Use a non-negative integer.


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

.. index:: write_frame/2
.. _http_websocket_frames/0::write_frame/2:

``write_frame/2``
^^^^^^^^^^^^^^^^^

Writes one validated WebSocket frame to a binary stream and flushes the stream.

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

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

| **Exceptions:**
|    ``Stream`` is a variable:
|        ``instantiation_error``
|    ``Frame`` is not a valid normalized WebSocket frame term:
|        ``domain_error(http_websocket_frame,Frame)``


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

.. index:: final/2
.. _http_websocket_frames/0::final/2:

``final/2``
^^^^^^^^^^^

Returns the fragmentation state atom of a validated WebSocket frame term.

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

| **Template:**
|    ``final(Frame,Final)``
| **Mode and number of proofs:**
|    ``final(+compound,-atom)`` - ``one_or_error``

| **Exceptions:**
|    ``Frame`` is not a valid normalized WebSocket frame term:
|        ``domain_error(http_websocket_frame,Frame)``


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

.. index:: opcode/2
.. _http_websocket_frames/0::opcode/2:

``opcode/2``
^^^^^^^^^^^^

Returns the opcode atom of a validated WebSocket frame term.

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

| **Template:**
|    ``opcode(Frame,Opcode)``
| **Mode and number of proofs:**
|    ``opcode(+compound,-atom)`` - ``one_or_error``

| **Exceptions:**
|    ``Frame`` is not a valid normalized WebSocket frame term:
|        ``domain_error(http_websocket_frame,Frame)``


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

.. index:: payload/2
.. _http_websocket_frames/0::payload/2:

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

Returns the payload byte list of a validated WebSocket frame term.

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

| **Template:**
|    ``payload(Frame,Payload)``
| **Mode and number of proofs:**
|    ``payload(+compound,-list(byte))`` - ``one_or_error``

| **Exceptions:**
|    ``Frame`` is not a valid normalized WebSocket frame term:
|        ``domain_error(http_websocket_frame,Frame)``


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

.. index:: properties/2
.. _http_websocket_frames/0::properties/2:

``properties/2``
^^^^^^^^^^^^^^^^

Returns the normalized property list of a validated WebSocket frame term.

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

| **Template:**
|    ``properties(Frame,Properties)``
| **Mode and number of proofs:**
|    ``properties(+compound,-list(compound))`` - ``one_or_error``

| **Exceptions:**
|    ``Frame`` is not a valid normalized WebSocket frame term:
|        ``domain_error(http_websocket_frame,Frame)``


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

.. index:: property/2
.. _http_websocket_frames/0::property/2:

``property/2``
^^^^^^^^^^^^^^

True when the validated WebSocket frame term contains the given property. When the property argument is a variable, properties can be enumerated on backtracking.

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

| **Template:**
|    ``property(Frame,Property)``
| **Mode and number of proofs:**
|    ``property(+compound,?compound)`` - ``zero_or_one_or_error``

| **Exceptions:**
|    ``Frame`` is not a valid normalized WebSocket frame term:
|        ``domain_error(http_websocket_frame,Frame)``


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

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

(no local declarations; see entity ancestors if any)

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

(no local declarations; see entity ancestors if any)

Operators
---------

(none)

