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)