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 options
Uses:
list
reader
Remarks:
(none)
Inherited public predicates:
 check_option/1  check_options/1  default_option/1  default_options/1  option/2  option/3  valid_option/1  valid_options/1

Public predicates

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.

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

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)

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)

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)

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.

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)

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)

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)

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)

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)

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)