datetime: add datetime type in msgpack

This patch provides datetime support for all space operations and as
function return result. Datetime type was introduced in Tarantool 2.10.
See more in issue [1].

Note that timezone's index and offset are not implemented in Tarantool,
see [2].

This Lua snippet was quite useful for debugging encoding and decoding
datetime in MessagePack:

```
local msgpack = require('msgpack')
local datetime = require('datetime')

local dt = datetime.parse('2012-01-31T23:59:59.000000010Z')
local mp_dt = msgpack.encode(dt):gsub('.',
    function (c)
        return string.format('%02x', string.byte(c))
    end)

print(dt, mp_dt)
```

1. tarantool/tarantool#5946
2. tarantool/tarantool#6751

Closes #118

Author: ligurio

CHANGELOG.md

@@ -16,6 +16,7 @@ Versioning](http://semver.org/spec/v2.0.0.html) except to the first release.
 - Support UUID type in msgpack (#90)
 - Go modules support (#91)
 - queue-utube handling (#85)
+- Support datetime type in msgpack (#118)
 
 ### Fixed
 

README.md

@@ -331,6 +331,49 @@ func main() {
 }
 ```
 
+To enable support of datetime in msgpack with builtin module [time](https://pkg.go.dev/time),
+import `tarantool/datetime` submodule.
+```go
+package main
+
+import (
+	"log"
+	"time"
+
+	"github.com/tarantool/go-tarantool"
+	_ "github.com/tarantool/go-tarantool/datetime"
+)
+
+func main() {
+	server := "127.0.0.1:3013"
+	opts := tarantool.Opts{
+		Timeout:       500 * time.Millisecond,
+		Reconnect:     1 * time.Second,
+		MaxReconnects: 3,
+		User:          "test",
+		Pass:          "test",
+	}
+	client, err := tarantool.Connect(server, opts)
+	if err != nil {
+		log.Fatalf("Failed to connect: %s", err.Error())
+	}
+	defer client.Close()
+
+	spaceNo := uint32(524)
+
+	tm, err := time.Parse(time.RFC3339, "2006-01-02T15:04:05Z")
+	if err != nil {
+		log.Fatalf("Failed to parse time: %s", err)
+	}
+
+	resp, err := client.Insert(spaceNo, []interface{}{tm})
+
+	log.Println("Error:", err)
+	log.Println("Code:", resp.Code)
+	log.Println("Data:", resp.Data)
+}
+```
+
 ## Schema
 
 ```go
@@ -700,9 +743,11 @@ and call
 ```bash
 go clean -testcache && go test -v
 ```
-Use the same for main `tarantool` package and `queue` and `uuid` subpackages.
+Use the same for main `tarantool` package, `queue`, `uuid` and `datetime` subpackages.
 `uuid` tests require
 [Tarantool 2.4.1 or newer](https://github.com/tarantool/tarantool/commit/d68fc29246714eee505bc9bbcd84a02de17972c5).
+`datetime` tests require
+[Tarantool 2.10 or newer](https://github.com/tarantool/tarantool/issues/5946).
 
 ## Alternative connectors
 

datetime/config.lua

@@ -0,0 +1,39 @@
+local has_datetime, _ = pcall(require, 'datetime')
+
+if not has_datetime then
+    error('Datetime unsupported, use Tarantool 2.10 or newer')
+end
+
+-- Do not set listen for now so connector won't be
+-- able to send requests until everything is configured.
+box.cfg{
+    work_dir = os.getenv("TEST_TNT_WORK_DIR"),
+}
+
+box.schema.user.create('test', { password = 'test' , if_not_exists = true })
+box.schema.user.grant('test', 'execute', 'universe', nil, { if_not_exists = true })
+
+local s = box.schema.space.create('testDatetime', {
+    id = 524,
+    if_not_exists = true,
+})
+s:create_index('primary', {
+    type = 'TREE',
+    parts = {
+        {
+            field = 1,
+            type = 'datetime',
+        },
+    },
+    if_not_exists = true
+})
+s:truncate()
+
+box.schema.user.grant('test', 'read,write', 'space', 'testDatetime', { if_not_exists = true })
+
+-- Set listen only when every other thing is configured.
+box.cfg{
+    listen = os.getenv("TEST_TNT_LISTEN"),
+}
+
+require('console').start()

datetime/datetime.go

@@ -0,0 +1,129 @@
+// Datetime MessagePack serialization schema is an MP_EXT extension, which
+// creates container of 8 or 16 bytes long payload.
+//
+//   +---------+--------+===============+-------------------------------+
+//   |0xd7/0xd8|type (4)| seconds (8b)  | nsec; tzoffset; tzindex; (8b) |
+//   +---------+--------+===============+-------------------------------+
+//
+// MessagePack data encoded using fixext8 (0xd7) or fixext16 (0xd8), and may
+// contain:
+//
+// * [required] seconds parts as full, unencoded, signed 64-bit integer,
+// stored in little-endian order;
+//
+// * [optional] all the other fields (nsec, tzoffset, tzindex) if any of them
+// were having not 0 value. They are packed naturally in little-endian order;
+package datetime
+
+import (
+	"fmt"
+	"io"
+	"math"
+	"reflect"
+	"time"
+
+	"encoding/binary"
+
+	"gopkg.in/vmihailenco/msgpack.v2"
+)
+
+// Datetime external type
+// Supported since Tarantool 2.10. See more details in issue
+// https://github.com/tarantool/tarantool/issues/5946
+const datetime_extId = 4
+
+/**
+ * datetime structure keeps number of seconds and
+ * nanoseconds since Unix Epoch.
+ * Time is normalized by UTC, so time-zone offset
+ * is informative only.
+ */
+type datetime struct {
+	// Seconds since Epoch
+	seconds int64
+	// Nanoseconds, fractional part of seconds
+	nsec int32
+	// Timezone offset in minutes from UTC
+	// (not implemented in Tarantool, https://github.com/tarantool/tarantool/issues/6751)
+	tzOffset int16
+	// Olson timezone id
+	// (not implemented in Tarantool, https://github.com/tarantool/tarantool/issues/6751)
+	tzIndex int16
+}
+
+const (
+	secondsSize  = 8
+	nsecSize     = 4
+	tzIndexSize  = 2
+	tzOffsetSize = 2
+)
+
+func encodeDatetime(e *msgpack.Encoder, v reflect.Value) error {
+	var dt datetime
+
+	tm := v.Interface().(time.Time)
+	dt.seconds = tm.Unix()
+	nsec := tm.Nanosecond()
+	dt.nsec = int32(math.Round((10000 * float64(nsec)) / 10000))
+	dt.tzIndex = 0  /* not implemented */
+	dt.tzOffset = 0 /* not implemented */
+
+	var bytesSize = secondsSize
+	if dt.nsec != 0 || dt.tzOffset != 0 || dt.tzIndex != 0 {
+		bytesSize += nsecSize + tzIndexSize + tzOffsetSize
+	}
+
+	buf := make([]byte, bytesSize)
+	binary.LittleEndian.PutUint64(buf[0:], uint64(dt.seconds))
+	if bytesSize == 16 {
+		binary.LittleEndian.PutUint32(buf[secondsSize:], uint32(dt.nsec))
+		binary.LittleEndian.PutUint16(buf[nsecSize:], uint16(dt.tzOffset))
+		binary.LittleEndian.PutUint16(buf[tzOffsetSize:], uint16(dt.tzIndex))
+	}
+
+	_, err := e.Writer().Write(buf)
+	if err != nil {
+		return fmt.Errorf("msgpack: can't write bytes to encoder writer: %w", err)
+	}
+
+	return nil
+}
+
+func decodeDatetime(d *msgpack.Decoder, v reflect.Value) error {
+	var dt datetime
+	secondsBytes := make([]byte, secondsSize)
+	n, err := d.Buffered().Read(secondsBytes)
+	if err != nil {
+		return fmt.Errorf("msgpack: can't read bytes on datetime's seconds decode: %w", err)
+	}
+	if n < secondsSize {
+		return fmt.Errorf("msgpack: unexpected end of stream after %d datetime bytes", n)
+	}
+	dt.seconds = int64(binary.LittleEndian.Uint64(secondsBytes))
+	tailSize := nsecSize + tzOffsetSize + tzIndexSize
+	tailBytes := make([]byte, tailSize)
+	n, err = d.Buffered().Read(tailBytes)
+	// Part with nanoseconds, tzoffset and tzindex is optional,
+	// so we don't need to handle an error here.
+	if err != nil && err != io.EOF {
+		return fmt.Errorf("msgpack: can't read bytes on datetime's tail decode: %w", err)
+	}
+	dt.nsec = 0
+	if err == nil {
+		if n < tailSize {
+			return fmt.Errorf("msgpack: can't read bytes on datetime's tail decode: %w", err)
+		}
+		dt.nsec = int32(binary.LittleEndian.Uint32(tailBytes[0:]))
+		dt.tzOffset = int16(binary.LittleEndian.Uint16(tailBytes[nsecSize:]))
+		dt.tzIndex = int16(binary.LittleEndian.Uint16(tailBytes[tzOffsetSize:]))
+	}
+	t := time.Unix(dt.seconds, int64(dt.nsec)).UTC()
+	v.Set(reflect.ValueOf(t))
+
+	return nil
+}
+
+func init() {
+	msgpack.Register(reflect.TypeOf((*time.Time)(nil)).Elem(), encodeDatetime, decodeDatetime)
+	msgpack.RegisterExt(datetime_extId, (*time.Time)(nil))
+}