.. 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 ` | **Uses:** | :ref:`list ` | :ref:`reader ` | **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)