Did you know ... Search Documentation:
Pack logtalk -- logtalk-3.101.0/docs/handbook/_sources/libraries/http_websocket_messages.rst.txt

.. _library_http_websocket_messages:

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 <../../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.