config/schema: support unique_items annotation

The motivation is to allow to assign a user-provided `validate`
annotation for an array with unique items. This is used in the next
commit to simplify config's code.

See the API description in the documentation request below.

@TarantoolBot document
Title: schema: `unique_items` annotation

Since Tarantool 3.4 the `experimental.config.utils.schema` module has
the `unique_items` annotation taken into account by the `<schema
object>:validate()` method.

The annotation can be assigned to a schema node that represents an array
of strings. An attempt to assign it to another schema node leads to an
error on the schema object creation (`schema.new()`).

The `<schema object>:validate()` method now raises an error if the
`unique_items` annotation is assigned and truthly, but the corresponding
value (an array) contains the same string two or more times.

The `schema.set()` constructor (creates an array with enumerated values
without duplicates) now assigns the `unique_items` annotation to the
created schema node instead of defining its own `validate` annotation.

The `schema.set()` constructor now allows a user to define the
`validate` annotation for the new schema node.

Example 1 (use `unique_items`):

```lua
local schema = require('experimental.config.utils.schema')

local s = schema.new('myschema', schema.array({
    items = schema.scalar({type = 'string'}),
    unique_items = true,
}))

s:validate({'foo', 'bar'})
-- OK

s:validate({'foo', 'foo'})
-- error: [myschema] Values should be unique, but "foo" appears at least
-- twice
```

Example 2 (use the `schema.set()` constructor):

```lua
local schema = require('experimental.config.utils.schema')

local s = schema.new('myschema', schema.set({'foo', 'bar'}))

s:validate({'foo', 'bar'})
-- OK

s:validate({'foo', 'foo'})
-- error: [myschema] Values should be unique, but "foo" appears at least
-- twice
```

Example 3 (use the `validate` annotation):

```lua
local fun = require('fun')
local schema = require('experimental.config.utils.schema')

local s = schema.new('myschema', schema.set({
    'router',
    'storage',
    'rebalancer',
}, {
    validate = function(data, w)
        local kv = fun.iter(data):map(function(x) return x, true end):tomap()
        if kv.rebalancer and not kv.storage then
            w.error('rebalancer needs storage role enabled')
        end
    end,
}))

s:validate({'storage', 'rebalancer'})
-- OK

s:validate({'rebalancer'})
-- error: [myschema] rebalancer needs storage role enabled
```

Example 4 (`unique_items` on an unsupported type):

```lua
local schema = require('experimental.config.utils.schema')

local s = schema.new('myschema', schema.array({
    items = schema.scalar({type = 'integer'}),
    unique_items = true,
}))
-- error: [myschema] "unique_items" requires an array of strings, got an
-- array of integer items
```

Author: Totktonada

changelogs/unreleased/config-schema-unique-items.md

@@ -0,0 +1,5 @@
+## feature/config
+
+* `<schema object>:validate()` now takes into account the `unique_items` annotation.
+
+  Also, `schema.set()` now accepts a user-provided `validate` annotation.

src/box/lua/config/utils/schema.lua

@@ -4,6 +4,7 @@
 -- itself (affects work of the schema methods):
 --
 -- * allowed_values
+-- * unique_items
 -- * validate
 -- * default
 -- * apply_default_if
@@ -415,18 +416,6 @@ end
 
 -- {{{ Derived schema node type constructors: enum, set
 
-local function validate_no_repeat(data, w)
-    local visited = {}
-    for _, item in ipairs(data) do
-        assert(type(item) == 'string')
-        if visited[item] then
-            w.error('Values should be unique, but %q appears at ' ..
-                'least twice', item)
-        end
-        visited[item] = true
-    end
-end
-
 -- Shortcut for a string scalar with given allowed values.
 local function enum(allowed_values, annotations)
     local scalar_def = {
@@ -445,10 +434,10 @@ end
 local function set(allowed_values, annotations)
     local array_def = {
         items = enum(allowed_values),
-        validate = validate_no_repeat,
+        unique_items = true,
     }
     for k, v in pairs(annotations or {}) do
-        assert(k ~= 'type' and k ~= 'items' and k ~= 'validate')
+        assert(k ~= 'type' and k ~= 'items')
         array_def[k] = v
     end
     return array(array_def)
@@ -611,6 +600,56 @@ local function validate_by_allowed_values(schema, data, ctx)
     end
 end
 
+-- If the unique_items annotation is present (and truthly), verify
+-- that the given array has no duplicates.
+local function validate_unique_items(schema, data, ctx)
+    if not schema.unique_items then
+        return
+    end
+
+    -- These prerequisites are checked in
+    -- validate_schema_node_unique_items().
+    assert(schema.type == 'array')
+    assert(schema.items.type == 'string')
+
+    -- It is checked in validate_impl(), but let's have an
+    -- assertion here.
+    assert(type(data) == 'table')
+
+    -- If we support the annotation only for an array of strings,
+    -- a simple duplicate check algorithm with a visited set can
+    -- be used.
+    --
+    -- We can extend it to all the scalar types except 'any'
+    -- without changing the algorithm.
+    --
+    -- If we add support for numeric types here and add support of
+    -- cdata<int64_t> and cdata<uint64_t> to them, we should
+    -- reimplement the duplicate check (different cdata objects
+    -- are different keys in a table even if they represent the
+    -- same number).
+    --
+    -- If we allow 'any' or composite types for an item, we have
+    -- to reimplement the algorithm too and introduce some kind of
+    -- a deep comparison or deep hashing.
+    local visited = {}
+    for _, item in ipairs(data) do
+        -- An array can't have holes (see table_is_array()) and it
+        -- can't contain box.NULL values (only values accepted by
+        -- the given schema node are allowed). It means that only
+        -- string items are possible in our case.
+        --
+        -- That all is checked in validate_impl() before calling
+        -- this function.
+        assert(type(item) == 'string')
+        if visited[item] then
+            walkthrough_error(ctx, 'Values should be unique, but %q appears ' ..
+                'at least twice', item)
+        end
+        visited[item] = true
+    end
+end
+
 -- Call schema node specific validation function.
 local function validate_by_node_function(schema, data, ctx)
     if schema.validate == nil then
@@ -685,6 +724,7 @@ local function validate_impl(schema, data, ctx)
     end
 
     validate_by_allowed_values(schema, data, ctx)
+    validate_unique_items(schema, data, ctx)
 
     -- Call schema node specific validation function.
     --
@@ -708,6 +748,8 @@ end
 -- Annotations taken into accounts:
 --
 -- * allowed_values (table) -- whitelist of values
+-- * unique_items (boolean) -- whether array values should be
+--                             unique
 -- * validate (function) -- schema node specific validator
 --
 --   validate = function(data, w)
@@ -1747,7 +1789,7 @@ local function jsonschema_impl(schema, ctx)
             items = jsonschema_impl(schema.items, ctx),
         }
         walkthrough_leave(ctx)
-        if schema.validate == validate_no_repeat then
+        if schema.unique_items then
             res.uniqueItems = true
         end
         return set_common_jsonschema_fields(res, schema)
@@ -1806,6 +1848,7 @@ local function preprocess_enter(ctx, schema)
     -- context of descendant schema nodes. Don't track them.
     local ignored_annotations = {
         allowed_values = true,
+        unique_items = true,
         validate = true,
         default = true,
         apply_default_if = true,
@@ -1923,6 +1966,63 @@ end
 
 -- }}} Schema preprocessing
 
+-- {{{ Schema validation
+
+-- The unique_items annotation is only applicable to an array of
+-- strings.
+--
+-- We can support other item types in a future, but let's be
+-- conservative on the first step. See validate_unique_items() for
+-- details.
+local function validate_schema_node_unique_items(schema, ctx)
+    if not schema.unique_items then
+        return
+    end
+
+    if schema.type ~= 'array' then
+        walkthrough_error(ctx, '"unique_items" requires an array of ' ..
+            'strings, got a %s', schema.type)
+    end
+
+    if schema.items.type ~= 'string' then
+        walkthrough_error(ctx, '"unique_items" requires an array of ' ..
+            'strings, got an array of %s items', schema.items.type)
+    end
+end
+
+local function validate_schema_impl(schema, ctx)
+    validate_schema_node_unique_items(schema, ctx)
+
+    -- luacheck: ignore 542 empty if branch
+    if is_scalar(schema) then
+        -- Nothing to do.
+    elseif schema.type == 'record' then
+        for field_name, field_def in pairs(schema.fields) do
+            walkthrough_enter(ctx, field_name)
+            validate_schema_impl(field_def, ctx)
+            walkthrough_leave(ctx)
+        end
+    elseif schema.type == 'map' then
+        walkthrough_enter(ctx, '*')
+        validate_schema_impl(schema.key, ctx)
+        validate_schema_impl(schema.value, ctx)
+        walkthrough_leave(ctx)
+    elseif schema.type == 'array' then
+        walkthrough_enter(ctx, '*')
+        validate_schema_impl(schema.items, ctx)
+        walkthrough_leave(ctx)
+    else
+        assert(false)
+    end
+end
+
+local function validate_schema(name, schema)
+    local ctx = {path = {}, name = name}
+    validate_schema_impl(schema, ctx)
+end
+
+-- }}} Schema validation
+
 -- {{{ Schema object constructor: new
 
 -- Define a field lookup function on a schema object.
@@ -2007,6 +2107,8 @@ local function new(name, schema, opts)
     assert(type(name) == 'string')
     assert(type(schema) == 'table')
 
+    validate_schema(name, schema)
+
     local ctx = {
         annotation_stack = {},
     }

test/config-luatest/schema_test.lua

@@ -224,24 +224,6 @@ end
 
 -- }}} Schema node constructors: scalar, record, map, array
 
--- {{{ Testing helpers for derived schema node type constructors
-
-local function mask_functions(data)
-    if type(data) == 'function' then
-        return '<function>'
-    elseif type(data) == 'table' then
-        local res = {}
-        for k, v in pairs(data) do
-            res[k] = mask_functions(v)
-        end
-        return res
-    else
-        return data
-    end
-end
-
--- }}} Testing helpers for derived schema node type constructors
-
 -- {{{ Derived schema node type constructors: enum, set
 
 -- schema.enum() must return a table of the following shape.
@@ -286,30 +268,30 @@ end
 --         type = 'string',
 --         allowed_values = <...>,
 --     }),
---     validate = <...>,
+--     unique_items = true,
 --     <..annotations..>
 -- }
 g.test_set_constructor = function()
     -- A simple good case.
-    t.assert_equals(mask_functions(schema.set({'foo', 'bar'})), {
+    t.assert_equals(schema.set({'foo', 'bar'}), {
         type = 'array',
         items = {
             type = 'string',
             allowed_values = {'foo', 'bar'},
         },
-        validate = '<function>',
+        unique_items = true,
     })
 
     -- A simple good case with an annotation.
-    t.assert_equals(mask_functions(schema.set({'foo', 'bar'}, {
+    t.assert_equals(schema.set({'foo', 'bar'}, {
         my_annotation = 'info',
-    })), {
+    }), {
         type = 'array',
         items = {
             type = 'string',
             allowed_values = {'foo', 'bar'},
         },
-        validate = '<function>',
+        unique_items = true,
         my_annotation = 'info',
     })
 
@@ -320,11 +302,9 @@ g.test_set_constructor = function()
     -- Ignore error messages. They are just 'assertion failed at
     -- line X', purely for the schema creator.
     local scalar = schema.scalar({type = 'string'})
-    local nop = function() end
     local def = {'foo', 'bar'}
     t.assert_equals(pcall(schema.set, def, {type = 'number'}), false)
     t.assert_equals(pcall(schema.set, def, {items = scalar}), false)
-    t.assert_equals(pcall(schema.set, def, {validate = nop}), false)
 end
 
 -- }}} Derived schema node type constructors: enum, set
@@ -528,6 +508,7 @@ end
 -- computed annotations.
 --
 -- * allowed_values
+-- * unique_items
 -- * validate
 -- * default
 -- * apply_default_if
@@ -546,6 +527,53 @@ g.test_computed_annotations_ignore = function()
             my_annotation = 'my annotation',
         },
     })
+
+    -- NB: unique_items is allowed only in an array.
+    local s = schema.new('myschema', schema.array({
+        items = schema.scalar({type = 'string'}),
+        unique_items = true,
+        my_annotation = 'my annotation',
+    }))
+
+    t.assert_equals(s.schema.computed, {
+        annotations = {
+            my_annotation = 'my annotation',
+        },
+    })
+end
+
+-- Verify that the unique_items annotation is only allowed in an
+-- array of strings.
+g.test_validate_schema = function()
+    -- Not an array.
+    local exp_err_msg = '[myschema] foo.bar: "unique_items" requires an ' ..
+        'array of strings, got a string'
+    t.assert_error_msg_equals(exp_err_msg, function()
+        schema.new('myschema', schema.record({
+            foo = schema.record({
+                bar = schema.scalar({
+                    type = 'string',
+                    unique_items = true,
+                }),
+            }),
+        }))
+    end)
+
+    -- Array of non-string values.
+    local exp_err_msg = '[myschema] foo.bar: "unique_items" requires an ' ..
+        'array of strings, got an array of integer items'
+    t.assert_error_msg_equals(exp_err_msg, function()
+        schema.new('myschema', schema.record({
+            foo = schema.record({
+                bar = schema.array({
+                    items = schema.scalar({
+                        type = 'integer',
+                    }),
+                    unique_items = true,
+                }),
+            }),
+        }))
+    end)
 end
 
 -- }}} Schema object constructor: new
@@ -933,6 +961,25 @@ g.test_validate_by_allowed_values = function()
     assert_validate_scalar_type_mismatch(s, 1, 'string')
 end
 
+g.test_validate_unique_items = function()
+    local s = schema.new('myschema', schema.set({'foo', 'bar'}, {
+        validate = function(_data, w)
+            w.error('error from the validate annotation')
+        end,
+    }))
+
+    -- The uniqueness check is performed before the user-provided
+    -- validation function.
+    local exp_err = '[myschema] Values should be unique, but "foo" ' ..
+        'appears at least twice'
+    t.assert_error_msg_equals(exp_err, s.validate, s, {'foo', 'foo'})
+
+    -- The user-provided validation function is taken into
+    -- account.
+    local exp_err = '[myschema] error from the validate annotation'
+    t.assert_error_msg_equals(exp_err, s.validate, s, {'foo'})
+end
+
 g.test_validate_by_node_function = function()
     local schema_saved
     local path_saved