#
#  resolver.txt - protocol description for communicating with resolvers
#

When the socks5pp is run with name resolution enabled with the -r option,
it starts one or more resolvers, depending on the value passed to -r.

Each of the resolvers is a child process to the socks5pp process.  The
main socks5pp process resolves DNS names to IP addresses by sending the
name to the resolver via the resolver's standard input.  The resolver
sends the IP addresses back to the parent via its standard output.

The protocol used to communicate between these processes is simple.
Each request and response is line-oriented.

The resolver sends "OK" to the parent process when it is ready to
resolve a new name.  The parent process sends a name to the resolver,
on a single line.  The resolver sends one or more response lines,
and then sends "OK" on a single line.

E.g., from the resolver's perspective:

[out] OK
[ in] www.google.com
[out] www.google.com 172.253.135.105
[out] www.google.com 172.253.135.104
[out] www.google.com 172.253.135.106
[out] www.google.com 172.253.135.99
[out] www.google.com 172.253.135.147
[out] www.google.com 172.253.135.103
[out] www.google.com 2607:f8b0:4023:1015::93
[out] www.google.com 2607:f8b0:4023:1015::6a
[out] www.google.com 2607:f8b0:4023:1015::67
[out] www.google.com 2607:f8b0:4023:1015::63
[out] OK

The [in] line is the request from the parent process, and the [out]
lines are the responses.

If the resolution fails, the resolver will send a single '0' as the
response, e.g.,

[out] OK
[ in] www.bogus-name.com
[out] www.bogus-name.com 0
[out] OK

Both IPv4 and IPv6 addresses are supported, but order is not
guaranteed.

The resolvers included in the package can be run by hand from
the command line, to allow experimenting with the resolvers,
and understanding how they work.

There are different resolvers included, which can be selected
with the -R option to socks5pp:

s5resolver - minimal C++ resolver; fast and light; uses libc
    name resolution methods, such as getaddrinfo(3)
s5host - small Python wrapper around the ISC 'host' utility,
    which must be installed to use the resolver; this is a
	heavier resolver, but offers more options
s5dnstls - uses the Python dnspython package to implement
    DNS-over-TLS queries; this is also a somewhat heavier
	resolver process, but it allows encryption of queries

# EOF: resolver.txt
