`Web::Transport::WSClient`

A WebSocket client

SYNOPSIS

  use Web::Transport::WSClient;
  Web::Transport::WSClient->new (
    url => Web::URL->parse_url (q<wss://server.test/p1>),
    cb => sub {
      my ($client, $data, $is_text) = @_;
      if (defined $is_text) { # text or binary
        if (defined $data) { # frame data
          $current_data .= $data;
        } else { # end of frame
          if ($is_text) { # text
            warn "Received |$current_data| (text)";
          } else { # binary
            warn "Received |$current_data| (binary)";
          }
          if ($current_data eq 'end') {
            $client->close;
          } else {
            $client->send_binary ("\x01");
          }
          $current_data = '';
        }
      } else { # handshake done
        $client->send_text ('Hello!');
        $current_data = '';
      }
    },
  )->then (sub {
    my $res = $_[0];
    if ($res->ws_closed_cleanly) {
      warn "Done!";
    } else {
      warn $res->ws_code, "\t", $res->ws_reason;
    }
  });

DESCRIPTION

The Web::Transport::WSClient module is a WebSocket client.

METHODS

There are following methods:

$promise = Web::Transport::WSClient->new (KEY => VALUE, ...)

Connect to a WebSocket server. The URL of the server, as well as various connection parameters, has to be specified as named arguments.

It returns a promise (Promise object), which is resolved with a response object (Web::Transport::Response object) when the connection is closed. (If the connection has failed, the promise is resolved with a response object representing the failure. If any argument to the method is incorrect, the promise is rejected.)

Following key/value pairs, including required url and cb options, are available as named arguments:

url => $url

Specify the URL (a Web::URL object) of the WebSocket server. Its scheme must be wss or ws.

This option is required.

headers => {$string => $string, ...}

cookies => {$string => $string, ...}

params => {$string => $string, ...}

basic_auth => [$userid, $password]

bearer => $string

oauth1 => [$string, $string, $string, $string]

oauth1_container => 'authorization' | 'query'

superreload => $boolean

See "REQUEST OPTIONS" in Web::Transport.

proxy_manager => $pm

Specify the proxy manager used to establish the connection. By default, a proxy manager which takes standard environment variables into account (i.e. Web::Transport::ENVProxyManager) is set as the proxy manager.

resolver => $resolver

Specify the name resolver used to establish the connection. By default, a resolver using system's name resolution API (Web::Transport::PlatformResolver) wrapped by DNS caching (Web::Transport::CachedResolver) is set as the resolver.

Please note that this clock cannot alter the value used in OpenSSL.

protocol_clock => $clock

Specify the clock object used for various protocol-level date-time operations (e.g. obtaining timestamps used in authentications). A clock of Web::DateTime::Clock->realtime_clock is used by default.

tls_options => {...}

XXX

debug => $mode

Specify the debug mode. The default value is the WEBUA_DEBUG environment variable's value. See WEBUA_DEBUG section in Web::Transport for available mode values.

cb => $code

Specify the callback subroutine. The value must be a code reference. This option must be specified.

When a WebSocket connection has successfully established, $code is invoked with three arguments: the client object, undef, and undef.

Whenever a WebSocket text or binary message has received, $code is invoked zero or more times with partial data $data, and then is invoked with undef. It is invoked with three arguments: the client object, $data or undef, and $is_binary. The concatenation of $data, in order, represents the received message's data. If the message's data is binary, $is_binary is true. Otherwise, $is_binary is false.

If the connection is failed while receiving a message, the final invocation with undef argument might not happen.

$client->send_text ($text)

Send a text message. The argument must be a character string.

$client->send_binary ($bytes)

Send a binary message. The argument must be a byte string.

$promise = $client->close

Close any connection. It returns a promise, which is to be resolved once the connection has been closed.

ENVIRONMENT VARIABLES

This module supports WEBUA_DEBUG. See Web::Transport.

When the default resolver is used, proxy environment variables http_proxy, https_proxy, ftp_proxy, and no_proxy are taken into account. See Web::Transport::ENVProxyManager.

SPECIFICATION

Web Transport Processing <https://wiki.suikawiki.org/n/Web%20Transport%20Processing>.

AUTHOR

Wakaba <wakaba@suikawiki.org>.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The manakai project

Web::Transport::WSClient