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 http_websocket_service(HTTPTransport,client,atom)
Uses:
http_client
list
user
Remarks:
(none)
Inherited public predicates:
 initial_state/1  is_message/1  is_state/1  message/3  payload/2  read_message/2  read_message/4  read_message/5  read_message/6  run_session/3  run_session/4  type/2  write_message/2  write_message/3  write_message/4  write_message/5

Public predicates

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)

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)