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( , , ). 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 *******************************/
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}.
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).
call(Goal, WebSocket)
,
where WebSocket is a socket-pair. Options:
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).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) ).
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).
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 *******************************/
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.text(+Text)
, provided for consistency.opcode
key. Other keys
used are:
string
, prolog
or json
. See ws_receive/3.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.
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]).
close
and data to the atom
end_of_file
.
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:
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).
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)).
close
message if
this was not already sent and wait for the close 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 ).
server
or client
. If client
, messages are sent
as masked.true
(default), closing WSStream also closes Stream.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).
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).
close
, close the stream.false
, it will wait for an
additional message.ping
is received, it will reply with a pong
on the
matching output stream.pong
is received, it will be ignored.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 ).
687ws_property(WebSocket, Property) :- 688 ws_property_(Property, WebSocket). 689 690ws_property_(subprotocol(Protocol), WebSocket) :- 691 ws_property(WebSocket, subprotocol, Protocol).
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 ).
713ws_opcode(continuation, 0). 714ws_opcode(text, 1). 715ws_opcode(binary, 2). 716ws_opcode(close, 8). 717ws_opcode(ping, 9). 718ws_opcode(pong, 10).
725:- public ws_mask/1. 726 727ws_mask(Mask) :- 728 Mask is 1+random(1<<32-1)
WebSocket support
WebSocket is a lightweight message oriented protocol on top of TCP/IP streams. It is typically used as an upgrade of an HTTP connection to provide bi-directional communication, but can also be used in isolation over arbitrary (Prolog) streams.
The SWI-Prolog interface is based on streams and provides ws_open/3 to create a websocket stream from any Prolog stream. Typically, both an input and output stream are wrapped and then combined into a single object using stream_pair/3.
The high-level interface provides http_upgrade_to_websocket/3 to realise a websocket inside the HTTP server infrastructure and http_open_websocket/3 as a layer over http_open/3 to realise a client connection. After establishing a connection, ws_send/2 and ws_receive/2 can be used to send and receive messages. The predicate ws_close/3 is provided to perform the closing handshake and dispose of the stream objects.