.. 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)