kibi-swipl-linux-x64-gnu 1.0.0

package/lib/swipl/library/ext/clib/socket.pl

@@ -0,0 +1,1102 @@
+/*  Part of SWI-Prolog
+
+    Author:        Jan Wielemaker
+    E-mail:        J.Wielemaker@vu.nl
+    WWW:           http://www.swi-prolog.org
+    Copyright (c)  2000-2023, University of Amsterdam
+                              VU University Amsterdam
+                              CWI, Amsterdam
+                              SWI-Prolog Solutions b.v.
+    All rights reserved.
+
+    Redistribution and use in source and binary forms, with or without
+    modification, are permitted provided that the following conditions
+    are met:
+
+    1. Redistributions of source code must retain the above copyright
+       notice, this list of conditions and the following disclaimer.
+
+    2. Redistributions in binary form must reproduce the above copyright
+       notice, this list of conditions and the following disclaimer in
+       the documentation and/or other materials provided with the
+       distribution.
+
+    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+    POSSIBILITY OF SUCH DAMAGE.
+*/
+
+:- module(socket,
+          [ socket_create/2,		% -Socket, +Options
+	    tcp_socket/1,               % -Socket
+            tcp_close_socket/1,         % +Socket
+            tcp_open_socket/3,          % +Socket, -Read, -Write
+            tcp_connect/2,              % +Socket, +Address
+            tcp_connect/3,              % +Address, -StreamPair, +Options
+            tcp_connect/4,              % +Socket, +Address, -Read, -Write)
+            tcp_bind/2,                 % +Socket, +Address
+            tcp_accept/3,               % +Master, -Slave, -PeerName
+            tcp_listen/2,               % +Socket, +BackLog
+            tcp_fcntl/3,                % +Socket, +Command, ?Arg
+            tcp_setopt/2,               % +Socket, +Option
+            tcp_getopt/2,               % +Socket, ?Option
+            host_address/3,		% ?HostName, ?Address, +Options
+            tcp_host_to_address/2,      % ?HostName, ?Ip-nr
+            tcp_select/3,               % +Inputs, -Ready, +Timeout
+            gethostname/1,              % -HostName
+
+            ip_name/2,			% ?Ip, ?Name
+
+            tcp_open_socket/2,          % +Socket, -StreamPair
+
+            udp_socket/1,               % -Socket
+            udp_receive/4,              % +Socket, -Data, -Sender, +Options
+            udp_send/4,                 % +Socket, +Data, +Sender, +Options
+
+            negotiate_socks_connection/2% +DesiredEndpoint, +StreamPair
+          ]).
+:- use_module(library(debug), [assertion/1, debug/3]).
+:- autoload(library(lists), [last/2, member/2, append/3, append/2]).
+:- autoload(library(apply), [maplist/3, maplist/2]).
+:- autoload(library(error),
+            [instantiation_error/1, syntax_error/1, must_be/2, domain_error/2]).
+:- autoload(library(option), [option/2, option/3]).
+
+:- multifile
+    rewrite_host/3.                     % +HostIn, -Host, +Socket
+
+/** <module> Network socket (TCP and UDP) library
+
+The library(socket) provides  TCP  and   UDP  inet-domain  sockets  from
+SWI-Prolog, both client and server-side  communication. The interface of
+this library is very close to the  Unix socket interface, also supported
+by the MS-Windows _winsock_ API. SWI-Prolog   applications  that wish to
+communicate with multiple sources have two options:
+
+  - Use I/O multiplexing based on wait_for_input/3.  On Windows
+    systems this can only be used for sockets, not for general
+    (device-) file handles.
+  - Use multiple threads, handling either a single blocking socket
+    or a pool using I/O multiplexing as above.
+
+## Client applications  {#socket-server}
+
+Using this library to establish  a  TCP   connection  to  a server is as
+simple as opening a file.  See also http_open/3.
+
+==
+dump_swi_homepage :-
+    setup_call_cleanup(
+        tcp_connect('www.swi-prolog.org':http, Stream, []),
+        ( format(Stream,
+                 'GET / HTTP/1.1~n\c
+                  Host: www.swi-prolog.org~n\c
+                  Connection: close~n~n', []),
+          flush_output(Stream),
+          copy_stream_data(Stream, current_output)
+        ),
+        close(Stream)).
+==
+
+To   deal   with   timeouts   and     multiple   connections,   threads,
+wait_for_input/3 and/or non-blocking streams (see   tcp_fcntl/3)  can be
+used.
+
+## Server applications  {#socket-client}
+
+The typical sequence for generating a server application is given below.
+To close the server, use close/1 on the `StreamPair`.
+
+  ==
+  create_server(Port) :-
+        tcp_socket(Socket),
+        tcp_bind(Socket, Port),
+        tcp_listen(Socket, 5),
+        tcp_open_socket(Socket, StreamPair),
+        stream_pair(StreamPair, AcceptFd, _),
+        <dispatch>
+  ==
+
+There are various options for <dispatch>.  The most commonly used option
+is to start a Prolog  thread   to  handle the connection. Alternatively,
+input from multiple clients  can  be  handled   in  a  single  thread by
+listening to these clients  using   wait_for_input/3.  Finally,  on Unix
+systems, we can use fork/1 to handle   the  connection in a new process.
+Note that fork/1 and threads do not  cooperate well. Combinations can be
+realised  but  require  good   understanding    of   POSIX   thread  and
+fork-semantics.
+
+Below  is  the  typical  example  using  a   thread.  Note  the  use  of
+setup_call_cleanup/3 to guarantee that all resources are reclaimed, also
+in case of failure or exceptions.
+
+  ==
+  dispatch(AcceptFd) :-
+          tcp_accept(AcceptFd, Socket, Peer),
+          thread_create(process_client(Socket, Peer), _,
+                        [ detached(true)
+                        ]),
+          dispatch(AcceptFd).
+
+  process_client(Socket, Peer) :-
+          setup_call_cleanup(
+              tcp_open_socket(Socket, StreamPair),
+              handle_service(StreamPair),
+              close(StreamPair)).
+
+  handle_service(StreamPair) :-
+          ...
+  ==
+
+## Socket exceptions			{#socket-exceptions}
+
+Errors that are trapped by  the  low-level   library  are  mapped  to an
+exception of the shape below. In this term,  `Code` is a lower case atom
+that corresponds to the C macro name,   e.g., `epipe` for a broken pipe.
+`Message` is the human readable string for   the  error code returned by
+the OS or  the  same  as  `Code`  if   the  OS  does  not  provide  this
+functionality. Note that `Code` is derived from   a static set of macros
+that may or may not be defines for the   target OS. If the macro name is
+not known, `Code` is =|ERROR_nnn|=, where _nnn_ is an integer.
+
+    error(socket_error(Code, Message), _)
+
+Note that on Windows `Code` is a ``wsa*``   code  which makes it hard to
+write portable code that handles specific   socket errors. Even on POSIX
+systems the exact set of errors  produced   by  the network stack is not
+defined.
+
+## Socket addresses (families)		{#socket-domains}
+
+The library supports both IP4 and IP6 addresses. On Unix systems it also
+supports _Unix domain sockets_ (``AF_UNIX``).  The   address  of  a Unix
+domain sockets is a file name.  Unix   domain  sockets are created using
+socket_create/2 or unix_domain_socket/1.
+
+IP4 or IP6 sockets can be created using socket_create/2 or tcp_connect/3
+with the `inet` (default, IP3) or  `inet6`   domain  option. Some of the
+predicates produce or consume IP addresses as  a Prolog term. The format
+of this term is one of:
+
+  - ip(A,B,C,D)
+    Represents an IP4 address.  Each field is an integer in the range
+    0..255 (8 bit).
+  - ip(A,B,C,D,E,F,G,H)
+    Represents an IP6 address.  Each field is an integer in the range
+    0..65535 (16 bit).
+
+The  predicate  ip_name/2  translates  between   the  canonical  textual
+representation and the above defined address terms.
+
+## Socket predicate reference           {#socket-predicates}
+*/
+
+:- multifile
+    tcp_connect_hook/3,             % +Socket, +Addr, -In, -Out
+    tcp_connect_hook/4,             % +Socket, +Addr, -Stream
+    proxy_for_url/3,                % +URL, +Host, -ProxyList
+    try_proxy/4.                    % +Proxy, +Addr, -Socket, -Stream
+
+:- predicate_options(tcp_connect/3, 3,
+                     [ bypass_proxy(boolean),
+                       nodelay(boolean),
+                       domain(oneof([inet,inet6]))
+                     ]).
+
+:- use_foreign_library(foreign(socket)).
+:- public tcp_debug/1.                  % set debugging.
+
+:- if(current_predicate(unix_domain_socket/1)).
+:- export(unix_domain_socket/1).  % -Socket
+:- endif.
+
+%!  socket_create(-SocketId, +Options) is det.
+%
+%   Create a socket according to Options.   Supported Options are:
+%
+%     - domain(+Domain)
+%       One of `inet` (default), `inet6`, `unix` or `local` (same
+%       as `unix`)
+%     - type(+Type)
+%       One of `stream` (default) to create a TCP connection or
+%       `dgram` to create a UDP socket.
+%
+%   This   predicate    subsumes   tcp_socket/1,    udp_socket/1   and
+%   unix_domain_socket/1.
+
+%!  tcp_socket(-SocketId) is det.
+%
+%   Equivalent   to   socket_create(SocketId,    [])   or,   explicit,
+%   socket_create(SocketId, [domain(inet), type(stream)]).
+
+%!  unix_domain_socket(-SocketId) is det.
+%
+%   Equivalent   to    socket_create(SocketId,   [domain(unix)])   or,
+%   explicit, socket_create(SocketId, [domain(unix), type(stream)])
+%
+%   Unix  domain   socket  affect  tcp_connect/2  (for   clients)  and
+%   tcp_bind/2 and tcp_accept/3 (for servers).  The address is an atom
+%   or string  that is  handled as  a file name.  On most  systems the
+%   length of this  file name is limited to 128  bytes (including null
+%   terminator), but  according to the Linux  documentation (unix(7)),
+%   portable applications must  keep the address below  92 bytes. Note
+%   that  these lengths  are  in bytes.  Non-ascii  characters may  be
+%   represented as multiple  bytes. If the length limit  is exceeded a
+%   representation_error(af_unix_name) exception is raised.
+
+%!  tcp_close_socket(+SocketId) is det.
+%
+%   Closes the indicated socket, making  SocketId invalid. Normally,
+%   sockets are closed by closing both   stream  handles returned by
+%   open_socket/3. There are two cases   where tcp_close_socket/1 is
+%   used because there are no stream-handles:
+%
+%     - If, after tcp_accept/3, the server uses fork/1 to handle the
+%       client in a sub-process. In this case the accepted socket is
+%       not longer needed from the main server and must be discarded
+%       using tcp_close_socket/1.
+%     - If, after discovering the connecting client with
+%       tcp_accept/3, the server does not want to accept the
+%       connection, it should discard the accepted socket
+%       immediately using tcp_close_socket/1.
+
+%!  tcp_open_socket(+SocketId, -StreamPair) is det.
+%
+%   Create streams to communicate to  SocketId.   If  SocketId  is a
+%   master socket (see tcp_bind/2), StreamPair   should  be used for
+%   tcp_accept/3. If SocketId is a  connected (see tcp_connect/2) or
+%   accepted socket (see tcp_accept/3), StreamPair   is unified to a
+%   stream pair (see stream_pair/3) that can be used for reading and
+%   writing. The stream or pair must   be closed with close/1, which
+%   also closes SocketId.
+
+tcp_open_socket(Socket, Stream) :-
+    tcp_open_socket(Socket, In, Out),
+    (   var(Out)
+    ->  Stream = In
+    ;   stream_pair(Stream, In, Out)
+    ).
+
+%!  tcp_open_socket(+SocketId, -InStream, -OutStream) is det.
+%
+%   Similar to tcp_open_socket/2, but creates   two separate sockets
+%   where tcp_open_socket/2 would have created a stream pair.
+%
+%   @deprecated New code should use tcp_open_socket/2 because
+%   closing a stream pair is much easier to perform safely.
+
+%!  tcp_bind(SocketId, ?Address) is det.
+%
+%   Bind  the  socket  to  Address  on  the  current  machine.  This
+%   operation, together with tcp_listen/2 and tcp_accept/3 implement
+%   the _server-side_ of the socket interface.  Address is either an
+%   plain `Port` or a term HostPort. The first form binds the socket
+%   to the given port on all interfaces, while the second only binds
+%   to the matching interface. A typical   example is below, causing
+%   the socket to listen only on port   8080  on the local machine's
+%   network.
+%
+%     ==
+%       tcp_bind(Socket, localhost:8080)
+%     ==
+%
+%   If `Port` is unbound, the system   picks  an arbitrary free port
+%   and unifies `Port` with the  selected   port  number.  `Port` is
+%   either an integer or the name of  a registered service. See also
+%   tcp_connect/4.
+
+%!  tcp_listen(+SocketId, +BackLog) is det.
+%
+%   Tells, after tcp_bind/2,  the  socket   to  listen  for incoming
+%   requests for connections. Backlog  indicates   how  many pending
+%   connection requests are allowed. Pending   requests are requests
+%   that  are  not  yet  acknowledged  using  tcp_accept/3.  If  the
+%   indicated number is exceeded,  the   requesting  client  will be
+%   signalled  that  the  service  is  currently  not  available.  A
+%   commonly used default value for Backlog is 5.
+
+%!  tcp_accept(+Socket, -Slave, -Peer) is det.
+%
+%   This predicate waits on a server socket  for a connection request by
+%   a client. On success, it creates  a   new  socket for the client and
+%   binds the identifier to Slave. Peer is   bound  to the IP-address of
+%   the client or the atom `af_unix` if Socket is an AF_UNIX socket (see
+%   unix_domain_socket/1).
+
+%!  tcp_connect(+SocketId, +Address) is det.
+%
+%   Connect SocketId. After successful completion, tcp_open_socket/3
+%   can be used to create  I/O-Streams   to  the remote socket. This
+%   predicate is part of the low level client API. A connection to a
+%   particular host and port is realised using these steps:
+%
+%     ==
+%         tcp_socket(Socket),
+%         tcp_connect(Socket, Host:Port),
+%         tcp_open_socket(Socket, StreamPair)
+%     ==
+%
+%   Typical client applications should use  the high level interface
+%   provided by tcp_connect/3 which  avoids   resource  leaking if a
+%   step in the process fails, and can  be hooked to support proxies.
+%   For example:
+%
+%     ==
+%         setup_call_cleanup(
+%             tcp_connect(Host:Port, StreamPair, []),
+%             talk(StreamPair),
+%             close(StreamPair))
+%     ==
+%
+%   If SocketId is an AF_UNIX socket (see unix_domain_socket/1), Address
+%   is an atom or string denoting a file name.
+
+tcp_connect(Socket, Host0:Port) =>
+    (   rewrite_host(Host0, Host, Socket)
+    ->  true
+    ;   Host = Host0
+    ),
+    tcp_connect_(Socket, Host:Port).
+tcp_connect(Socket, Address) =>
+    tcp_connect_(Socket, Address).
+
+%!  rewrite_host(+HostIn, -HostOut, +Socket) is nondet.
+%
+%   Allow rewriting the host for tcp_connect/2   and therefore all other
+%   predicates to connect a socket.
+%
+%   This hook is currently defined  in   Windows  to  map `localhost` to
+%   ip(127,0,0,1) as resolving `localhost`  on   Windows  is  often very
+%   slow. Note that we do not want to do that in general as a system may
+%   prefer to map `localhost` to `::1`, i.e., the IPv6 loopback address.
+
+:- if(current_prolog_flag(windows, true)).
+rewrite_host(localhost, ip(127,0,0,1), _).
+:- endif.
+
+
+                 /*******************************
+                 *      HOOKABLE CONNECT        *
+                 *******************************/
+
+%!  tcp_connect(+Socket, +Address, -Read, -Write) is det.
+%
+%   Connect a (client) socket to Address and return a bi-directional
+%   connection through the  stream-handles  Read   and  Write.  This
+%   predicate may be hooked   by  defining socket:tcp_connect_hook/4
+%   with the same signature. Hooking can be  used to deal with proxy
+%   connections. E.g.,
+%
+%       ==
+%       :- multifile socket:tcp_connect_hook/4.
+%
+%       socket:tcp_connect_hook(Socket, Address, Read, Write) :-
+%           proxy(ProxyAdress),
+%           tcp_connect(Socket, ProxyAdress),
+%           tcp_open_socket(Socket, Read, Write),
+%           proxy_connect(Address, Read, Write).
+%       ==
+%
+%   @deprecated New code should use tcp_connect/3 called as
+%   tcp_connect(+Address, -StreamPair, +Options).
+
+tcp_connect(Socket, Address, Read, Write) :-
+    tcp_connect_hook(Socket, Address, Read, Write),
+    !.
+tcp_connect(Socket, Address, Read, Write) :-
+    tcp_connect(Socket, Address),
+    tcp_open_socket(Socket, Read, Write).
+
+
+
+%!  tcp_connect(+Address, -StreamPair, +Options) is det.
+%!  tcp_connect(+Socket, +Address, -StreamPair) is det.
+%
+%   Establish a TCP communication as a  client.   The  +,-,+ mode is the
+%   preferred way for a client to establish a connection. This predicate
+%   can be hooked to support network proxies.   To use a proxy, the hook
+%   proxy_for_url/3 must be defined. Permitted options are:
+%
+%      * bypass_proxy(+Boolean)
+%        Defaults to =false=. If =true=, do not attempt to use any
+%        proxies to obtain the connection
+%
+%      * nodelay(+Boolean)
+%        Defaults to =false=. If =true=, set nodelay on the
+%        resulting socket using tcp_setopt(Socket, nodelay)
+%
+%      * domain(+Domain)
+%        One of `inet' or `inet6`.  When omitted we use host_address/2
+%        with type(stream) and try the returned addresses in order.
+%
+%   The +,+,- mode is  deprecated  and   does  not  support  proxies. It
+%   behaves  like  tcp_connect/4,  but  creates    a  stream  pair  (see
+%   stream_pair/3).
+%
+%   @arg Address is either a Host:Port  term   or  a  file name (atom or
+%   string). The latter connects  to  an   AF_UNIX  socket  and requires
+%   unix_domain_socket/1.
+%
+%   @error proxy_error(tried(ResultList)) is raised by   mode (+,-,+) if
+%   proxies are defines by proxy_for_url/3 but no proxy can establsh the
+%   connection. `ResultList` contains one or  more   terms  of  the form
+%   false(Proxy)  for  a  hook  that    simply  failed  or  error(Proxy,
+%   ErrorTerm) for a hook that raised an exception.
+%
+%   @see library(http/http_proxy) defines a hook  that allows to connect
+%   through HTTP proxies that support the =CONNECT= method.
+
+% Main mode: +,-,+
+tcp_connect(Address, StreamPair, Options) :-
+    var(StreamPair),
+    !,
+    (   memberchk(bypass_proxy(true), Options)
+    ->  tcp_connect_direct(Address, Socket, StreamPair, Options)
+    ;   findall(Result,
+                try_a_proxy(Address, Result),
+                ResultList),
+        last(ResultList, Status)
+    ->  (   Status = true(_Proxy, Socket, StreamPair)
+        ->  true
+        ;   throw(error(proxy_error(tried(ResultList)), _))
+        )
+    ;   tcp_connect_direct(Address, Socket, StreamPair, Options)
+    ),
+    (   memberchk(nodelay(true), Options)
+    ->  tcp_setopt(Socket, nodelay)
+    ;   true
+    ).
+% backward compatibility mode +,+,-
+tcp_connect(Socket, Address, StreamPair) :-
+    tcp_connect_hook(Socket, Address, StreamPair0),
+    !,
+    StreamPair = StreamPair0.
+tcp_connect(Socket, Address, StreamPair) :-
+    connect_stream_pair(Socket, Address, StreamPair).
+
+:- public tcp_connect_direct/3.   % used by HTTP proxy code.
+tcp_connect_direct(Address, Socket, StreamPair) :-
+    tcp_connect_direct(Address, Socket, StreamPair, []).
+
+%!  tcp_connect_direct(+Address, +Socket, -StreamPair, +Options) is det.
+%
+%   Make a direct connection to a TCP address, i.e., do not take proxy
+%   rules into  account.  If  no explicit  domain (`inet`,  `inet6` is
+%   given,  perform  a  getaddrinfo()  call  to  obtain  the  relevant
+%   addresses.
+
+tcp_connect_direct(Host0:Port, Socket, StreamPair, Options) :-
+    must_be(ground, Host0),
+    \+ option(domain(_), Options),
+    !,
+    (   rewrite_host(Host0, Host, Socket)
+    ->  true
+    ;   Host = Host0
+    ),
+    State = error(_),
+    (   (   is_ip(Host, Domain)
+        ->  IP = Host
+        ;   host_address(Host, Address, [type(stream)]),
+            Domain = Address.domain,
+            IP = Address.address
+        ),
+	socket_create(Socket, [domain(Domain)]),
+	E = error(_,_),
+	catch(connect_or_discard_socket(Socket, IP:Port, StreamPair),
+	      E, store_error_and_fail(State, E)),
+	debug(socket, '~p: connected to ~p', [Host, IP])
+    ->  true
+    ;   arg(1, State, Error),
+	assertion(nonvar(Error)),
+	throw(Error)
+    ).
+tcp_connect_direct(Address, Socket, StreamPair, Options) :-
+    make_socket(Address, Socket, Options),
+    connect_or_discard_socket(Socket, Address, StreamPair).
+
+is_ip(ip(_,_,_,_), inet).
+is_ip(ip(_,_,_,_, _,_,_,_), inet6).
+
+connect_or_discard_socket(Socket, Address, StreamPair) :-
+    setup_call_catcher_cleanup(
+	true,
+	connect_stream_pair(Socket, Address, StreamPair),
+	Catcher, cleanup(Catcher, Socket)).
+
+cleanup(exit, _) :- !.
+cleanup(_, Socket) :-
+    tcp_close_socket(Socket).
+
+connect_stream_pair(Socket, Address, StreamPair) :-
+    tcp_connect(Socket, Address, Read, Write),
+    stream_pair(StreamPair, Read, Write).
+
+store_error_and_fail(State, E) :-
+    arg(1, State, E0),
+    var(E0),
+    nb_setarg(1, State, E),
+    fail.
+
+:- if(current_predicate(unix_domain_socket/1)).
+make_socket(Address, Socket, _Options) :-
+    (   atom(Address)
+    ;   string(Address)
+    ),
+    !,
+    unix_domain_socket(Socket).
+:- endif.
+make_socket(_Address, Socket, Options) :-
+    option(domain(Domain), Options, inet),
+    socket_create(Socket, [domain(Domain)]).
+
+
+%!  tcp_select(+ListOfStreams, -ReadyList, +TimeOut)
+%
+%   Same as the built-in wait_for_input/3. Used  to allow for interrupts
+%   and timeouts on Windows. A redesign  of the Windows socket interface
+%   makes  it  impossible  to  do  better  than  Windows  select()  call
+%   underlying wait_for_input/3. As input multiplexing typically happens
+%   in a background thread anyway we  accept   the  loss of timeouts and
+%   interrupts.
+%
+%   @deprecated Use wait_for_input/3
+
+tcp_select(ListOfStreams, ReadyList, TimeOut) :-
+    wait_for_input(ListOfStreams, ReadyList, TimeOut).
+
+
+                 /*******************************
+                 *        PROXY SUPPORT         *
+                 *******************************/
+
+try_a_proxy(Address, Result) :-
+    format(atom(URL), 'socket://~w', [Address]),
+    (   Address = Host:_
+    ->  true
+    ;   Host = Address
+    ),
+    proxy_for_url(URL, Host, Proxy),
+    debug(socket(proxy), 'Socket connecting via ~w~n', [Proxy]),
+    (   catch(try_proxy(Proxy, Address, Socket, Stream), E, true)
+    ->  (   var(E)
+        ->  !, Result = true(Proxy, Socket, Stream)
+        ;   Result = error(Proxy, E)
+        )
+    ;   Result = false(Proxy)
+    ),
+    debug(socket(proxy), 'Socket: ~w: ~p', [Proxy, Result]).
+
+%!  try_proxy(+Proxy, +TargetAddress, -Socket, -StreamPair) is semidet.
+%
+%   Attempt  a  socket-level  connection  via  the  given  proxy  to
+%   TargetAddress. The Proxy argument must match the output argument
+%   of proxy_for_url/3. The predicate tcp_connect/3 (and http_open/3
+%   from the library(http/http_open)) collect the  results of failed
+%   proxies and raise an exception no  proxy is capable of realizing
+%   the connection.
+%
+%   The default implementation  recognises  the   values  for  Proxy
+%   described    below.    The      library(http/http_proxy)    adds
+%   proxy(Host,Port)  which  allows  for  HTTP   proxies  using  the
+%   =CONNECT= method.
+%
+%     - direct
+%     Do not use any proxy
+%     - socks(Host, Port)
+%     Use a SOCKS5 proxy
+
+:- multifile
+    try_proxy/4.
+
+try_proxy(direct, Address, Socket, StreamPair) :-
+    !,
+    tcp_connect_direct(Address, Socket, StreamPair).
+try_proxy(socks(Host, Port), Address, Socket, StreamPair) :-
+    !,
+    tcp_connect_direct(Host:Port, Socket, StreamPair),
+    catch(negotiate_socks_connection(Address, StreamPair),
+          Error,
+          ( close(StreamPair, [force(true)]),
+            throw(Error)
+          )).
+
+%!  proxy_for_url(+URL, +Hostname, -Proxy) is nondet.
+%
+%   This hook can be implemented  to  return   a  proxy  to try when
+%   connecting to URL. Returned proxies are   tried  in the order in
+%   which they are  returned  by   the  multifile  hook try_proxy/4.
+%   Pre-defined proxy methods are:
+%
+%      * direct
+%        connect directly to the resource
+%      * proxy(Host, Port)
+%        Connect to the resource using an HTTP proxy. If the
+%        resource is not an HTTP URL, then try to connect using the
+%        CONNECT verb, otherwise, use the GET verb.
+%      * socks(Host, Port)
+%        Connect to the resource via a SOCKS5 proxy
+%
+%   These correspond to the proxy  methods   defined  by  PAC [Proxy
+%   auto-config](http://en.wikipedia.org/wiki/Proxy_auto-config).
+%   Additional methods can  be  returned   if  suitable  clauses for
+%   http:http_connection_over_proxy/6 or try_proxy/4 are defined.
+
+:- multifile
+    proxy_for_url/3.
+
+%!  udp_socket(-SocketId) is det.
+%
+%   Equivalent to socket_create(SocketId, [type(dgram)]) or, explicit,
+%   socket_create(SocketId, [domain(inet), type(dgram)]).
+
+%!  udp_receive(+Socket, -Data, -From, +Options) is det.
+%
+%   Wait for and  return the next datagram. The Data  is returned as a
+%   Prolog term  depending on Options.  From  is a term of  the format
+%   Ip:Port indicating the sender of the message. Here, `Ip` is either
+%   an  ip4  or  ip6  structure.   Socket  can  be  waited  for  using
+%   wait_for_input/3. Defined Options:
+%
+%     - as(+Type)
+%     Defines the type for Data.  Possible values are `atom`, `codes`,
+%     `string` (default) or `term` (parse as Prolog term).
+%     - encoding(+Encoding)
+%     Specify the encoding used to interpret the message. It is one of
+%     `octet`. `iso_latin_1`, `text` or `utf8`.
+%     - max_message_size(+Size)
+%     Specify  the  maximum  number  of  bytes  to  read  from  a  UDP
+%     datagram. Size must be within the range 0-65535. If unspecified,
+%     a maximum of 4096 bytes will be read.
+%
+%   For example:
+%
+%   ```
+%   receive(Port) :-
+%       udp_socket(Socket),
+%       tcp_bind(Socket, Port),
+%       repeat,
+%           udp_receive(Socket, Data, From, [as(atom)]),
+%           format('Got ~q from ~q~n', [Data, From]),
+%           fail.
+%   ```
+
+
+%!  udp_send(+Socket, +Data, +To, +Options) is det.
+%
+%   Send a UDP message. Data is  a string, atom or code-list providing
+%   the data.  To is an  address of the  form Host:Port where  Host is
+%   either the hostname or an IP address. Defined Options are:
+%
+%     - encoding(+Encoding)
+%       Specifies   the  encoding   to   use  for   the  string.   See
+%       udp_receive/4 for details
+%     - as(+Type)
+%       This uses the  same values for Type as the  as(Type) option of
+%       udp_receive/4. The are interpreted differently though. No Type
+%       corresponds   to  CVT_ALL   of  PL_get_chars().    Using  atom
+%       corresponds to CVT_ATOM  and any of string or  codes is mapped
+%       to  CVT_STRING|CVT_LIST,  allowing  for  a  SWI-Prolog  string
+%       object,  list  of  character  codes  or  list  of  characters.
+%       Finally, `term` maps to CVT_WRITE_CANONICAL. This implies that
+%       arbitrary Prolog terms  can be sent reliably  using the option
+%       list `[as(term),encoding(utf8)])`, using  the same option list
+%       for udp_receive/4.
+%
+%   For example
+%
+%   ```
+%   send(Host, Port, Message) :-
+%       udp_socket(S),
+%       udp_send(S, Message, Host:Port, []),
+%       tcp_close_socket(S).
+%   ```
+%
+%   A  broadcast is  achieved by  using tcp_setopt(Socket,  broadcast)
+%   prior  to  sending  the  datagram  and  using  the  local  network
+%   broadcast address as a ip/4 term.
+
+
+                 /*******************************
+                 *            OPTIONS           *
+                 *******************************/
+
+%!  tcp_setopt(+SocketId, +Option) is det.
+%
+%   Set options on the socket.  Defined options are:
+%
+%     - reuseaddr
+%     Allow servers to reuse a port without the system being
+%     completely sure the port is no longer in use.
+%
+%     - bindtodevice(+Device)
+%     Bind the socket to Device (an atom). For example, the code
+%     below binds the socket to the _loopback_ device that is
+%     typically used to realise the _localhost_. See the manual
+%     pages for setsockopt() and the socket interface (e.g.,
+%     socket(7) on Linux) for details.
+%
+%       ==
+%       tcp_socket(Socket),
+%       tcp_setopt(Socket, bindtodevice(lo))
+%       ==
+%
+%     - nodelay
+%     - nodelay(true)
+%     If =true=, disable the Nagle optimization on this socket,
+%     which is enabled by default on almost all modern TCP/IP
+%     stacks. The Nagle optimization joins small packages, which is
+%     generally desirable, but sometimes not. Please note that the
+%     underlying TCP_NODELAY setting to setsockopt() is not
+%     available on all platforms and systems may require additional
+%     privileges to change this option. If the option is not
+%     supported, tcp_setopt/2 raises a domain_error exception. See
+%     [Wikipedia](http://en.wikipedia.org/wiki/Nagle's_algorithm)
+%     for details.
+%
+%     - broadcast
+%     UDP sockets only: broadcast the package to all addresses
+%     matching the address. The address is normally the address of
+%     the local subnet (i.e. 192.168.1.255).  See udp_send/4.
+%
+%     - ip_add_membership(+MultiCastGroup)
+%     - ip_add_membership(+MultiCastGroup, +LocalInterface)
+%     - ip_add_membership(+MultiCastGroup, +LocalInterface, +InterfaceIndex)
+%     - ip_drop_membership(+MultiCastGroup)
+%     - ip_drop_membership(+MultiCastGroup, +LocalInterface)
+%     - ip_drop_membership(+MultiCastGroup, +LocalInterface, +InterfaceIndex)
+%     Join/leave a multicast group.  Calls setsockopt() with the
+%     corresponding arguments.
+%
+%     - dispatch(+Boolean)
+%     In GUI environments (using XPCE or the Windows =swipl-win.exe=
+%     executable) this flags defines whether or not any events are
+%     dispatched on behalf of the user interface. Default is
+%     =true=. Only very specific situations require setting
+%     this to =false=.
+%
+%     - sndbuf(+Integer)
+%     Sets the send buffer size to Integer (bytes). On Windows this defaults
+%     (now) to 64kb. Higher latency links may benefit from increasing this
+%     further since the maximum theoretical throughput on a link is given by
+%     buffer-size / latency.
+%     See https://support.microsoft.com/en-gb/help/823764/slow-performance-occurs-when-you-copy-data-to-a-tcp-server-by-using-a
+%     for Microsoft's discussion
+
+%!  tcp_fcntl(+Stream, +Action, ?Argument) is det.
+%
+%   Interface to the fcntl() call. Currently   only suitable to deal
+%   switch stream to non-blocking mode using:
+%
+%     ==
+%       tcp_fcntl(Stream, setfl, nonblock),
+%     ==
+%
+%   An attempt to read from a non-blocking  stream while there is no
+%   data available returns -1  (or   =end_of_file=  for read/1), but
+%   at_end_of_stream/1    fails.    On      actual     end-of-input,
+%   at_end_of_stream/1 succeeds.
+
+tcp_fcntl(Socket, setfl, nonblock) :-
+    !,
+    tcp_setopt(Socket, nonblock).
+
+%!  tcp_getopt(+Socket, ?Option) is semidet.
+%
+%   Get  information  about  Socket.  Defined    properties  are  below.
+%   Requesting an unknown option results in a `domain_error` exception.
+%
+%     - file_no(-File)
+%     Get the OS file handle as an integer.  This may be used for
+%     debugging and integration.
+
+%!  host_address(+HostName, -Address, +Options) is nondet.
+%!  host_address(-HostName, +Address, +Options) is det.
+%
+%   Translate  between a  machines  host-name  and it's  (IP-)address.
+%   Supported options:
+%
+%     - domain(+Domain)
+%       One of `inet` or `inet6` to limit the results to the given
+%       family.
+%     - type(+Type)
+%       One of `stream` or `dgram`.
+%     - canonname(+Boolean)
+%       If `true` (default `false`), return the canonical host name
+%       in the frist answer
+%
+%   In mode (+,-,+) Address is unified to a dict with the following keys:
+%
+%     - address
+%       A Prolog terms describing the ip address.
+%     - domain
+%       One of `inet` or `inet6`.  The underlying getaddrinfo() calls
+%       this `family`.  We use `domain` for consistency with
+%       socket_create/2.
+%     - type
+%       Currently one of `stream` or `dgram`.
+%     - host
+%       Available if canonname(true) is specified on the first
+%       returned address.  Holds the official canonical host name.
+
+host_address(HostName, Address, Options), ground(HostName) =>
+    '$host_address'(HostName, Addresses, Options),
+    member(Address, Addresses).
+host_address(HostName, Address, Options), is_dict(Address) =>
+    '$host_address'(HostName, Address.address, Options).
+host_address(HostName, Address, Options), ground(Address) =>
+    '$host_address'(HostName, Address, Options).
+
+%!  tcp_host_to_address(?HostName, ?Address) is det.
+%
+%   Translate between a machines  host-name   and  it's (IP-)address. If
+%   HostName is an atom, it  is   resolved  using  getaddrinfo() and the
+%   IP-number  is  unified  to  Address  using  a  term  of  the  format
+%   ip(Byte1,Byte2,Byte3,Byte4). Otherwise, if Address is   bound  to an
+%   ip(Byte1,Byte2,Byte3,Byte4) term, it is  resolved by gethostbyaddr()
+%   and the canonical hostname is unified with HostName.
+%
+%   @deprecated New code should  use   host_address/3.  This  version is
+%   bootstrapped from host_address/3 and only searches for IP4 addresses
+%   that support TCP connections.
+
+tcp_host_to_address(Host, Address), ground(Address) =>
+    host_address(Host, Address, []).
+tcp_host_to_address(Host, Address), ground(Host) =>
+    host_address(Host, [Dict|_], [domain(inet), type(stream)]),
+    Address = Dict.address.
+
+
+%!  gethostname(-Hostname) is det.
+%
+%   Return the canonical fully qualified name  of this host. This is
+%   achieved by calling gethostname() and  return the canonical name
+%   returned by getaddrinfo().
+
+
+%!  ip_name(?IP, ?Name) is det.
+%
+%   Translate between the textual representation  of an IP address and
+%   the  Prolog data  structure.  Prolog  represents ip4  addresses as
+%   ip(A,B,C,D) and ip6 addresses as ip(A,B,C,D,E,F,H).  For example:
+%
+%       ?- ip_name(ip(1,2,3,4), Name)
+%       Name = '1.2.3.4'.
+%       ?- ip_name(IP, '::').
+%       IP = ip(0,0,0,0,0,0,0,0).
+%       ?- ip_name(IP, '1:2::3').
+%       IP = ip(1,2,0,0,0,0,0,3).
+
+ip_name(Ip, Atom), ground(Atom) =>
+    name_to_ip(Atom, Ip).
+ip_name(Ip, Atom), ground(Ip) =>
+    ip_to_name(Ip, Atom).
+ip_name(Ip, _) =>
+    instantiation_error(Ip).
+
+name_to_ip(Atom, Ip4) :-
+    split_string(Atom, '.', '', Parts),
+    length(Parts, 4),
+    maplist(string_byte, Parts, Bytes),
+    !,
+    Ip4 =.. [ip|Bytes].
+name_to_ip(Atom, Ip6) :-
+    split_string(Atom, ':', '', Parts0),
+    clean_ends(Parts0, Parts1),
+    length(Parts1, Len),
+    (   Len < 8
+    ->  append(Pre, [""|Post], Parts1),
+	Zeros is 8-(Len-1),
+	length(ZList, Zeros),
+	maplist(=("0"), ZList),
+	append([Pre, ZList, Post], Parts)
+    ;   Len == 8
+    ->  Parts = Parts1
+    ),
+    !,
+    maplist(string_short, Parts, Shorts),
+    Ip6 =.. [ip|Shorts].
+name_to_ip(Atom, _) :-
+    syntax_error(ip_address(Atom)).
+
+clean_ends([""|T0], T) :-
+    !,
+    (   append(T1, [""], T0)
+    ->  T = T1
+    ;   T = T0
+    ).
+clean_ends(T0, T) :-
+    append(T1, [""], T0),
+    !,
+    T = T1.
+clean_ends(T, T).
+
+string_byte(String, Byte) :-
+    number_string(Byte, String),
+    must_be(between(0, 255), Byte).
+
+string_short(String, Short) :-
+    string_concat('0x', String, String1),
+    number_string(Short, String1),
+    must_be(between(0, 65535), Short).
+
+ip_to_name(ip(A,B,C,D), Atom) :-
+    !,
+    atomic_list_concat([A,B,C,D], '.', Atom).
+ip_to_name(IP, Atom) :-
+    compound(IP),
+    compound_name_arity(IP, ip, 8),
+    !,
+    IP =.. [ip|Parts],
+    (   zero_seq(Parts, Pre, Post, Len),
+        Len > 1,
+        \+ ( zero_seq(Post, _, _, Len2),
+	     Len2 > Len
+	   )
+    ->  append([Pre, [''], Post], Parts1),
+	(   Pre == []
+	->  Parts2 = [''|Parts1]
+	;   Parts2 = Parts1
+	),
+	(   Post == []
+	->  append(Parts2, [''], Parts3)
+	;   Parts3 = Parts2
+	)
+    ;   Parts3 = Parts
+    ),
+    maplist(to_hex, Parts3, Parts4),
+    atomic_list_concat(Parts4, ':', Atom).
+ip_to_name(IP, _) :-
+    domain_error(ip_address, IP).
+
+zero_seq(List, Pre, Post, Count) :-
+    append(Pre, [0|Post0], List),
+    leading_zeros(Post0, Post, 1, Count).
+
+leading_zeros([0|T0], T, C0, C) =>
+    C1 is C0+1,
+    leading_zeros(T0, T, C1, C).
+leading_zeros(L0, L, C0, C) =>
+    L = L0,
+    C = C0.
+
+to_hex('', '') :-
+    !.
+to_hex(Num, Hex) :-
+    format(string(Hex), '~16r', [Num]).
+
+
+
+                 /*******************************
+                 *            SOCKS             *
+                 *******************************/
+
+%!  negotiate_socks_connection(+DesiredEndpoint, +StreamPair) is det.
+%
+%   Negotiate  a  connection  to  DesiredEndpoint  over  StreamPair.
+%   DesiredEndpoint should be in the form of either:
+%
+%      * hostname : port
+%      * ip(A,B,C,D) : port
+%
+%   @error socks_error(Details) if the SOCKS negotiation failed.
+
+negotiate_socks_connection(Host:Port, StreamPair):-
+    format(StreamPair, '~s', [[0x5,    % Version 5
+                               0x1,    % 1 auth method supported
+                               0x0]]), % which is 'no auth'
+    flush_output(StreamPair),
+    get_byte(StreamPair, ServerVersion),
+    get_byte(StreamPair, AuthenticationMethod),
+    (   ServerVersion =\= 0x05
+    ->  throw(error(socks_error(invalid_version(5, ServerVersion)), _))
+    ;   AuthenticationMethod =:= 0xff
+    ->  throw(error(socks_error(invalid_authentication_method(
+                                    0xff,
+                                    AuthenticationMethod)), _))
+    ;   true
+    ),
+    (   Host = ip(A,B,C,D)
+    ->  AddressType = 0x1,                  % IPv4 Address
+        format(atom(Address), '~s', [[A, B, C, D]])
+    ;   AddressType = 0x3,                  % Domain
+        atom_length(Host, Length),
+        format(atom(Address), '~s~w', [[Length], Host])
+    ),
+    P1 is Port /\ 0xff,
+    P2 is Port >> 8,
+    format(StreamPair, '~s~w~s', [[0x5,   % Version 5
+                                   0x1,   % Please establish a connection
+                                   0x0,   % reserved
+                                   AddressType],
+                                  Address,
+                                  [P2, P1]]),
+    flush_output(StreamPair),
+    get_byte(StreamPair, _EchoedServerVersion),
+    get_byte(StreamPair, Status),
+    (   Status =:= 0                        % Established!
+    ->  get_byte(StreamPair, _Reserved),
+        get_byte(StreamPair, EchoedAddressType),
+        (   EchoedAddressType =:= 0x1
+        ->  get_byte(StreamPair, _),        % read IP4
+            get_byte(StreamPair, _),
+            get_byte(StreamPair, _),
+            get_byte(StreamPair, _)
+        ;   get_byte(StreamPair, Length),   % read host name
+            forall(between(1, Length, _),
+                   get_byte(StreamPair, _))
+        ),
+        get_byte(StreamPair, _),            % read port
+        get_byte(StreamPair, _)
+    ;   throw(error(socks_error(negotiation_rejected(Status)), _))
+    ).
+
+
+                 /*******************************
+                 *             MESSAGES         *
+                 *******************************/
+
+/* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+The C-layer generates exceptions of the  following format, where Message
+is extracted from the operating system.
+
+        error(socket_error(Code, Message), _)
+- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
+
+:- multifile
+    prolog:error_message//1.
+
+prolog:error_message(socket_error(_Code, Message)) -->
+    [ 'Socket error: ~w'-[Message] ].
+prolog:error_message(socks_error(Error)) -->
+    socks_error(Error).
+prolog:error_message(proxy_error(tried(Tried))) -->
+    [ 'Failed to connect using a proxy.  Tried:'-[], nl],
+    proxy_tried(Tried).
+
+socks_error(invalid_version(Supported, Got)) -->
+    [ 'SOCKS: unsupported version: ~p (supported: ~p)'-
+      [ Got, Supported ] ].
+socks_error(invalid_authentication_method(Supported, Got)) -->
+    [ 'SOCKS: unsupported authentication method: ~p (supported: ~p)'-
+      [ Got, Supported ] ].
+socks_error(negotiation_rejected(Status)) -->
+    [ 'SOCKS: connection failed: ~p'-[Status] ].
+
+proxy_tried([]) --> [].
+proxy_tried([H|T]) -->
+    proxy_tried(H),
+    proxy_tried(T).
+proxy_tried(error(Proxy, Error)) -->
+    [ '~w: '-[Proxy] ],
+    '$messages':translate_message(Error).
+proxy_tried(false(Proxy)) -->
+    [ '~w: failed with unspecified error'-[Proxy] ].