# `http_websocket_messages`

This library provides the next transport-neutral WebSocket slice on top of the `http_websocket` frame library. It reassembles continuation sequences for text and binary messages, decodes and encodes UTF-8 text payloads, and adds a normalized message term for text, binary, ping, pong, and close messages.

This library can be used with backend Prolog systems that support unbound integer arithmetic.

## API documentation

Open the ../../apis/library_index.html#http_websocket_messages link in a web browser.

## Loading

To load the library, load the `loader.lgt` file:

    | ?- logtalk_load(http_websocket_messages(loader)).

## Testing

To test this library, load the `tester.lgt` file:

    | ?- logtalk_load(http_websocket_messages(tester)).

## Current scope

The current implementation provides:

- `message/3` for constructing validated normalized WebSocket message terms.

- `is_message/1` for testing normalized message terms.

- `type/2` and `payload/2` for inspecting normalized message terms.

- `read_message/2` for reading one WebSocket message from a binary stream, including continuation reassembly for text and binary messages.

- `write_message/2` for writing one WebSocket message as a single final frame.

This layer remains intentionally stateless. The `http_websocket_session` library builds on top of it when the caller needs explicit session state, interleaved control-frame surfacing, or role-aware outgoing fragmentation and masking.

## Normalized terms

Messages use the normalized term:

    message(Type, Payload)

Where:

- `Type` is one of `text`, `binary`, `ping`, `pong`, or `close`.

- For `text`, `Payload` is text in the selected representation.

- For `binary`, `ping`, and `pong`, `Payload` is a list of bytes.

- For `close`, `Payload` is one of:

  - `empty`

  - `status(Code)`

  - `status(Code, Reason)`

The parameterized object `http_websocket_messages(TextRepresentation)` accepts `atom`, `chars`, or `codes`. The plain `http_websocket_messages` object uses atoms.

## Current workflow

- Complete the opening handshake with `http_client::open_websocket/4` or `http_socket_transport::serve_websocket_once/5`.

- Obtain the upgraded binary streams with `http_socket_transport::connection_streams/3`.

- Use `read_message/2` and `write_message/2` when you want UTF-8-aware text messages and continuation reassembly instead of raw frame access.

- Use the higher-level `http_websocket_session` library when fragmented data reads must coexist with interleaved control messages or when writes should apply client or server masking policy automatically.

- Use the lower-level `http_websocket` predicates directly when you need raw frame properties such as masking keys or reserved bits.

## Current limitations

- Outgoing messages are generated as a single final frame. This layer does not provide outgoing fragmentation policies.

- Fragmented text and binary messages are reassembled only when the following frames are plain continuation frames. Use the `http_websocket_session` library when interleaved control messages must be surfaced while the fragmented data remains pending.

- Client and server masking policy is not enforced automatically by role in this stateless layer. Use the `http_websocket_session` library when that policy should be applied automatically.

- This layer does not provide application session loops. For full close-handshake orchestration or automatic ping/pong policies, use the `http_websocket_session` layer.