1/*  Part of SWI-Prolog
    2
    3    Author:        Jan Wielemaker
    4    E-mail:        J.Wielemaker@vu.nl
    5    WWW:           http://www.swi-prolog.org
    6    Copyright (c)  2014-2015, VU University Amsterdam
    7    All rights reserved.
    8
    9    Redistribution and use in source and binary forms, with or without
   10    modification, are permitted provided that the following conditions
   11    are met:
   12
   13    1. Redistributions of source code must retain the above copyright
   14       notice, this list of conditions and the following disclaimer.
   15
   16    2. Redistributions in binary form must reproduce the above copyright
   17       notice, this list of conditions and the following disclaimer in
   18       the documentation and/or other materials provided with the
   19       distribution.
   20
   21    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   22    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   23    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
   24    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
   25    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
   26    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
   27    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
   28    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
   29    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   30    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
   31    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
   32    POSSIBILITY OF SUCH DAMAGE.
   33*/
   34
   35:- module(websocket,
   36          [ http_open_websocket/3,      % +URL, -WebSocket, +Options
   37            http_upgrade_to_websocket/3, % :Goal, +Options, +Request
   38            ws_send/2,                  % +WebSocket, +Message
   39            ws_receive/2,               % +WebSocket, -Message
   40            ws_receive/3,               % +WebSocket, -Message, +Options
   41            ws_close/3,                 % +WebSocket, +Code, +Message
   42                                        % Low level interface
   43            ws_open/3,                  % +Stream, -WebSocket, +Options
   44            ws_property/2               % +WebSocket, ?Property
   45          ]).   46:- autoload(library(base64),[base64//1]).   47:- autoload(library(debug),[debug/3]).   48:- autoload(library(error),
   49	    [permission_error/3,must_be/2,type_error/2,domain_error/2]).   50:- autoload(library(lists),[member/2]).   51:- autoload(library(option),[select_option/3,option/2,option/3]).   52:- autoload(library(sha),[sha_hash/3]).   53:- autoload(library(http/http_dispatch),[http_switch_protocol/2]).   54:- autoload(library(http/http_open),[http_open/3]).   55:- autoload(library(http/json),[json_write_dict/2,json_read_dict/3]).   56
   57:- meta_predicate
   58    http_upgrade_to_websocket(1, +, +).   59
   60:- predicate_options(http_open_websocket/3, 3,
   61                     [ subprotocols(list(atom)),
   62                       pass_to(http_open:http_open/3, 3)
   63                     ]).   64:- predicate_options(http_upgrade_to_websocket/3, 2,
   65                     [ guarded(boolean),
   66                       subprotocols(list(atom))
   67                     ]).   68
   69:- use_foreign_library(foreign(websocket)).

   97                 /*******************************
   98                 *         HTTP SUPPORT         *
   99                 *******************************/

 http_open_websocket(+URL, -WebSocket, +Options) is det

Establish a client websocket connection. This predicate calls http_open/3 with additional headers to negotiate a websocket connection. In addition to the options processed by http_open/3, the following options are recognised:

subprotocols(+List)

List of subprotocols that are acceptable. The selected protocol is available as ws_property(WebSocket, subprotocol(Protocol).

Note that clients often provide an Origin header and some servers require this field. See RFC 6455 for details. By default this predicate does not set Origin. It may be set using the request_header option of http_open/3, e.g. by passing this in the Options list:

request_header('Origin' = 'https://www.swi-prolog.org')

The following example exchanges a message with the html5rocks.websocket.org echo service:

?- URL = 'ws://html5rocks.websocket.org/echo',
   http_open_websocket(URL, WS, []),
   ws_send(WS, text('Hello World!')),
   ws_receive(WS, Reply),
   ws_close(WS, 1000, "Goodbye").
URL = 'ws://html5rocks.websocket.org/echo',
WS = <stream>(0xe4a440,0xe4a610),
Reply = websocket{data:"Hello World!", opcode:text}.

Arguments:

WebSocket

- is a stream pair (see stream_pair/3)

  137http_open_websocket(URL, WebSocket, Options) :-
  138    phrase(base64(`___SWI-Prolog___`), Bytes),
  139    string_codes(Key, Bytes),
  140    add_subprotocols(Options, Options1),
  141    http_open(URL, In,
  142              [ status_code(Status),
  143                output(Out),
  144                header(sec_websocket_protocol, Selected),
  145                header(sec_websocket_accept, AcceptedKey),
  146                connection('Keep-alive, Upgrade'),
  147                request_header('Upgrade' = websocket),
  148                request_header('Sec-WebSocket-Key' = Key),
  149                request_header('Sec-WebSocket-Version' = 13)
  150              | Options1
  151              ]),
  152    (   Status == 101,
  153        sec_websocket_accept(_{key:Key}, AcceptedKey)
  154    ->  ws_client_options(Selected, WsOptions),
  155        stream_pair(In,  Read, Write),      % Old API: In and Out
  156        stream_pair(Out, Read, Write),      % New API: In == Out (= pair)
  157        ws_open(Read,  WsIn,  WsOptions),
  158        ws_open(Write, WsOut, WsOptions),
  159        stream_pair(WebSocket, WsIn, WsOut)
  160    ;   close(Out),
  161        close(In),
  162        permission_error(open, websocket, URL)
  163    ).
  164
  165ws_client_options('',          [mode(client)]) :- !.
  166ws_client_options(null,        [mode(client)]) :- !.
  167ws_client_options(Subprotocol, [mode(client), subprotocol(Subprotocol)]).
  168
  169add_subprotocols(OptionsIn, OptionsOut) :-
  170    select_option(subprotocols(Subprotocols), OptionsIn, Options1),
  171    !,
  172    must_be(list(atom), Subprotocols),
  173    atomic_list_concat(Subprotocols, ', ', Value),
  174    OptionsOut = [ request_header('Sec-WebSocket-Protocol' = Value)
  175                 | Options1
  176                 ].
  177add_subprotocols(Options, Options).

 http_upgrade_to_websocket(:Goal, +Options, +Request)

Create a websocket connection running call(Goal, WebSocket), where WebSocket is a socket-pair. Options:

guarded(+Boolean)

If true (default), guard the execution of Goal and close the websocket on both normal and abnormal termination of Goal. If false, Goal itself is responsible for the created websocket. This can be used to create a single thread that manages multiple websockets using I/O multiplexing.

subprotocols(+List)

List of acceptable subprotocols.

timeout(+TimeOut)

Timeout to apply to the input stream. Default is infinite.

Note that the Request argument is the last for cooperation with http_handler/3. A simple echo server that can be accessed at =/ws/= can be implemented as:

:- use_module(library(http/websocket)).
:- use_module(library(http/thread_httpd)).
:- use_module(library(http/http_dispatch)).

:- http_handler(root(ws),
                http_upgrade_to_websocket(echo, []),
                [spawn([])]).

echo(WebSocket) :-
    ws_receive(WebSocket, Message),
    (   Message.opcode == close
    ->  true
    ;   ws_send(WebSocket, Message),
        echo(WebSocket)
    ).

throws

- switching_protocols(Goal, Options). The recovery from this exception causes the HTTP infrastructure to call call(Goal, WebSocket).

See also

- http_switch_protocol/2.

  225http_upgrade_to_websocket(Goal, Options, Request) :-
  226    request_websocket_info(Request, Info),
  227    debug(websocket(open), 'Websocket request: ~p', [Info]),
  228    sec_websocket_accept(Info, AcceptKey),
  229    choose_subprotocol(Info, Options, SubProtocol, ExtraHeaders),
  230    debug(websocket(open), 'Subprotocol: ~p', [SubProtocol]),
  231    http_switch_protocol(
  232        open_websocket(Goal, SubProtocol, Options),
  233        [ header([ upgrade(websocket),
  234                   connection('Upgrade'),
  235                   sec_websocket_accept(AcceptKey)
  236                 | ExtraHeaders
  237                 ])
  238        ]).
  239
  240choose_subprotocol(Info, Options, SubProtocol, ExtraHeaders) :-
  241    HdrValue = Info.get(subprotocols),
  242    option(subprotocols(ServerProtocols), Options),
  243    split_string(HdrValue, ",", " ", RequestProtocols),
  244    member(Protocol, RequestProtocols),
  245    member(SubProtocol, ServerProtocols),
  246    atom_string(SubProtocol, Protocol),
  247    !,
  248    ExtraHeaders = [ 'Sec-WebSocket-Protocol'(SubProtocol) ].
  249choose_subprotocol(_, _, null, []).
  250
  251open_websocket(Goal, SubProtocol, Options, HTTPIn, HTTPOut) :-
  252    option(timeout(TimeOut), Options, infinite),
  253    set_stream(HTTPIn, timeout(TimeOut)),
  254    WsOptions = [mode(server), subprotocol(SubProtocol)],
  255    ws_open(HTTPIn, WsIn, WsOptions),
  256    ws_open(HTTPOut, WsOut, WsOptions),
  257    stream_pair(WebSocket, WsIn, WsOut),
  258    (   option(guarded(true), Options, true)
  259    ->  guard_websocket_server(Goal, WebSocket)
  260    ;   call(Goal, WebSocket)
  261    ).
  262
  263guard_websocket_server(Goal, WebSocket) :-
  264    (   catch(call(Goal, WebSocket), E, true)
  265    ->  (   var(E)
  266        ->  Msg = bye, Code = 1000
  267        ;   message_to_string(E, Msg),
  268            Code = 1011
  269        )
  270    ;   Msg = "goal failed", Code = 1011
  271    ),
  272    catch(ws_close(WebSocket, Code, Msg), Error,
  273          print_message(error, Error)).
  274
  275
  276request_websocket_info(Request, Info) :-
  277    option(upgrade(Websocket), Request),
  278    downcase_atom(Websocket, websocket),
  279    option(connection(Connection), Request),
  280    connection_contains_upgrade(Connection),
  281    option(sec_websocket_key(ClientKey), Request),
  282    option(sec_websocket_version(Version), Request),
  283    Info0 = _{key:ClientKey, version:Version},
  284    add_option(origin,                   Request, origin,       Info0, Info1),
  285    add_option(sec_websocket_protocol,   Request, subprotocols, Info1, Info2),
  286    add_option(sec_websocket_extensions, Request, extensions,   Info2, Info).
  287
  288connection_contains_upgrade(Connection) :-
  289    split_string(Connection, ",", " ", Tokens),
  290    member(Token, Tokens),
  291    string_lower(Token, "upgrade"),
  292    !.
  293
  294add_option(OptionName, Request, Key, Dict0, Dict) :-
  295    Option =.. [OptionName,Value],
  296    option(Option, Request),
  297    !,
  298    Dict = Dict0.put(Key,Value).
  299add_option(_, _, _, Dict, Dict).

 sec_websocket_accept(+Info, -AcceptKey) is det

Compute the accept key as per 4.2.2., point 5.4

  305sec_websocket_accept(Info, AcceptKey) :-
  306    string_concat(Info.key, "258EAFA5-E914-47DA-95CA-C5AB0DC85B11", Str),
  307    sha_hash(Str, Hash, [ algorithm(sha1) ]),
  308    phrase(base64(Hash), Encoded),
  309    string_codes(AcceptKey, Encoded).
  310
  311
  312                 /*******************************
  313                 *     HIGH LEVEL INTERFACE     *
  314                 *******************************/

 ws_send(+WebSocket, +Message) is det

Send a message over a websocket. The following terms are allowed for Message:

text(+Text)

Send a text message. Text is serialized using write/1.

binary(+Content)

As text(+Text), but all character codes produced by Content must be in the range [0..255]. Typically, Content will be an atom or string holding binary data.

prolog(+Term)

Send a Prolog term as a text message. Text is serialized using write_canonical/1.

json(+JSON)

Send the Prolog representation of a JSON term using json_write_dict/2.

string(+Text)

Same as text(+Text), provided for consistency.

close(+Code, +Text)

Send a close message. Code is 1000 for normal close. See websocket documentation for other values.

Dict

A dict that minimally contains an opcode key. Other keys used are:

format:Format

Serialization format used for Message.data. Format is one of string, prolog or json. See ws_receive/3.

data:Term

If this key is present, it is serialized according to Message.format. Otherwise it is serialized using write/1, which implies that string and atoms are just sent verbatim.

Note that ws_start_message/3 does not unlock the stream. This is done by ws_send/1. This implies that multiple threads can use ws_send/2 and the messages are properly serialized.

To be done

- Provide serialization details using options.

  358ws_send(WsStream, Message) :-
  359    message_opcode(Message, OpCode),
  360    setup_call_cleanup(
  361        ws_start_message(WsStream, OpCode, 0),
  362        write_message_data(WsStream, Message),
  363        ws_send(WsStream)).
  364
  365message_opcode(Message, OpCode) :-
  366    is_dict(Message),
  367    !,
  368    to_opcode(Message.opcode, OpCode).
  369message_opcode(Message, OpCode) :-
  370    functor(Message, Name, _),
  371    (   text_functor(Name)
  372    ->  to_opcode(text, OpCode)
  373    ;   to_opcode(Name, OpCode)
  374    ).
  375
  376text_functor(json).
  377text_functor(string).
  378text_functor(prolog).
  379
  380write_message_data(Stream, Message) :-
  381    is_dict(Message),
  382    !,
  383    (   _{code:Code, data:Data} :< Message
  384    ->  write_message_data(Stream, close(Code, Data))
  385    ;   _{format:prolog, data:Data} :< Message
  386    ->  format(Stream, '~k .~n', [Data])
  387    ;   _{format:json, data:Data} :< Message
  388    ->  json_write_dict(Stream, Data)
  389    ;   _{data:Data} :< Message
  390    ->  format(Stream, '~w', Data)
  391    ;   true
  392    ).
  393write_message_data(Stream, Message) :-
  394    functor(Message, Format, 1),
  395    !,
  396    arg(1, Message, Data),
  397    (   text_functor(Format)
  398    ->  write_text_message(Format, Stream, Data)
  399    ;   format(Stream, '~w', [Data])
  400    ).
  401write_message_data(_, Message) :-
  402    atom(Message),
  403    !.
  404write_message_data(Stream, close(Code, Data)) :-
  405    !,
  406    High is (Code >> 8) /\ 0xff,
  407    Low  is Code /\ 0xff,
  408    put_byte(Stream, High),
  409    put_byte(Stream, Low),
  410    stream_pair(Stream, _, Out),
  411    set_stream(Out, encoding(utf8)),
  412    format(Stream, '~w', [Data]).
  413write_message_data(_, Message) :-
  414    type_error(websocket_message, Message).
  415
  416write_text_message(json, Stream, Data) :-
  417    !,
  418    json_write_dict(Stream, Data).
  419write_text_message(prolog, Stream, Data) :-
  420    !,
  421    format(Stream, '~k .', [Data]).
  422write_text_message(_, Stream, Data) :-
  423    format(Stream, '~w', [Data]).

 ws_receive(+WebSocket, -Message:dict) is det

 ws_receive(+WebSocket, -Message:dict, +Options) is det

Receive the next message from WebSocket. Message is a dict containing the following keys:

opcode:OpCode

OpCode of the message. This is an atom for known opcodes and an integer for unknown ones. If the peer closed the stream, OpCode is bound to close and data to the atom end_of_file.

data:String

The data, represented as a string. This field is always present. String is the empty string if there is no data in the message.

rsv:RSV

Present if the WebSocket RSV header is not 0. RSV is an integer in the range [1..7].

If ping message is received and WebSocket is a stream pair, ws_receive/1 replies with a pong and waits for the next message.

The predicate ws_receive/3 processes the following options:

format(+Format)

Defines how text messages are parsed. Format is one of

string

Data is returned as a Prolog string (default)

json

Data is parsed using json_read_dict/3, which also receives Options.

prolog

Data is parsed using read_term/3, which also receives Options.

To be done

- Add a hook to allow for more data formats?

  465ws_receive(WsStream, Message) :-
  466    ws_receive(WsStream, Message, []).
  467
  468ws_receive(WsStream, Message, Options) :-
  469    ws_read_header(WsStream, Code, RSV),
  470    debug(websocket, 'ws_receive(~p): OpCode=~w, RSV=~w',
  471          [WsStream, Code, RSV]),
  472    (   Code == end_of_file
  473    ->  Message = websocket{opcode:close, data:end_of_file}
  474    ;   (   ws_opcode(OpCode, Code)
  475        ->  true
  476        ;   OpCode = Code
  477        ),
  478        read_data(OpCode, WsStream, Data, Options),
  479        (   OpCode == ping,
  480            reply_pong(WsStream, Data.data)
  481        ->  ws_receive(WsStream, Message, Options)
  482        ;   (   RSV == 0
  483            ->  Message = Data
  484            ;   Message = Data.put(rsv, RSV)
  485            )
  486        )
  487    ),
  488    debug(websocket, 'ws_receive(~p) --> ~p', [WsStream, Message]).
  489
  490read_data(close, WsStream,
  491          websocket{opcode:close, code:Code, format:string, data:Data}, _Options) :-
  492    !,
  493    get_byte(WsStream, High),
  494    (   High == -1
  495    ->  Code = 1000,
  496        Data = ""
  497    ;   get_byte(WsStream, Low),
  498        Code is High<<8 \/ Low,
  499        stream_pair(WsStream, In, _),
  500        set_stream(In, encoding(utf8)),
  501        read_string(WsStream, _Len, Data)
  502    ).
  503read_data(text, WsStream, Data, Options) :-
  504    !,
  505    option(format(Format), Options, string),
  506    read_text_data(Format, WsStream, Data, Options).
  507read_data(OpCode, WsStream, websocket{opcode:OpCode, format:string, data:Data}, _Options) :-
  508    read_string(WsStream, _Len, Data).

 read_text_data(+Format, +WsStream, -Dict, +Options) is det

Read a websocket message into a dict websocket{opcode:OpCode, data:Data}, where Data is parsed according to Format.

  515read_text_data(string, WsStream,
  516          websocket{opcode:text, format:string, data:Data}, _Options) :-
  517    !,
  518    read_string(WsStream, _Len, Data).
  519read_text_data(json, WsStream,
  520          websocket{opcode:text, format:json,   data:Data}, Options) :-
  521    !,
  522    json_read_dict(WsStream, Data, Options).
  523read_text_data(prolog, WsStream,
  524          websocket{opcode:text, format:prolog, data:Data}, Options) :-
  525    !,
  526    read_term(WsStream, Data, Options).
  527read_text_data(Format, _, _, _) :-
  528    domain_error(format, Format).
  529
  530reply_pong(WebSocket, Data) :-
  531    stream_pair(WebSocket, _In, Out),
  532    is_stream(Out),
  533    ws_send(Out, pong(Data)).

 ws_close(+WebSocket:stream_pair, +Code, +Data) is det

Close a WebSocket connection by sending a close message if this was not already sent and wait for the close reply.

Arguments:

Code	- is the numerical code indicating the close status. This is 16-bit integer. The codes are defined in section 7.4.1. Defined Status Codes of RFC6455. Notably, 1000 indicates a normal closure.
Data	- is currently interpreted as text.

Errors

- websocket_error(unexpected_message, Reply) if the other side did not send a close message in reply.

  549ws_close(WebSocket, Code, Data) :-
  550    setup_call_cleanup(
  551        true,
  552        ws_close_(WebSocket, Code, Data),
  553        close(WebSocket)).
  554
  555ws_close_(WebSocket, Code, Data) :-
  556    stream_pair(WebSocket, In, Out),
  557    (   (   var(Out)
  558        ;   ws_property(Out, status, closed)
  559        )
  560    ->  debug(websocket(close),
  561              'Output stream of ~p already closed', [WebSocket])
  562    ;   ws_send(WebSocket, close(Code, Data)),
  563        close(Out),
  564        debug(websocket(close), '~p: closed output', [WebSocket]),
  565        (   (   var(In)
  566            ;   ws_property(In, status, closed)
  567            )
  568        ->  debug(websocket(close),
  569                  'Input stream of ~p already closed', [WebSocket])
  570        ;   ws_receive(WebSocket, Reply),
  571            (   Reply.opcode == close
  572            ->  debug(websocket(close), '~p: close confirmed', [WebSocket])
  573            ;   throw(error(websocket_error(unexpected_message, Reply), _))
  574            )
  575        )
  576    ).

 ws_open(+Stream, -WSStream, +Options) is det

Turn a raw TCP/IP (or any other binary stream) into a websocket stream. Stream can be an input stream, output stream or a stream pair. Options includes

mode(+Mode)

One of server or client. If client, messages are sent as masked.

buffer_size(+Count)

Send partial messages for each Count bytes or when flushing the output. The default is to buffer the entire message before it is sent.

close_parent(+Boolean)

If true (default), closing WSStream also closes Stream.

subprotocol(+Protocol)

Set the subprotocol property of WsStream. This value can be retrieved using ws_property/2. Protocol is an atom. See also the subprotocols option of http_open_websocket/3 and http_upgrade_to_websocket/3.

A typical sequence to turn a pair of streams into a WebSocket is here:

    ...,
    Options = [mode(server), subprotocol(chat)],
    ws_open(Input, WsInput, Options),
    ws_open(Output, WsOutput, Options),
    stream_pair(WebSocket, WsInput, WsOutput).

 ws_start_message(+WSStream, +OpCode) is det

 ws_start_message(+WSStream, +OpCode, +RSV) is det

Prepare for sending a new message. OpCode is one of text, binary, close, ping or pong. RSV is reserved for extensions. After this call, the application usually writes data to WSStream and uses ws_send/1 to complete the message. Depending on OpCode, the stream is switched to binary (for OpCode is binary) or text using utf8 encoding (all other OpCode values). For example, to a JSON message can be send using:

ws_send_json(WSStream, JSON) :-
   ws_start_message(WSStream, text),
   json_write(WSStream, JSON),
   ws_send(WSStream).

 ws_send(+WSStream) is det

Complete and send the WebSocket message. If the OpCode of the message is close, close the stream.

 ws_read_header(+WSStream, -OpCode, -RSV) is det

Read the header of the WebSocket next message. After this call, WSStream is switched to the appropriate encoding and reading from the stream will signal end-of-file at the end of the message. Note that this end-of-file does not invalidate WSStream. Reading may perform various tasks on the background:

• If the message has Fin is false, it will wait for an additional message.
• If a ping is received, it will reply with a pong on the matching output stream.
• If a pong is received, it will be ignored.
• If a close is received and a partial message is read, it generates an exception (TBD: which?). If no partial message is received, it unified OpCode with close and replies with a close message.

If not all data has been read for the previous message, it will first read the remainder of the message. This input is silently discarded. This allows for trailing white space after proper text messages such as JSON, Prolog or XML terms. For example, to read a JSON message, use:

ws_read_json(WSStream, JSON) :-
    ws_read_header(WSStream, OpCode, RSV),
    (   OpCode == text,
        RSV == 0
    ->  json_read(WSStream, JSON)
    ;   OpCode == close
    ->  JSON = end_of_file
    ).

 ws_property(+WebSocket, ?Property) is nondet

True if Property is a property WebSocket. Defined properties are:

subprotocol(Protocol)

Protocol is the negotiated subprotocol. This is typically set as a property of the websocket by ws_open/3.

  682ws_property(WebSocket, Property) :-
  683    ws_property_(Property, WebSocket).
  684
  685ws_property_(subprotocol(Protocol), WebSocket) :-
  686    ws_property(WebSocket, subprotocol, Protocol).

 to_opcode(+Spec, -OpCode:int) is det

Convert a specification of an opcode into the numeric opcode.

  692to_opcode(In, Code) :-
  693    integer(In),
  694    !,
  695    must_be(between(0, 15), In),
  696    Code = In.
  697to_opcode(Name, Code) :-
  698    must_be(atom, Name),
  699    (   ws_opcode(Name, Code)
  700    ->  true
  701    ;   domain_error(ws_opcode, Name)
  702    ).

 ws_opcode(?Name, ?Code)

Define symbolic names for the WebSocket opcodes.

  708ws_opcode(continuation, 0).
  709ws_opcode(text,         1).
  710ws_opcode(binary,       2).
  711ws_opcode(close,        8).
  712ws_opcode(ping,         9).
  713ws_opcode(pong,         10).

 ws_mask(-Mask)

Produce a good random number of the mask of a client message.

  720:- public ws_mask/1.  721
  722ws_mask(Mask) :-
  723    Mask is 1+random(1<<32-1)