api: add a public API with request types

This patch provides request types for part of space operations: Select,
Update and Upstream. It allows to create requests step by step. The
main idea here is too provide more extensible approach to create
requests.

It renames IPROTO constants that identify requests from `NameRequest`
to `NameRequestCode` to provide names for request types.

Part of #126

Author: oleg-jukovec

CHANGELOG.md

@@ -12,9 +12,13 @@ Versioning](http://semver.org/spec/v2.0.0.html) except to the first release.
 
 - SSL support (#155)
 - IPROTO_PUSH messages support (#67)
+- Public API with request object types (#126)
 
 ### Changed
 
+- IPROTO constants that identify requests renamed from `NameRequest` to
+  `NameRequestCode` (#126)
+
 ### Fixed
 
 ## [1.6.0] - 2022-06-01

client_tools.go

@@ -67,6 +67,79 @@ func (o Op) EncodeMsgpack(enc *msgpack.Encoder) error {
 	return enc.Encode(o.Arg)
 }
 
+const (
+	appendOperator      = "+"
+	subtractionOperator = "-"
+	bitwiseAndOperator  = "&"
+	bitwiseOrOperator   = "|"
+	bitwiseXorOperator  = "^"
+	spliceOperator      = ":"
+	insertOperator      = "!"
+	deleteOperator      = "#"
+	assignOperator      = "="
+)
+
+// Operations is a collection of update operations.
+type Operations struct {
+	ops []Op
+}
+
+// NewOperations returns a new empty collection of update operations.
+func NewOperations() *Operations {
+	ops := new(Operations)
+	return ops
+}
+
+func (ops *Operations) append(op string, field int, arg interface{}) *Operations {
+	ops.ops = append(ops.ops, Op{op, field, arg})
+	return ops
+}
+
+// Add adds an additional operation to the collection of update operations.
+func (ops *Operations) Add(field int, arg interface{}) *Operations {
+	return ops.append(appendOperator, field, arg)
+}
+
+// Subtract adds a subtraction operation to the collection of update operations.
+func (ops *Operations) Subtract(field int, arg interface{}) *Operations {
+	return ops.append(subtractionOperator, field, arg)
+}
+
+// BitwiseAnd adds a bitwise AND operation to the collection of update operations.
+func (ops *Operations) BitwiseAnd(field int, arg interface{}) *Operations {
+	return ops.append(bitwiseAndOperator, field, arg)
+}
+
+// BitwiseOr adds a bitwise OR operation to the collection of update operations.
+func (ops *Operations) BitwiseOr(field int, arg interface{}) *Operations {
+	return ops.append(bitwiseOrOperator, field, arg)
+}
+
+// BitwiseXor adds a bitwise XOR operation to the collection of update operations.
+func (ops *Operations) BitwiseXor(field int, arg interface{}) *Operations {
+	return ops.append(bitwiseXorOperator, field, arg)
+}
+
+// Splice adds a splice operation to the collection of update operations.
+func (ops *Operations) Splice(field int, arg interface{}) *Operations {
+	return ops.append(spliceOperator, field, arg)
+}
+
+// Insert adds an insert operation to the collection of update operations.
+func (ops *Operations) Insert(field int, arg interface{}) *Operations {
+	return ops.append(insertOperator, field, arg)
+}
+
+// Delete adds a delete operation to the collection of update operations.
+func (ops *Operations) Delete(field int, arg interface{}) *Operations {
+	return ops.append(deleteOperator, field, arg)
+}
+
+// Assign adds an assign operation to the collection of update operations.
+func (ops *Operations) Assign(field int, arg interface{}) *Operations {
+	return ops.append(assignOperator, field, arg)
+}
+
 type OpSplice struct {
 	Op      string
 	Field   int

connection.go

@@ -471,7 +471,7 @@ func (conn *Connection) dial() (err error) {
 func (conn *Connection) writeAuthRequest(w *bufio.Writer, scramble []byte) (err error) {
 	request := &Future{
 		requestId:   0,
-		requestCode: AuthRequest,
+		requestCode: AuthRequestCode,
 	}
 	var packet smallWBuf
 	err = request.pack(&packet, msgpack.NewEncoder(&packet), func(enc *msgpack.Encoder) error {
@@ -978,6 +978,43 @@ func (conn *Connection) nextRequestId() (requestId uint32) {
 	return atomic.AddUint32(&conn.requestId, 1)
 }
 
+// Do verifies, sends the request and returns a response.
+//
+// An error is returned if the request was formed incorrectly, or failure to
+// communicate by the connection, or unable to decode the response.
+func (conn *Connection) Do(req Request) (*Response, error) {
+	fut, err := conn.DoAsync(req)
+	if err != nil {
+		return nil, err
+	}
+	return fut.Get()
+}
+
+// DoTyped verifies, sends the request and fills the typed result.
+//
+// An error is returned if the request was formed incorrectly, or failure to
+// communicate by the connection, or unable to decode the response.
+func (conn *Connection) DoTyped(req Request, result interface{}) error {
+	fut, err := conn.DoAsync(req)
+	if err != nil {
+		return err
+	}
+	return fut.GetTyped(result)
+}
+
+// DoAsync verifies, sends the request and returns a future.
+//
+// An error is returned if the request was formed incorrectly, or failure to
+// create the future.
+func (conn *Connection) DoAsync(req Request) (*Future, error) {
+	bodyFunc, err := req.BodyFunc(conn.Schema)
+	if err != nil {
+		return nil, err
+	}
+	future := conn.newFuture(req.Code())
+	return conn.sendFuture(future, bodyFunc), nil
+}
+
 // ConfiguredTimeout returns a timeout from connection config.
 func (conn *Connection) ConfiguredTimeout() time.Duration {
 	return conn.opts.Timeout

const.go

@@ -1,19 +1,19 @@
 package tarantool
 
 const (
-	SelectRequest    = 1
-	InsertRequest    = 2
-	ReplaceRequest   = 3
-	UpdateRequest    = 4
-	DeleteRequest    = 5
-	CallRequest      = 6 /* call in 1.6 format */
-	AuthRequest      = 7
-	EvalRequest      = 8
-	UpsertRequest    = 9
-	Call17Request    = 10
-	ExecuteRequest   = 11
-	PingRequest      = 64
-	SubscribeRequest = 66
+	SelectRequestCode    = 1
+	InsertRequestCode    = 2
+	ReplaceRequestCode   = 3
+	UpdateRequestCode    = 4
+	DeleteRequestCode    = 5
+	CallRequestCode      = 6 /* call in 1.6 format */
+	AuthRequestCode      = 7
+	EvalRequestCode      = 8
+	UpsertRequestCode    = 9
+	Call17RequestCode    = 10
+	ExecuteRequestCode   = 11
+	PingRequestCode      = 64
+	SubscribeRequestCode = 66
 
 	KeyCode         = 0x00
 	KeySync         = 0x01

example_test.go

@@ -126,6 +126,116 @@ func ExampleConnection_SelectAsync() {
 	// Future 2 Data [[18 val 18 bla]]
 }
 
+func ExampleSelectRequest() {
+	conn := example_connect()
+	defer conn.Close()
+
+	req := tarantool.NewSelectRequest(517).
+		Limit(100).
+		Key(tarantool.IntKey{1111})
+	resp, err := conn.Do(req)
+	if err != nil {
+		fmt.Printf("error in do select request is %v", err)
+		return
+	}
+	fmt.Printf("response is %#v\n", resp.Data)
+
+	req = tarantool.NewSelectRequest("test").
+		Index("primary").
+		Limit(100).
+		Key(tarantool.IntKey{1111})
+	fut, err := conn.DoAsync(req)
+	if err != nil {
+		fmt.Printf("error in do async select request is %v", err)
+	}
+	resp, err = fut.Get()
+	if err != nil {
+		fmt.Printf("error in do async select request is %v", err)
+		return
+	}
+	fmt.Printf("response is %#v\n", resp.Data)
+	// Output:
+	// response is []interface {}{[]interface {}{0x457, "hello", "world"}}
+	// response is []interface {}{[]interface {}{0x457, "hello", "world"}}
+}
+
+func ExampleUpdateRequest() {
+	conn := example_connect()
+	defer conn.Close()
+
+	req := tarantool.NewUpdateRequest(517).
+		Key(tarantool.IntKey{1111}).
+		Operations(tarantool.NewOperations().Assign(1, "bye"))
+	resp, err := conn.Do(req)
+	if err != nil {
+		fmt.Printf("error in do update request is %v", err)
+		return
+	}
+	fmt.Printf("response is %#v\n", resp.Data)
+
+	req = tarantool.NewUpdateRequest("test").
+		Index("primary").
+		Key(tarantool.IntKey{1111}).
+		Operations(tarantool.NewOperations().Assign(1, "hello"))
+	fut, err := conn.DoAsync(req)
+	if err != nil {
+		fmt.Printf("error in do async update request is %v", err)
+	}
+	resp, err = fut.Get()
+	if err != nil {
+		fmt.Printf("error in do async update request is %v", err)
+		return
+	}
+	fmt.Printf("response is %#v\n", resp.Data)
+	// Output:
+	// response is []interface {}{[]interface {}{0x457, "bye", "world"}}
+	// response is []interface {}{[]interface {}{0x457, "hello", "world"}}
+}
+
+func ExampleUpsertRequest() {
+	conn := example_connect()
+	defer conn.Close()
+
+	var req tarantool.Request
+	req = tarantool.NewUpsertRequest(517).
+		Tuple([]interface{}{uint(1113), "first", "first"}).
+		Operations(tarantool.NewOperations().Assign(1, "updated"))
+	resp, err := conn.Do(req)
+	if err != nil {
+		fmt.Printf("error in do select upsert is %v", err)
+		return
+	}
+	fmt.Printf("response is %#v\n", resp.Data)
+
+	req = tarantool.NewUpsertRequest("test").
+		Tuple([]interface{}{uint(1113), "second", "second"}).
+		Operations(tarantool.NewOperations().Assign(2, "updated"))
+	fut, err := conn.DoAsync(req)
+	if err != nil {
+		fmt.Printf("error in do async upsert request is %v", err)
+	}
+	resp, err = fut.Get()
+	if err != nil {
+		fmt.Printf("error in do async upsert request is %v", err)
+		return
+	}
+	fmt.Printf("response is %#v\n", resp.Data)
+
+	req = tarantool.NewSelectRequest(517).
+		Limit(100).
+		Key(tarantool.IntKey{1113})
+	resp, err = conn.Do(req)
+	if err != nil {
+		fmt.Printf("error in do select request is %v", err)
+		return
+	}
+	fmt.Printf("response is %#v\n", resp.Data)
+	// Output:
+	// response is []interface {}{}
+	// response is []interface {}{}
+	// response is []interface {}{[]interface {}{0x459, "first", "updated"}}
+}
+
 func ExampleFuture_GetIterator() {
 	conn := example_connect()
 	defer conn.Close()

export_test.go

@@ -3,11 +3,9 @@ package tarantool
 import (
 	"net"
 	"time"
-)
 
-func (schema *Schema) ResolveSpaceIndex(s interface{}, i interface{}) (spaceNo, indexNo uint32, err error) {
-	return schema.resolveSpaceIndex(s, i)
-}
+	"gopkg.in/vmihailenco/msgpack.v2"
+)
 
 func SslDialTimeout(network, address string, timeout time.Duration,
 	opts SslOpts) (connection net.Conn, err error) {
@@ -17,3 +15,63 @@ func SslDialTimeout(network, address string, timeout time.Duration,
 func SslCreateContext(opts SslOpts) (ctx interface{}, err error) {
 	return sslCreateContext(opts)
 }
+
+// RefImplPingBody is reference implementation for filling of a ping
+// request's body.
+func RefImplPingBody(enc *msgpack.Encoder) error {
+	return fillPing(enc)
+}
+
+// RefImplSelectBody is reference implementation for filling of a select
+// request's body.
+func RefImplSelectBody(enc *msgpack.Encoder, space, index, offset, limit, iterator uint32, key interface{}) error {
+	return fillSelect(enc, space, index, offset, limit, iterator, key)
+}
+
+// RefImplInsertBody is reference implementation for filling of an insert
+// request's body.
+func RefImplInsertBody(enc *msgpack.Encoder, space uint32, tuple interface{}) error {
+	return fillInsert(enc, space, tuple)
+}
+
+// RefImplReplaceBody is reference implementation for filling of a replace
+// request's body.
+func RefImplReplaceBody(enc *msgpack.Encoder, space uint32, tuple interface{}) error {
+	return fillInsert(enc, space, tuple)
+}
+
+// RefImplDeleteBody is reference implementation for filling of a delete
+// request's body.
+func RefImplDeleteBody(enc *msgpack.Encoder, space, index uint32, key interface{}) error {
+	return fillDelete(enc, space, index, key)
+}
+
+// RefImplUpdateBody is reference implementation for filling of an update
+// request's body.
+func RefImplUpdateBody(enc *msgpack.Encoder, space, index uint32, key, ops interface{}) error {
+	return fillUpdate(enc, space, index, key, ops)
+}
+
+// RefImplUpsertBody is reference implementation for filling of an upsert
+// request's body.
+func RefImplUpsertBody(enc *msgpack.Encoder, space uint32, tuple, ops interface{}) error {
+	return fillUpsert(enc, space, tuple, ops)
+}
+
+// RefImplCallBody is reference implementation for filling of a call or call17
+// request's body.
+func RefImplCallBody(enc *msgpack.Encoder, function string, args interface{}) error {
+	return fillCall(enc, function, args)
+}
+
+// RefImplEvalBody is reference implementation for filling of an eval
+// request's body.
+func RefImplEvalBody(enc *msgpack.Encoder, expr string, args interface{}) error {
+	return fillEval(enc, expr, args)
+}
+
+// RefImplExecuteBody is reference implementation for filling of an execute
+// request's body.
+func RefImplExecuteBody(enc *msgpack.Encoder, expr string, args interface{}) error {
+	return fillExecute(enc, expr, args)
+}