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:- use_module(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 if Goal succeeds. The websocket is closed if Goal fails or raises an exception. This can be used to create a single thread that manages multiple websockets using I/O multiplexing. See library(http/hub).

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.

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

 sec_websocket_accept(+Info, -AcceptKey) is det

Compute the accept key as per 4.2.2., point 5.4

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

 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.

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

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

  520read_text_data(string, WsStream,
  521          websocket{opcode:text, format:string, data:Data}, _Options) :-
  522    !,
  523    read_string(WsStream, _Len, Data).
  524read_text_data(json, WsStream,
  525          websocket{opcode:text, format:json,   data:Data}, Options) :-
  526    !,
  527    json_read_dict(WsStream, Data, Options).
  528read_text_data(prolog, WsStream,
  529          websocket{opcode:text, format:prolog, data:Data}, Options) :-
  530    !,
  531    read_term(WsStream, Data, Options).
  532read_text_data(Format, _, _, _) :-
  533    domain_error(format, Format).
  534
  535reply_pong(WebSocket, Data) :-
  536    stream_pair(WebSocket, _In, Out),
  537    is_stream(Out),
  538    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.

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

 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.

  687ws_property(WebSocket, Property) :-
  688    ws_property_(Property, WebSocket).
  689
  690ws_property_(subprotocol(Protocol), WebSocket) :-
  691    ws_property(WebSocket, subprotocol, Protocol).

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

Convert a specification of an opcode into the numeric opcode.

  697to_opcode(In, Code) :-
  698    integer(In),
  699    !,
  700    must_be(between(0, 15), In),
  701    Code = In.
  702to_opcode(Name, Code) :-
  703    must_be(atom, Name),
  704    (   ws_opcode(Name, Code)
  705    ->  true
  706    ;   domain_error(ws_opcode, Name)
  707    ).

 ws_opcode(?Name, ?Code)

Define symbolic names for the WebSocket opcodes.

  713ws_opcode(continuation, 0).
  714ws_opcode(text,         1).
  715ws_opcode(binary,       2).
  716ws_opcode(close,        8).
  717ws_opcode(ping,         9).
  718ws_opcode(pong,         10).

 ws_mask(-Mask)

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

  725:- public ws_mask/1.  726
  727ws_mask(Mask) :-
  728    Mask is 1+random(1<<32-1)