api: support iproto feature discovery

Since version 2.10.0 Tarantool supports feature discovery [1]. Client
can send client protocol version and supported features and receive
server protocol version and supported features information to tune
its behavior.

After this patch, the request will be sent on `dial`, before
authentication is performed. Connector stores server info in connection
internals. User can also set option RequiredProtocolVersion and
RequiredProtocolFeatures to fast fail on connect if server does
not provide some expected feature, similar to net.box opts [2]. It is
not clear how connector should behave in case if client doesn't support
a protocol feature or protocol version, see [3]. For now we decided not
to check requirements on client side.

Feature check iterates over lists to check if feature is
enabled. It seems that iterating over a small list is way faster than
building a map, see [4]. Benchmark tests show that this check is rather
fast (0.5 ns for both client and server check on HP ProBook 440 G5) so
it is not necessary to cache it in any way.

Traces of IPROTO_FEATURE_GRACEFUL_SHUTDOWN flag and protocol version 4
could be found in Tarantool source code but they were removed in the
following commits before the release and treated like they never
existed. We also ignore them here too. See [5] for more info. In latest
master commit new feature with code 4 and protocol version 4 were
introduced [6].

1. tarantool/tarantool#6253
2. https://www.tarantool.io/en/doc/latest/reference/reference_lua/net_box/#lua-function.net_box.new
3. tarantool/tarantool#7953
4. https://stackoverflow.com/a/52710077/11646599
5. tarantool/tarantool-python#262
6. tarantool/tarantool@948e5cd

Closes #120

Author: DifferentialOrange

Diff for: CHANGELOG.md

@@ -10,6 +10,8 @@ Versioning](http://semver.org/spec/v2.0.0.html) except to the first release.
 
 ### Added
 
+- Support iproto feature discovery (#120).
+
 ### Changed
 
 ### Fixed

Diff for: connection.go

@@ -146,6 +146,8 @@ type Connection struct {
 	lenbuf  [PacketLengthBytes]byte
 
 	lastStreamId uint64
+
+	serverProtocolInfo ProtocolInfo
 }
 
 var _ = Connector(&Connection{}) // Check compatibility with connector interface.
@@ -269,6 +271,14 @@ type Opts struct {
 	Transport string
 	// SslOpts is used only if the Transport == 'ssl' is set.
 	Ssl SslOpts
+	// Minimal protocol version that should be supported by
+	// Go connection client and Tarantool server. By default
+	// it is equal to 0 (no restrictions)
+	RequiredProtocolVersion ProtocolVersion
+	// List of protocol features that should be supported by
+	// Go connection client and Tarantool server. By default
+	// it is a nil array (no restrictions)
+	RequiredProtocolFeatures []ProtocolFeature
 }
 
 // SslOpts is a way to configure ssl transport.
@@ -296,6 +306,9 @@ type SslOpts struct {
 func (opts Opts) Copy() (optsCopy Opts) {
 	optsCopy = opts
 
+	optsCopy.RequiredProtocolFeatures = make([]ProtocolFeature, len(opts.RequiredProtocolFeatures))
+	copy(optsCopy.RequiredProtocolFeatures, opts.RequiredProtocolFeatures)
+
 	return optsCopy
 }
 
@@ -508,6 +521,23 @@ func (conn *Connection) dial() (err error) {
 	conn.Greeting.Version = bytes.NewBuffer(greeting[:64]).String()
 	conn.Greeting.auth = bytes.NewBuffer(greeting[64:108]).String()
 
+	// IPROTO_ID requests can be processed without authentication.
+	// https://www.tarantool.io/en/doc/latest/dev_guide/internals/iproto/requests/#iproto-id
+	if err = conn.identify(w, r); err != nil {
+		connection.Close()
+		return err
+	}
+
+	if err = checkProtocolVersion(opts.RequiredProtocolVersion, conn.ServerProtocolVersion()); err != nil {
+		connection.Close()
+		return fmt.Errorf("identify: %w", err)
+	}
+
+	if err = checkProtocolFeatures(opts.RequiredProtocolFeatures, conn.ServerProtocolFeatures()); err != nil {
+		connection.Close()
+		return fmt.Errorf("identify: %w", err)
+	}
+
 	// Auth
 	if opts.User != "" {
 		scr, err := scramble(conn.Greeting.auth, opts.Pass)
@@ -614,6 +644,18 @@ func (conn *Connection) writeAuthRequest(w *bufio.Writer, scramble []byte) (err
 	return nil
 }
 
+func (conn *Connection) writeIdRequest(w *bufio.Writer, version ProtocolVersion,
+	features []ProtocolFeature) (err error) {
+	req := NewIdRequest(version, features)
+
+	err = conn.writeRequest(w, req)
+	if err != nil {
+		return fmt.Errorf("identify: %w", err)
+	}
+
+	return nil
+}
+
 func (conn *Connection) readResponse(r io.Reader) (resp Response, err error) {
 	respBytes, err := conn.read(r)
 	if err != nil {
@@ -645,6 +687,15 @@ func (conn *Connection) readAuthResponse(r io.Reader) (err error) {
 	return nil
 }
 
+func (conn *Connection) readIdResponse(r io.Reader) (resp Response, err error) {
+	resp, err = conn.readResponse(r)
+	if err != nil {
+		return resp, fmt.Errorf("identify: %w", err)
+	}
+
+	return resp, nil
+}
+
 func (conn *Connection) createConnection(reconnect bool) (err error) {
 	var reconnects uint
 	for conn.c == nil && conn.state == connDisconnected {
@@ -1188,3 +1239,97 @@ func (conn *Connection) NewStream() (*Stream, error) {
 		Conn: conn,
 	}, nil
 }
+
+// checkProtocolVersion checks that expected protocol version is supported.
+func checkProtocolVersion(expected ProtocolVersion, actual ProtocolVersion) error {
+	if expected > actual {
+		return fmt.Errorf("protocol version %d is not supported", expected)
+	}
+
+	return nil
+}
+
+// checkProtocolFeatures checks that expected protocol features are supported.
+func checkProtocolFeatures(expectedList []ProtocolFeature, actualList []ProtocolFeature) error {
+	var found bool
+	// It seems that iterating over a small list is way faster
+	// than building a map: https://stackoverflow.com/a/52710077/11646599
+	for _, expected := range expectedList {
+		found = false
+		for _, actual := range actualList {
+			if expected == actual {
+				found = true
+			}
+		}
+		if !found {
+			// "Feature" already is a part of the String().
+			return fmt.Errorf("%s is not supported", expected)
+		}
+	}
+
+	return nil
+}
+
+// identify sends info about client protocol, receives info
+// about server protocol in response and store it in the connection.
+func (conn *Connection) identify(w *bufio.Writer, r *bufio.Reader) error {
+	var ok bool
+
+	werr := conn.writeIdRequest(w, conn.ClientProtocolVersion(), conn.ClientProtocolFeatures())
+	if werr != nil {
+		return werr
+	}
+
+	resp, rerr := conn.readIdResponse(r)
+	if rerr != nil {
+		if resp.Code == ErrUnknownRequestType {
+			// IPROTO_ID requests are not supported by server.
+			return nil
+		}
+
+		return rerr
+	}
+
+	if len(resp.Data) == 0 {
+		return fmt.Errorf("identify: unexpected response: no data")
+	}
+
+	conn.serverProtocolInfo, ok = resp.Data[0].(ProtocolInfo)
+	if !ok {
+		return fmt.Errorf("identify: unexpected response: wrong data")
+	}
+
+	return nil
+}
+
+// ServerProtocolVersion returns protocol version supported by
+// connected Tarantool server. Beware that values might be outdated
+// if connection is in a disconnected state.
+// Since 1.10.0
+func (conn *Connection) ServerProtocolVersion() ProtocolVersion {
+	return conn.serverProtocolInfo.Version
+}
+
+// ClientProtocolVersion returns protocol version supported by
+// Go connection client.
+// Since 1.10.0
+func (conn *Connection) ClientProtocolVersion() ProtocolVersion {
+	return сlientProtocolVersion
+}
+
+// ServerFeatures returns protocol features supported by connected Tarantool server.
+// Beware that values might be outdated if connection is in a disconnected state.
+// Since 1.10.0
+func (conn *Connection) ServerProtocolFeatures() []ProtocolFeature {
+	res := make([]ProtocolFeature, len(conn.serverProtocolInfo.Features))
+	copy(res, conn.serverProtocolInfo.Features)
+	return res
+}
+
+// ClientFeatures returns protocol features supported by Go connection client.
+// Since 1.10.0
+func (conn *Connection) ClientProtocolFeatures() []ProtocolFeature {
+	res := make([]ProtocolFeature, len(сlientProtocolFeatures))
+	copy(res, сlientProtocolFeatures)
+	return res
+}

Diff for: connection_pool/example_test.go

@@ -19,7 +19,7 @@ type Tuple struct {
 
 var testRoles = []bool{true, true, false, true, true}
 
-func examplePool(roles []bool) (*connection_pool.ConnectionPool, error) {
+func examplePool(roles []bool, connOpts tarantool.Opts) (*connection_pool.ConnectionPool, error) {
 	err := test_helpers.SetClusterRO(servers, connOpts, roles)
 	if err != nil {
 		return nil, fmt.Errorf("ConnectionPool is not established")
@@ -33,7 +33,7 @@ func examplePool(roles []bool) (*connection_pool.ConnectionPool, error) {
 }
 
 func ExampleConnectionPool_Select() {
-	pool, err := examplePool(testRoles)
+	pool, err := examplePool(testRoles, connOpts)
 	if err != nil {
 		fmt.Println(err)
 	}
@@ -94,7 +94,7 @@ func ExampleConnectionPool_Select() {
 }
 
 func ExampleConnectionPool_SelectTyped() {
-	pool, err := examplePool(testRoles)
+	pool, err := examplePool(testRoles, connOpts)
 	if err != nil {
 		fmt.Println(err)
 	}
@@ -156,7 +156,7 @@ func ExampleConnectionPool_SelectTyped() {
 }
 
 func ExampleConnectionPool_SelectAsync() {
-	pool, err := examplePool(testRoles)
+	pool, err := examplePool(testRoles, connOpts)
 	if err != nil {
 		fmt.Println(err)
 	}
@@ -239,7 +239,7 @@ func ExampleConnectionPool_SelectAsync() {
 
 func ExampleConnectionPool_SelectAsync_err() {
 	roles := []bool{true, true, true, true, true}
-	pool, err := examplePool(roles)
+	pool, err := examplePool(roles, connOpts)
 	if err != nil {
 		fmt.Println(err)
 	}
@@ -258,7 +258,7 @@ func ExampleConnectionPool_SelectAsync_err() {
 }
 
 func ExampleConnectionPool_Ping() {
-	pool, err := examplePool(testRoles)
+	pool, err := examplePool(testRoles, connOpts)
 	if err != nil {
 		fmt.Println(err)
 	}
@@ -276,7 +276,7 @@ func ExampleConnectionPool_Ping() {
 }
 
 func ExampleConnectionPool_Insert() {
-	pool, err := examplePool(testRoles)
+	pool, err := examplePool(testRoles, connOpts)
 	if err != nil {
 		fmt.Println(err)
 	}
@@ -325,7 +325,7 @@ func ExampleConnectionPool_Insert() {
 }
 
 func ExampleConnectionPool_Delete() {
-	pool, err := examplePool(testRoles)
+	pool, err := examplePool(testRoles, connOpts)
 	if err != nil {
 		fmt.Println(err)
 	}
@@ -377,7 +377,7 @@ func ExampleConnectionPool_Delete() {
 }
 
 func ExampleConnectionPool_Replace() {
-	pool, err := examplePool(testRoles)
+	pool, err := examplePool(testRoles, connOpts)
 	if err != nil {
 		fmt.Println(err)
 	}
@@ -448,7 +448,7 @@ func ExampleConnectionPool_Replace() {
 }
 
 func ExampleConnectionPool_Update() {
-	pool, err := examplePool(testRoles)
+	pool, err := examplePool(testRoles, connOpts)
 	if err != nil {
 		fmt.Println(err)
 	}
@@ -492,7 +492,7 @@ func ExampleConnectionPool_Update() {
 }
 
 func ExampleConnectionPool_Call() {
-	pool, err := examplePool(testRoles)
+	pool, err := examplePool(testRoles, connOpts)
 	if err != nil {
 		fmt.Println(err)
 	}
@@ -512,7 +512,7 @@ func ExampleConnectionPool_Call() {
 }
 
 func ExampleConnectionPool_Eval() {
-	pool, err := examplePool(testRoles)
+	pool, err := examplePool(testRoles, connOpts)
 	if err != nil {
 		fmt.Println(err)
 	}
@@ -532,7 +532,7 @@ func ExampleConnectionPool_Eval() {
 }
 
 func ExampleConnectionPool_Do() {
-	pool, err := examplePool(testRoles)
+	pool, err := examplePool(testRoles, connOpts)
 	if err != nil {
 		fmt.Println(err)
 	}
@@ -551,7 +551,7 @@ func ExampleConnectionPool_Do() {
 }
 
 func ExampleConnectionPool_NewPrepared() {
-	pool, err := examplePool(testRoles)
+	pool, err := examplePool(testRoles, connOpts)
 	if err != nil {
 		fmt.Println(err)
 	}
@@ -586,7 +586,14 @@ func ExampleCommitRequest() {
 		return
 	}
 
-	pool, err := examplePool(testRoles)
+	// Assert that server supports expected features
+	txnOpts := connOpts.Copy()
+	txnOpts.RequiredProtocolFeatures = []tarantool.ProtocolFeature{
+		tarantool.StreamsFeature,
+		tarantool.TransactionsFeature,
+	}
+
+	pool, err := examplePool(testRoles, txnOpts)
 	if err != nil {
 		fmt.Println(err)
 		return
@@ -672,8 +679,15 @@ func ExampleRollbackRequest() {
 		return
 	}
 
+	// Assert that server supports expected features
+	txnOpts := connOpts.Copy()
+	txnOpts.RequiredProtocolFeatures = []tarantool.ProtocolFeature{
+		tarantool.StreamsFeature,
+		tarantool.TransactionsFeature,
+	}
+
 	// example pool has only one rw instance
-	pool, err := examplePool(testRoles)
+	pool, err := examplePool(testRoles, txnOpts)
 	if err != nil {
 		fmt.Println(err)
 		return
@@ -758,8 +772,15 @@ func ExampleBeginRequest_TxnIsolation() {
 		return
 	}
 
+	// Assert that server supports expected features
+	txnOpts := connOpts.Copy()
+	txnOpts.RequiredProtocolFeatures = []tarantool.ProtocolFeature{
+		tarantool.StreamsFeature,
+		tarantool.TransactionsFeature,
+	}
+
 	// example pool has only one rw instance
-	pool, err := examplePool(testRoles)
+	pool, err := examplePool(testRoles, txnOpts)
 	if err != nil {
 		fmt.Println(err)
 		return
@@ -836,7 +857,7 @@ func ExampleBeginRequest_TxnIsolation() {
 }
 
 func ExampleConnectorAdapter() {
-	pool, err := examplePool(testRoles)
+	pool, err := examplePool(testRoles, connOpts)
 	if err != nil {
 		fmt.Println(err)
 	}