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)