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

.. _library_http_websocket_frames:

http_websocket_frames

This library provides the transport-neutral WebSocket helpers shared by the current HTTP stack. It includes normalized frame terms and binary frame parsing and generation in the http_websocket_frames object.

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

API documentation

Open the `../../apis/library_index.html#http_websocket_frames <../../apis/library_index.html#http_websocket_frames>`__ link in a web browser.

Loading

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

::

| ?- logtalk_load(http_websocket_frames(loader)).

Testing

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

::

| ?- logtalk_load(http_websocket_frames(tester)).

Current scope

The current implementation provides:

  • frame/5 for constructing validated normalized WebSocket frame terms.
  • is_frame/1 for testing normalized frame terms.
  • final/2, opcode/2, payload/2, properties/2, and property/2 for inspecting normalized frame terms.
  • parse/2 and generate/2 for binary source and sink terms.
  • read_frame/2 and write_frame/2 for incremental frame I/O on binary streams.

Normalized terms

Frames use the normalized term:

::

frame(Final, Opcode, Payload, Properties)

Where:

  • Final is either final or more.
  • Opcode is one of continuation, text, binary, close, ping, or pong.
  • Payload is a list of bytes.
  • Properties currently recognizes:
    • masking_key(Key) where Key is a four-byte list.
    • reserved_bits(Bits) where Bits is an ordered subset of [rsv1, rsv2, rsv3].

Valid properties

The Properties list accepted by frame/5, generate/2, and write_frame/2 can contain only the following properties:

  • masking_key(Key)
    • Key must be a list of exactly four bytes.
    • Each byte must be an integer in the 0..255 range.
  • reserved_bits(Bits)
    • Bits must be a list containing any ordered subset of [rsv1, rsv2, rsv3].
    • Duplicate reserved-bit atoms are invalid.

    Each property can be given at most once. When both properties are present, the normalized property list is returned in the canonical order [reserved_bits(Bits), masking_key(Key)].

Current workflow

  • Use read_frame/2 and write_frame/2 on those streams to exchange WebSocket frames.
  • Use the higher-level http_websocket_messages library when you need continuation reassembly or UTF-8-aware text and close-reason handling.
  • Use the http_websocket_session library when fragmented reads must preserve pending state across interleaved control frames or when outgoing writes should apply client or server masking policy automatically.
  • Use parse/2 and generate/2 when working with in-memory byte lists or binary files instead of live streams.

Current limitations

  • This library operates at the frame level only. It does not provide application session loops.
  • This layer does not provide message reassembly or UTF-8-aware text and close-reason handling.
  • Client and server masking policy is not enforced by role in this frame layer. The presence of a masking_key/1 property controls whether outgoing frames are masked. Use the http_websocket_session layer when you want role-aware writes and role-aware incoming masking validation.
  • Reserved bits are preserved structurally but no extension negotiation or extension semantics are implemented.