object

http_websocket_messages(TextRepresentation)

  • TextRepresentation - Text representation to be used for text messages and close reasons. Possible values are atom (default), chars, and codes.

Transport-neutral WebSocket message predicates built on top of the http_websocket frame layer.

Availability:
logtalk_load(http_websocket_messages(loader))
Author: Paulo Moura
Version: 1:0:0
Date: 2026-06-26
Compilation flags:
static, context_switching_calls
Uses:
http_websocket_frames
list
utf_8
Remarks:

  • Fragmentation model: This layer reassembles fragmented text and binary messages only when all continuation frames arrive contiguously. Interleaved control frames during fragmented messages raise http_websocket_message_sequence. Use http_websocket_session for RFC 6455 live-stream processing that must surface interleaved control frames while reassembling data messages.

Inherited public predicates:
(none)

Public predicates

message/3

Constructs a validated normalized WebSocket message term from the message type atom and payload term.

Compilation flags:
static
Template:
message(Type,Payload,Message)
Mode and number of proofs:
message(+atom,+term,-compound) - one_or_error
Exceptions:
Type is not a supported WebSocket message type:
domain_error(http_websocket_message_type,Type)
Payload is not valid for the requested WebSocket message type:
domain_error(http_websocket_message,Message)
Payload is not a valid WebSocket close payload:
domain_error(http_websocket_close_payload,Payload)
Payload contains an invalid WebSocket close code:
domain_error(http_websocket_close_code,Code)
Payload is not valid text for the selected text representation:
domain_error(http_websocket_message_text,Text)
Remarks:

  • Type text: Payload is text in the selected text representation.

  • Type binary: Payload is a list of bytes.

  • Type ping or pong: Payload is a list of bytes.

  • Type close: Payload is one of empty, status(Code), or status(Code, Reason).

is_message/1

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

Compilation flags:
static
Template:
is_message(Message)
Mode and number of proofs:
is_message(@term) - zero_or_one

read_message/2

Reads one WebSocket message from a binary stream. Continuation frames are reassembled for text and binary messages when they arrive contiguously. Returns end_of_file when the stream is already exhausted.

Compilation flags:
static
Template:
read_message(Stream,Message)
Mode and number of proofs:
read_message(+stream_or_alias,-term) - one_or_error
Exceptions:
Stream is a variable:
instantiation_error
The inbound frames do not form a valid normalized WebSocket message sequence:
domain_error(http_websocket_message_sequence,Frame)
The inbound frame is invalid:
domain_error(http_websocket_frame,Frame)
The inbound message payload is invalid:
domain_error(http_websocket_message,Message)
The inbound message text is invalid for the selected text representation:
domain_error(http_websocket_message_text,Text)
Remarks:

  • Interleaved control frames: Control frames interleaved in the middle of a fragmented data message are not surfaced by this simplified layer and instead raise http_websocket_message_sequence. Use http_websocket_session when interleaved control frames must be handled while a fragmented message is in progress.

write_message/2

Writes one validated WebSocket message as a single final frame to a binary stream and flushes the stream.

Compilation flags:
static
Template:
write_message(Stream,Message)
Mode and number of proofs:
write_message(+stream_or_alias,+compound) - one_or_error
Exceptions:
Stream is a variable:
instantiation_error
Message is not a valid normalized WebSocket message term:
domain_error(http_websocket_message,Message)
Message has an unsupported message type:
domain_error(http_websocket_message_type,Type)
Message has an invalid close payload:
domain_error(http_websocket_close_payload,Payload)
Message has invalid text for the selected text representation:
domain_error(http_websocket_message_text,Text)

type/2

Returns the type atom of a validated WebSocket message term.

Compilation flags:
static
Template:
type(Message,Type)
Mode and number of proofs:
type(+compound,-atom) - one_or_error
Exceptions:
Message is not a valid normalized WebSocket message term:
domain_error(http_websocket_message,Message)
Message has an unsupported message type:
domain_error(http_websocket_message_type,Type)

payload/2

Returns the payload term of a validated WebSocket message term.

Compilation flags:
static
Template:
payload(Message,Payload)
Mode and number of proofs:
payload(+compound,-term) - one_or_error
Exceptions:
Message is not a valid normalized WebSocket message term:
domain_error(http_websocket_message,Message)
Message has an unsupported message type:
domain_error(http_websocket_message_type,Type)

Protected predicates

encode_message/4

Protected helper that normalizes a WebSocket message term and returns the normalized term together with the corresponding frame opcode and payload bytes.

Compilation flags:
static
Template:
encode_message(Message,NormalizedMessage,Opcode,PayloadBytes)
Mode and number of proofs:
encode_message(+compound,-compound,-atom,-list(byte)) - one_or_error
Exceptions:
Message is not a valid normalized WebSocket message term:
domain_error(http_websocket_message,Message)
Message has an unsupported message type:
domain_error(http_websocket_message_type,Type)
Message has an invalid close payload:
domain_error(http_websocket_close_payload,Payload)
Message has invalid text for the selected text representation:
domain_error(http_websocket_message_text,Text)

decode_message/3

Protected helper that decodes payload bytes for the given message type atom into a normalized WebSocket message term.

Compilation flags:
static
Template:
decode_message(Type,PayloadBytes,Message)
Mode and number of proofs:
decode_message(+atom,+list(byte),-compound) - one_or_error
Exceptions:
Type is not a supported WebSocket message type:
domain_error(http_websocket_message_type,Type)
PayloadBytes is not a valid close payload:
domain_error(http_websocket_close_payload,PayloadBytes)
PayloadBytes contains an invalid close code:
domain_error(http_websocket_close_code,Code)
PayloadBytes does not decode to valid text for the selected text representation:
domain_error(http_websocket_message_text,PayloadBytes)

Private predicates

(no local declarations; see entity ancestors if any)

Operators

(none)