libpq host/hostaddr/conninfo inconsistencies

Hello devs,

While reviewing various patches by Tom which are focussing on libpq 
multi-host behavior,

     https://commitfest.postgresql.org/19/1749/
     https://commitfest.postgresql.org/19/1752/

it occured to me that there are a few more problems with the 
documentation, the host/hostaddr feature, and the consistency of both. 
Namely:

* According to the documentation, either "host" or "hostaddr" can be 
specified. The former for names and socket directories, the later for ip 
addresses. If both are specified, "hostaddr" supersedes "host", and it may 
be used for various authentication purposes.

However, the actual capability is slightly different: specifying an ip 
address to "host" does work, without ensuing any name or reverse name 
look-ups, even if this is undocumented.  This means that the host/hostaddr 
dichotomy is somehow moot as host can already be used for the same 
purpose.

* \conninfo does not follow the implemented logic, and, as there is no 
sanity check performed on the specification, it can display wrong 
informations, which are not going to be helpful to anyone with a problem 
to solve and trying to figure out the current state:

   sh> psql "host=/tmp hostaddr=127.0.0.1"
   psql> \conninfo
   You are connected to database "fabien" as user "fabien" via socket in "/tmp" at port "5432"
   # wrong, it is really connected to 127.0.0.1 by TCP/IP

   sh> psql "host=127.0.0.2 hostaddr=127.0.0.1"
   psql> \conninfo
   You are connected to database "fabien" as user "fabien" on host "127.0.0.2" at port "5432".
   # wrong again, it is really connected to 127.0.0.1

   sh> psql "hostaddr=127.0.0.1"
   psql> \conninfo
   You are connected to database "fabien" as user "fabien" via socket in "/var/run/postgresql" at port "5432".
   # wrong again

* Another issue with \conninfo is that if a host resolves to multiple ips, 
there is no way to know which was chosen and/or worked, although on errors 
some messages show the failing ip.

* The host/hostaddr dichotomy worsens when several targets are specified, 
because according to the documentation you should specify either names & 
dirs as host and ips as hostaddr, which leads to pretty strange spec each 
being a possible source of confusion and unhelpful messages as described 
above:

   sh> psql "host=localhost,127.0.0.2,, hostaddr=127.0.0.1,,127.0.0.3,"
   # attempt 1 is 127.0.0.1 identified as localhost
   # attempt 2 is 127.0.0.2
   # attempt 3 is 127.0.0.3 identified as the default, whatever it is
   # attempt 4 is really the default

* The documentation about host/hostaddr/port accepting lists is really 
added as an afterthought: the features are presented for one, and then the 
list is mentionned. Moreover there are quite a few repeats between the 
paragraph about defaults and so.


Given this state of affair ISTM that the situation would be clarified by:

(1) describing "host" full capability to accept names, ips and dirs.

(2) describing "hostaddr" as a look-up shortcut. Maybe the "hostaddr" 
could be renamed in passing, eg "resolve" to outline that it is just a 
lookup shortcut, and not a partial alternative to "host".

(3) checking that hostaddr non empty addresses are only accepted if the 
corresponding host is a name. The user must use the "host=ip" syntax
to connect to an ip.

(4) teaching \conninfo to show the real connection, which probably require 
extending libpq to access the underlying ip, eg PQaddr or PQhostaddr or 
whatever.

The attached patch does 1-3 (2 without renaming, though).

Thoughts?

-- 
Fabien.