.. index:: single: http_websocket_client_service(HTTPTransport)
.. _http_websocket_client_service/1:

.. rst-class:: right

**object**

``http_websocket_client_service(HTTPTransport)``
================================================

Client-side convenience for callback-driven WebSocket sessions with atom text representation, combining the opening handshake, optional initial outbound messages, and the higher-level session loop.

| **Availability:** 
|    ``logtalk_load(http_websocket_service(loader))``

| **Author:** Paulo Moura
| **Version:** 1:0:0
| **Date:** 2026-07-13

| **Compilation flags:**
|    ``static, context_switching_calls``


| **Extends:**
|    ``public`` :ref:`http_websocket_service(HTTPTransport,client,atom) <http_websocket_service/3>`
| **Uses:**
|    :ref:`http_client <http_client/0>`
|    :ref:`list <list/0>`
|    :ref:`user <user/0>`

| **Remarks:**
|    (none)

| **Inherited public predicates:**
|     :ref:`http_websocket_session/2::initial_state/1`  :ref:`http_websocket_messages/1::is_message/1`  :ref:`http_websocket_session/2::is_state/1`  :ref:`http_websocket_messages/1::message/3`  :ref:`http_websocket_messages/1::payload/2`  :ref:`http_websocket_messages/1::read_message/2`  :ref:`http_websocket_session/2::read_message/4`  :ref:`http_websocket_session/2::read_message/5`  :ref:`http_websocket_session/2::read_message/6`  :ref:`http_websocket_service/3::run_session/3`  :ref:`http_websocket_service/3::run_session/4`  :ref:`http_websocket_messages/1::type/2`  :ref:`http_websocket_session/2::write_message/2`  :ref:`http_websocket_session/2::write_message/3`  :ref:`http_websocket_session/2::write_message/4`  :ref:`http_websocket_session/2::write_message/5`  

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: open/4
.. _http_websocket_client_service/1::open/4:

``open/4``
^^^^^^^^^^

Builds a WebSocket opening handshake from the given absolute WebSocket URL supported by the selected transport parameterization, opens the upgraded connection, optionally writes initial outbound messages, then runs one callback-driven client session loop until the close handshake completes or the peer closes the stream.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``open(URL,Handler,Response,State)``
| **Mode and number of proofs:**
|    ``open(+atom,+object_identifier,-compound,-compound)`` - ``one_or_error``

| **Exceptions:**
|    ``URL`` is a variable:
|        ``instantiation_error``
|    ``URL`` is not a supported absolute WebSocket URL:
|        ``domain_error(http_client_websocket_url,URL)``
|    ``URL`` uses an unsupported WebSocket scheme:
|        ``domain_error(http_client_websocket_scheme,Scheme)``
|    The WebSocket server rejects the opening handshake version:
|        ``domain_error(http_client_websocket_version_rejection,Response)``
|    The WebSocket server rejects authentication:
|        ``domain_error(http_client_websocket_authentication_rejection,Response)``
|    The WebSocket server redirects the opening handshake:
|        ``domain_error(http_client_websocket_redirection_rejection,Response)``
|    The WebSocket server rejects the opening handshake:
|        ``domain_error(http_client_websocket_rejection,Response)``
|    The WebSocket server response is not a valid opening handshake response:
|        ``domain_error(http_client_websocket_response,Response)``
|    ``Handler`` is a variable:
|        ``instantiation_error``
|    ``Handler`` is not a valid WebSocket service handler:
|        ``domain_error(http_websocket_service_handler,Handler)``
|    The upgraded connection handle is invalid:
|        ``domain_error(http_socket_transport_connection,Connection)``
|    The delegated session loop raises a WebSocket session error:
|        ``domain_error(http_websocket_session_sequence,Frame)``
|    ``Handler`` returns an invalid reply:
|        ``domain_error(http_websocket_service_handler_reply,Reply)``


------------

.. index:: open/5
.. _http_websocket_client_service/1::open/5:

``open/5``
^^^^^^^^^^

Builds a WebSocket opening handshake from the given absolute WebSocket URL supported by the selected transport parameterization, opens the upgraded connection, optionally writes initial outbound messages, then runs one callback-driven client session loop using the given combined handshake and session options.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``open(URL,Handler,Response,State,Options)``
| **Mode and number of proofs:**
|    ``open(+atom,+object_identifier,-compound,-compound,+list)`` - ``one_or_error``

| **Exceptions:**
|    ``URL`` is a variable:
|        ``instantiation_error``
|    ``URL`` is not a supported absolute WebSocket URL:
|        ``domain_error(http_client_websocket_url,URL)``
|    ``URL`` uses an unsupported WebSocket scheme:
|        ``domain_error(http_client_websocket_scheme,Scheme)``
|    ``Options`` is a variable or a partial list:
|        ``instantiation_error``
|    ``Options`` is neither a variable nor a list:
|        ``type_error(list,Options)``
|    ``Options`` contains an invalid initial message list:
|        ``type_error(list,Messages)``
|    ``Options`` contains an invalid initial message:
|        ``domain_error(http_websocket_client_service_initial_message,Message)``
|    ``Options`` contains an invalid automatic pong setting:
|        ``domain_error(http_websocket_client_service_option,auto_pong(Option))``
|    ``Options`` contains an invalid client service option:
|        ``domain_error(http_websocket_client_service_option,Option)``
|    ``Options`` contains an invalid WebSocket client option:
|        ``domain_error(http_client_websocket_option,Option)``
|    ``Options`` contains an invalid WebSocket HTTP version:
|        ``domain_error(http_client_websocket_version,Version)``
|    ``Options`` contains reserved WebSocket headers:
|        ``domain_error(http_client_websocket_headers,Headers)``
|    ``Options`` contains an invalid WebSocket service loop option:
|        ``domain_error(http_websocket_service_option,Option)``
|    Timed session-loop options are not available on this backend:
|        ``existence_error(http_websocket_service,timing)``
|    The WebSocket server rejects the opening handshake version:
|        ``domain_error(http_client_websocket_version_rejection,Response)``
|    The WebSocket server rejects authentication:
|        ``domain_error(http_client_websocket_authentication_rejection,Response)``
|    The WebSocket server redirects the opening handshake:
|        ``domain_error(http_client_websocket_redirection_rejection,Response)``
|    The WebSocket server rejects the opening handshake:
|        ``domain_error(http_client_websocket_rejection,Response)``
|    The WebSocket server response is not a valid opening handshake response:
|        ``domain_error(http_client_websocket_response,Response)``
|    ``Handler`` is a variable:
|        ``instantiation_error``
|    ``Handler`` is not a valid WebSocket service handler:
|        ``domain_error(http_websocket_service_handler,Handler)``
|    The upgraded connection handle is invalid:
|        ``domain_error(http_socket_transport_connection,Connection)``
|    The delegated session loop raises a WebSocket session error:
|        ``domain_error(http_websocket_session_sequence,Frame)``
|    ``Handler`` returns an invalid reply:
|        ``domain_error(http_websocket_service_handler_reply,Reply)``

| **Remarks:**

    - Repeated options: When the same handshake or session option is given multiple times, the first occurrence is used.
    - Handshake options: The `headers/1`, `query/1`, `version/1`, `protocols/1`, `key/1`, and `connection_options/1` options are forwarded to `open_websocket/4`. The accepted URL schemes depend on the selected transport parameterization, e.g. `ws://` for `http_socket_transport` and both `ws://` and `wss://` for `http_process_transport`.
    - Session option ``auto_pong(on|off)``: Controls automatic pong replies during the session loop.
    - Session option ``initial_messages(Messages)``: Writes the given list of normalized outbound messages before entering the session loop.
    - Session option ``keepalive_interval(Seconds)``: Schedules empty ping messages when the peer stays silent for the given positive number of seconds. This option requires backend thread support.
    - Session option ``idle_timeout(Seconds)``: Closes the session with ``status(1001, idle_timeout)`` after the given positive number of seconds without an inbound message. This option requires backend thread support.
    - Session option ``max_payload_length(Bytes)``: Rejects inbound frames whose declared payload length is greater than ``Bytes`` before allocating payload storage. Oversized frames are treated as ``1009`` close errors in the session loop. Use a non-negative integer.


------------

Protected predicates
--------------------

(no local declarations; see entity ancestors if any)

Private predicates
------------------

(no local declarations; see entity ancestors if any)

Operators
---------

(none)