FUNCTIONS

promise(\@code_and_reason) = connect( %OPTS )

Starts a WebSocket connection. Returns a promise that indicates that connection’s final status.

Required %OPTS are:

• url - The target URL (e.g., ws://echo.websocket.org)

• event - The event loop interface to use. Recognized values are:

  • AnyEvent - to use AnyEvent

  • A two-member arrayref of [ 'IOAsync', $loop ] where $loop is an IO::Async::Loop instance.

• on_ready - Callback that “runs” the WebSocket connection once started. Receives a Net::Libwebsockets::WebSocket::Courier instance. If this throws, that exception will cause connect()’s returned promise to reject with that value.

Optional %OPTS are:

• tls - bitmask of TLS connection options, e.g., Net::Libwebsockets::LCCSCF_ALLOW_SELFSIGNED. Should be a mask of zero or more of:

  • Net::Libwebsockets::LCCSCF_ALLOW_SELFSIGNED

  • Net::Libwebsockets::LCCSCF_SKIP_SERVER_CERT_HOSTNAME_CHECK

  • Net::Libwebsockets::LCCSCF_ALLOW_EXPIRED

  • Net::Libwebsockets::LCCSCF_ALLOW_INSECURE

• subprotocols - arrayref of subprotocols to send

• compression - One of:

  • A simple string that names the compression type to use. Currently deflate is the only accepted value; this indicates permessage-deflate in its default configuration.

  • An arrayref of compression setups to try. Each setup is a compression name (again, only deflate is accepted) and an optional hashref of attributes.

    For permessage-deflate those attributes can be any or all of:

    • local_context_mode - one of:

      • takeover - retain deflate’s dictionary between messages

      • no_takeover - new dictionary for each message

    • peer_context_mode - ^^ ditto

    • local_max_window_bits

    • peer_max_window_bits

    See permessage-deflate’s specification for more about these options.

    If this option is not given, we’ll use the “best default” available; currently that means permessage-deflate in its default configuration if it’s available, or none if Libwebsockets lacks WebSocket compression support.

• headers - An arrayref of key-value pairs, e.g., [ 'X-Foo' => 'foo', 'X-Bar' => 'bar' ].

• ping_interval - The amount of time (in seconds) between pings that we’ll send. Defaults to 30 seconds.

• ping_timeout - The amount of time (in seconds) before we drop the connection. Defaults to 4m59s.

Return Value

Returns a promise that completes once the WebSocket connection is done. If the connection shuts down successfully then the promise resolves with an array reference of [ $code, $reason ]; otherwise the promise rejects with one of:

• Net::Libwebsockets::X::WebSocketClose

• Net::Libwebsockets::X::ConnectionFailed

• Net::Libwebsockets::X::General