How to use iproto.advertise.client (how to connect to an instance)

Related dev. issue(s): N/A

Product: Tarantool
Since: 3.0.0
Audience/target: application and external components developers
Root document: https://www.tarantool.io/en/doc/latest/reference/configuration/configuration_reference/#configuration-reference-iproto-advertise-client
SME: @ Totktonada

Details

There is the iproto.advertise.client option, which holds an URI for external clients, which tells them how to connect to the given tarantool instance (config schema, brief description, website documentation).

However, there is no formal agreement how an external client should connect to tarantool. Some clients may use only iproto.advertise.client, some may fallback to iproto.listen. Some may fallback only if iproto.advertise.client is not set, but some may fallback if it is set, but inaccessible.

This documentation request aims to hold an agreement between a writer of server's configuration and a developer of a logic on the external client.

The agreement is the following.

1. If iproto.advertise.client is set, it is used to connect. No attempts are performed for other URIs (including iproto.listen, iproto.advertise.{peer,sharding}).

2. If (and only if) iproto.advertise.client is unset, iproto.listen URIs are tried.

   Note 1: It is unspecified, in which order the iproto.listen URIs are tried.

   Note 2: A client may filter out iproto.listen URIs without an attempt to connect if it is known that it is impossible to connect (for example, if the URI has a zero port) -- it is considered as an optimization and shouldn't affect the overall behavior.

Definition of done

• TBD
• TBD

Planning checklist

• Pick product label: server.
• Pick type label:
  • reference,
  • getting started,
  • user_guide, etc.
• Estimate complexity in storypoints in the title
• Add to Documentation board → Backlog

Start with the root configuration reference for iproto.advertise.client and the linked instance_config.lua schema and description. Document the stated connection agreement for external clients and clarify the definition of done, then verify that the reference links and wording are consistent.