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
RequiredFeatures to fast fail on connect in server (or even client) does
not provide some expected feature.

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 [2]. 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 [3] for more info.

1. tarantool/tarantool#6253
2. https://stackoverflow.com/a/52710077/11646599
3. tarantool/tarantool-python#262

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
+
+	serverIdInfo IdInfo
 }
 
 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 features that should be supported by
+	// Go connection client and Tarantool server. By default
+	// it is a nil array (no restrictions)
+	RequiredFeatures []Feature
 }
 
 // SslOpts is a way to configure ssl transport.
@@ -351,6 +361,16 @@ func Connect(addr string, opts Opts) (conn *Connection, err error) {
 		}
 	}
 
+	if err = checkProtocolVersion(opts.RequiredProtocolVersion, conn.ClientProtocolVersion()); err != nil {
+		return nil, fmt.Errorf("client: %w", err)
+	}
+
+	requiredFeatures := make([]Feature, len(opts.RequiredFeatures))
+	copy(requiredFeatures, opts.RequiredFeatures)
+	if err = checkFeatures(requiredFeatures, conn.ClientFeatures()); err != nil {
+		return nil, fmt.Errorf("client: %w", err)
+	}
+
 	if conn.opts.Logger == nil {
 		conn.opts.Logger = defaultLogger{}
 	}
@@ -502,6 +522,25 @@ 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("server: %w", err)
+	}
+
+	requiredFeatures := make([]Feature, len(opts.RequiredFeatures))
+	copy(requiredFeatures, opts.RequiredFeatures)
+	if err = checkFeatures(requiredFeatures, conn.ServerFeatures()); err != nil {
+		connection.Close()
+		return fmt.Errorf("server: %w", err)
+	}
+
 	// Auth
 	if opts.User != "" {
 		scr, err := scramble(conn.Greeting.auth, opts.Pass)
@@ -608,6 +647,18 @@ func (conn *Connection) writeAuthRequest(w *bufio.Writer, scramble []byte) (err
 	return nil
 }
 
+func (conn *Connection) writeIdRequest(w *bufio.Writer, version ProtocolVersion,
+	features []Feature) (err error) {
+	req := NewIdRequest(version, features)
+
+	err = conn.writeRequest(w, req)
+	if err != nil {
+		return fmt.Errorf("id: %w", err)
+	}
+
+	return nil
+}
+
 func (conn *Connection) readResponse(r io.Reader) (resp Response, err error) {
 	respBytes, err := conn.read(r)
 	if err != nil {
@@ -639,6 +690,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("id: %w", err)
+	}
+
+	return resp, nil
+}
+
 func (conn *Connection) createConnection(reconnect bool) (err error) {
 	var reconnects uint
 	for conn.c == nil && conn.state == connDisconnected {
@@ -1182,3 +1242,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
+}
+
+// checkFeatures checks that expected features are supported.
+func checkFeatures(expectedList []Feature, actualList []Feature) 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.ClientFeatures())
+	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.serverIdInfo, ok = resp.Data[0].(IdInfo)
+	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.serverIdInfo.Version
+}
+
+// ClientProtocolVersion returns protocol version supported by
+// Go connection client.
+// Since 1.10.0
+func (conn *Connection) ClientProtocolVersion() ProtocolVersion {
+	return сlientProtocolVersion
+}
+
+// ServerFeatures returns 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) ServerFeatures() []Feature {
+	res := make([]Feature, len(conn.serverIdInfo.Features))
+	copy(res, conn.serverIdInfo.Features)
+	return res
+}
+
+// ClientFeatures returns features supported by Go connection client.
+// Since 1.10.0
+func (conn *Connection) ClientFeatures() []Feature {
+	res := make([]Feature, len(сlientFeatures))
+	copy(res, сlientFeatures)
+	return res
+}

Diff for: connection_pool/example_test.go

@@ -32,6 +32,19 @@ func examplePool(roles []bool) (*connection_pool.ConnectionPool, error) {
 	return connPool, nil
 }
 
+func examplePoolWithOpts(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")
+	}
+	connPool, err := connection_pool.Connect(servers, connOpts)
+	if err != nil || connPool == nil {
+		return nil, fmt.Errorf("ConnectionPool is not established")
+	}
+
+	return connPool, nil
+}
+
 func ExampleConnectionPool_Select() {
 	pool, err := examplePool(testRoles)
 	if err != nil {
@@ -586,7 +599,14 @@ func ExampleCommitRequest() {
 		return
 	}
 
-	pool, err := examplePool(testRoles)
+	// Assert that server supports expected features
+	txnOpts := connOpts
+	txnOpts.RequiredFeatures = []tarantool.Feature{
+		tarantool.StreamsFeature,
+		tarantool.TransactionsFeature,
+	}
+
+	pool, err := examplePoolWithOpts(testRoles, txnOpts)
 	if err != nil {
 		fmt.Println(err)
 		return
@@ -672,8 +692,15 @@ func ExampleRollbackRequest() {
 		return
 	}
 
+	// Assert that server supports expected features
+	txnOpts := connOpts
+	txnOpts.RequiredFeatures = []tarantool.Feature{
+		tarantool.StreamsFeature,
+		tarantool.TransactionsFeature,
+	}
+
 	// example pool has only one rw instance
-	pool, err := examplePool(testRoles)
+	pool, err := examplePoolWithOpts(testRoles, txnOpts)
 	if err != nil {
 		fmt.Println(err)
 		return
@@ -758,8 +785,15 @@ func ExampleBeginRequest_TxnIsolation() {
 		return
 	}
 
+	// Assert that server supports expected features
+	txnOpts := connOpts
+	txnOpts.RequiredFeatures = []tarantool.Feature{
+		tarantool.StreamsFeature,
+		tarantool.TransactionsFeature,
+	}
+
 	// example pool has only one rw instance
-	pool, err := examplePool(testRoles)
+	pool, err := examplePoolWithOpts(testRoles, txnOpts)
 	if err != nil {
 		fmt.Println(err)
 		return

Diff for: const.go

@@ -18,6 +18,7 @@ const (
 	RollbackRequestCode  = 16
 	PingRequestCode      = 64
 	SubscribeRequestCode = 66
+	IdRequestCode        = 73
 
 	KeyCode         = 0x00
 	KeySync         = 0x01
@@ -41,6 +42,8 @@ const (
 	KeySQLBind      = 0x41
 	KeySQLInfo      = 0x42
 	KeyStmtID       = 0x43
+	KeyVersion      = 0x54
+	KeyFeatures     = 0x55
 	KeyTimeout      = 0x56
 	KeyTxnIsolation = 0x59
 

Diff for: example_test.go

@@ -26,6 +26,14 @@ func example_connect() *tarantool.Connection {
 	return conn
 }
 
+func example_connect_with_opts(opts tarantool.Opts) *tarantool.Connection {
+	conn, err := tarantool.Connect(server, opts)
+	if err != nil {
+		panic("Connection is not established: " + err.Error())
+	}
+	return conn
+}
+
 // Example demonstrates how to use SSL transport.
 func ExampleSslOpts() {
 	var opts = tarantool.Opts{
@@ -331,7 +339,14 @@ func ExampleCommitRequest() {
 		return
 	}
 
-	conn := example_connect()
+	// Assert that server supports expected features
+	txnOpts := opts
+	txnOpts.RequiredFeatures = []tarantool.Feature{
+		tarantool.StreamsFeature,
+		tarantool.TransactionsFeature,
+	}
+
+	conn := example_connect_with_opts(txnOpts)
 	defer conn.Close()
 
 	stream, _ := conn.NewStream()
@@ -407,7 +422,14 @@ func ExampleRollbackRequest() {
 		return
 	}
 
-	conn := example_connect()
+	// Assert that server supports expected features
+	txnOpts := opts
+	txnOpts.RequiredFeatures = []tarantool.Feature{
+		tarantool.StreamsFeature,
+		tarantool.TransactionsFeature,
+	}
+
+	conn := example_connect_with_opts(txnOpts)
 	defer conn.Close()
 
 	stream, _ := conn.NewStream()
@@ -483,7 +505,14 @@ func ExampleBeginRequest_TxnIsolation() {
 		return
 	}
 
-	conn := example_connect()
+	// Assert that server supports expected features
+	txnOpts := opts
+	txnOpts.RequiredFeatures = []tarantool.Feature{
+		tarantool.StreamsFeature,
+		tarantool.TransactionsFeature,
+	}
+
+	conn := example_connect_with_opts(txnOpts)
 	defer conn.Close()
 
 	stream, _ := conn.NewStream()

Diff for: export_test.go

@@ -111,6 +111,12 @@ func RefImplRollbackBody(enc *encoder) error {
 	return fillRollback(enc)
 }
 
+// RefImplIdBody is reference implementation for filling of an id
+// request's body.
+func RefImplIdBody(enc *encoder, version ProtocolVersion, features []Feature) error {
+	return fillId(enc, version, features)
+}
+
 func NewEncoder(w io.Writer) *encoder {
 	return newEncoder(w)
 }