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)