introduce internal API for raw tuples

This patch introduces internal API for insert, replace and upsert
raw tuples. To reduce amonut of changes this methods will be
exposed in next patches. Hovewer this patch already tries to
support naming convenstion: we internally use module.object for
operations on objects and module.tuple for operations on tuples.

Also some kind of optimization is introduced. Before this patch we
call unflatten for object twice. This patch removes one of them.
This way reduce amount of Lua garbage.

Part of #6

Author: olegrok

crud.lua

@@ -25,25 +25,25 @@ crud.register = registry.add
 --- CRUD operations.
 -- @section crud
 
--- @refer insert.call
+-- @refer insert.object
 -- @function insert
-crud.insert = insert.call
+crud.insert = insert.object
 
 -- @refer get.call
 -- @function get
 crud.get = get.call
 
--- @refer replace.call
+-- @refer replace.object
 -- @function replace
-crud.replace = replace.call
+crud.replace = replace.object
 
 -- @refer update.call
 -- @function update
 crud.update = update.call
 
--- @refer upsert.call
+-- @refer upsert.object
 -- @function upsert
-crud.upsert = upsert.call
+crud.upsert = upsert.object
 
 -- @refer delete.call
 -- @function delete

crud/common/utils.lua

@@ -5,6 +5,7 @@ local dev_checks = require('crud.common.dev_checks')
 local FlattenError = errors.new_class("FlattenError", {capture_stack = false})
 local UnflattenError = errors.new_class("UnflattenError", {capture_stack = false})
 local ParseOperationsError = errors.new_class('ParseOperationsError',  {capture_stack = false})
+local ShardingError = errors.new_class('ShardingError',  {capture_stack = false})
 
 local utils = {}
 
@@ -195,4 +196,14 @@ function utils.reverse_inplace(t)
     return t
 end
 
+function utils.get_bucket_id_fieldno(space, shard_index_name)
+    shard_index_name = shard_index_name or 'bucket_id'
+    local bucket_id_index = space.index[shard_index_name]
+    if bucket_id_index == nil then
+        return nil, ShardingError:new('%q index is not found', shard_index_name)
+    end
+
+    return bucket_id_index.parts[1].fieldno
+end
+
 return utils

crud/insert.lua

@@ -30,27 +30,24 @@ function insert.init()
     })
 end
 
---- Inserts tuple to the specified space
+--- Inserts a tuple to the specified space
 --
--- @function call
+-- @function tuple
 --
 -- @param string space_name
 --  A space name
 --
--- @param table key_parts
---  Primary key fields' names array
---
--- @param table obj
---  Tuple object (according to space format)
+-- @param table tuple
+--  Tuple
 --
 -- @tparam ?number opts.timeout
 --  Function call timeout
 --
--- @return[1] object
+-- @return[1] tuple
 -- @treturn[2] nil
 -- @treturn[2] table Error description
 --
-function insert.call(space_name, obj, opts)
+function insert.tuple(space_name, tuple, opts)
     checks('string', 'table', {
         timeout = '?number',
     })
@@ -63,25 +60,24 @@ function insert.call(space_name, obj, opts)
     end
     local space_format = space:format()
 
-    -- compute default bucket_id
-    local tuple, err = utils.flatten(obj, space_format)
-    if err ~= nil then
-        return nil, InsertError:new("Object is specified in bad format: %s", err)
-    end
-
     local key = utils.extract_key(tuple, space.index[0].parts)
-
     local bucket_id = vshard.router.bucket_id_strcrc32(key)
     local replicaset, err = vshard.router.route(bucket_id)
     if replicaset == nil then
         return nil, InsertError:new("Failed to get replicaset for bucket_id %s: %s", bucket_id, err.err)
     end
 
-    local tuple, err = utils.flatten(obj, space_format, bucket_id)
+    local bucket_id_fieldno, err = utils.get_bucket_id_fieldno(space)
     if err ~= nil then
-        return nil, InsertError:new("Object is specified in bad format: %s", err)
+        return nil, err
+    end
+
+    if tuple[bucket_id_fieldno] ~= nil then
+        return nil, InsertError:new("Unexpected value (%s) at field %s (sharding key)",
+                tuple[bucket_id_fieldno], bucket_id_fieldno)
     end
 
+    tuple[bucket_id_fieldno] = bucket_id
     local results, err = call.rw(INSERT_FUNC_NAME, {space_name, tuple}, {
         replicasets = {replicaset},
         timeout = opts.timeout,
@@ -98,4 +94,42 @@ function insert.call(space_name, obj, opts)
     }
 end
 
+--- Inserts an object to the specified space
+--
+-- @function object
+--
+-- @param string space_name
+--  A space name
+--
+-- @param table obj
+--  Object
+--
+-- @tparam ?number opts.timeout
+--  Function call timeout
+--
+-- @return[1] object
+-- @treturn[2] nil
+-- @treturn[2] table Error description
+--
+function insert.object(space_name, obj, opts)
+    checks('string', 'table', {
+        timeout = '?number',
+    })
+
+    opts = opts or {}
+
+    local space = utils.get_space(space_name, vshard.router.routeall())
+    if space == nil then
+        return nil, InsertError:new("Space %q doesn't exists", space_name)
+    end
+    local space_format = space:format()
+
+    local tuple, err = utils.flatten(obj, space_format)
+    if err ~= nil then
+        return nil, InsertError:new("Object is specified in bad format: %s", err)
+    end
+
+    return insert.tuple(space_name, tuple, opts)
+end
+
 return insert

crud/replace.lua

@@ -32,13 +32,13 @@ end
 
 --- Insert or replace a tuple in the specified space
 --
--- @function call
+-- @function tuple
 --
 -- @param string space_name
 --  A space name
 --
--- @param table obj
---  Tuple object (according to space format)
+-- @param table tuple
+--  Tuple
 --
 -- @tparam ?number opts.timeout
 --  Function call timeout
@@ -47,7 +47,7 @@ end
 -- @treturn[2] nil
 -- @treturn[2] table Error description
 --
-function replace.call(space_name, obj, opts)
+function replace.tuple(space_name, tuple, opts)
     checks('string', 'table', {
         timeout = '?number',
     })
@@ -59,13 +59,6 @@ function replace.call(space_name, obj, opts)
         return nil, ReplaceError:new("Space %q doesn't exist", space_name)
     end
 
-    local space_format = space:format()
-    -- compute default bucket_id
-    local tuple, err = utils.flatten(obj, space_format)
-    if err ~= nil then
-        return nil, ReplaceError:new("Object is specified in bad format: %s", err)
-    end
-
     local key = utils.extract_key(tuple, space.index[0].parts)
 
     local bucket_id = vshard.router.bucket_id_strcrc32(key)
@@ -74,11 +67,17 @@ function replace.call(space_name, obj, opts)
         return nil, ReplaceError:new("Failed to get replicaset for bucket_id %s: %s", bucket_id, err.err)
     end
 
-    local tuple, err = utils.flatten(obj, space_format, bucket_id)
+    local bucket_id_fieldno, err = utils.get_bucket_id_fieldno(space)
     if err ~= nil then
-        return nil, ReplaceError:new("Object is specified in bad format: %s", err)
+        return nil, err
     end
 
+    if tuple[bucket_id_fieldno] ~= nil then
+        return nil, ReplaceError:new("Unexpected value (%s) at field %s (sharding key)",
+                tuple[bucket_id_fieldno], bucket_id_fieldno)
+    end
+
+    tuple[bucket_id_fieldno] = bucket_id
     local results, err = call.rw(REPLACE_FUNC_NAME, {space_name, tuple}, {
         replicasets = {replicaset},
         timeout = opts.timeout,
@@ -90,9 +89,47 @@ function replace.call(space_name, obj, opts)
 
     local tuple = results[replicaset.uuid]
     return {
-        metadata = table.copy(space_format),
+        metadata = table.copy(space:format()),
         rows = {tuple},
     }
 end
 
+--- Insert or replace an object in the specified space
+--
+-- @function object
+--
+-- @param string space_name
+--  A space name
+--
+-- @param table obj
+--  Object
+--
+-- @tparam ?number opts.timeout
+--  Function call timeout
+--
+-- @return[1] object
+-- @treturn[2] nil
+-- @treturn[2] table Error description
+--
+function replace.object(space_name, obj, opts)
+    checks('string', 'table', {
+        timeout = '?number',
+    })
+
+    opts = opts or {}
+
+    local space = utils.get_space(space_name, vshard.router.routeall())
+    if space == nil then
+        return nil, ReplaceError:new("Space %q doesn't exists", space_name)
+    end
+
+    local space_format = space:format()
+    local tuple, err = utils.flatten(obj, space_format)
+    if err ~= nil then
+        return nil, ReplaceError:new("Object is specified in bad format: %s", err)
+    end
+
+    return replace.tuple(space_name, tuple, opts)
+end
+
 return replace

crud/upsert.lua

@@ -32,26 +32,26 @@ end
 
 --- Update or insert a tuple in the specified space
 --
--- @function call
+-- @function tuple
 --
 -- @param string space_name
 --  A space name
 --
--- @param table obj
---  Tuple object (according to space format)
+-- @param table tuple
+--  Tuple
 --
 -- @param table user_operations
 --  user_operations to be performed.
---  See `space:update` operations in Tarantool doc
+--  See `space:upsert()` operations in Tarantool doc
 --
 -- @tparam ?number opts.timeout
 --  Function call timeout
 --
--- @return[1] object
+-- @return[1] tuple
 -- @treturn[2] nil
 -- @treturn[2] table Error description
 --
-function upsert.call(space_name, obj, user_operations, opts)
+function upsert.tuple(space_name, tuple, user_operations, opts)
     checks('string', '?', 'table', {
         timeout = '?number',
     })
@@ -69,12 +69,6 @@ function upsert.call(space_name, obj, user_operations, opts)
         return nil, UpsertError:new("Wrong operations are specified: %s", err)
     end
 
-    -- compute default bucket_id
-    local tuple, err = utils.flatten(obj, space_format)
-    if err ~= nil then
-        return nil, UpsertError:new("Object is specified in bad format: %s", err)
-    end
-
     local key = utils.extract_key(tuple, space.index[0].parts)
 
     local bucket_id = vshard.router.bucket_id_strcrc32(key)
@@ -83,11 +77,17 @@ function upsert.call(space_name, obj, user_operations, opts)
         return nil, UpsertError:new("Failed to get replicaset for bucket_id %s: %s", bucket_id, err.err)
     end
 
-    local tuple, err = utils.flatten(obj, space_format, bucket_id)
+    local bucket_id_fieldno, err = utils.get_bucket_id_fieldno(space)
     if err ~= nil then
-        return nil, UpsertError:new("Object is specified in bad format: %s", err)
+        return nil, err
+    end
+
+    if tuple[bucket_id_fieldno] ~= nil then
+        return nil, UpsertError:new("Unexpected value (%s) at field %s (sharding key)",
+                tuple[bucket_id_fieldno], bucket_id_fieldno)
     end
 
+    tuple[bucket_id_fieldno] = bucket_id
     local _, err = call.rw(UPSERT_FUNC_NAME, {space_name, tuple, operations}, {
         replicasets = {replicaset},
         timeout = opts.timeout,
@@ -104,4 +104,47 @@ function upsert.call(space_name, obj, user_operations, opts)
     }
 end
 
+--- Update or insert an object in the specified space
+--
+-- @function object
+--
+-- @param string space_name
+--  A space name
+--
+-- @param table obj
+--  Object
+--
+-- @param table user_operations
+--  user_operations to be performed.
+--  See `space:upsert()` operations in Tarantool doc
+--
+-- @tparam ?number opts.timeout
+--  Function call timeout
+--
+-- @return[1] object
+-- @treturn[2] nil
+-- @treturn[2] table Error description
+--
+function upsert.object(space_name, obj, user_operations, opts)
+    checks('string', '?', 'table', {
+        timeout = '?number',
+    })
+
+    opts = opts or {}
+
+    local space = utils.get_space(space_name, vshard.router.routeall())
+    if space == nil then
+        return nil, UpsertError:new("Space %q doesn't exists", space_name)
+    end
+
+    local space_format = space:format()
+
+    local tuple, err = utils.flatten(obj, space_format)
+    if err ~= nil then
+        return nil, UpsertError:new("Object is specified in bad format: %s", err)
+    end
+
+    return upsert.tuple(space_name, tuple, user_operations, opts)
+end
+
 return upsert