Add support for avro-schema unions

(including unions with arrays, maps and
records), closes #109

Author: SudoBobo

README.md

@@ -107,7 +107,8 @@ make test
   * python 2.7,
   * virtualenv,
   * luacheck,
-  * >=tarantool/shard-1.1-92-gec1a27e (but < 2.0).
+  * >=tarantool/shard-1.1-92-gec1a27e (but < 2.0),
+  * >=tarantool/avro-schema-2.2.2-4-g1145e3e.
 * For building apidoc (additionally to 'for use'):
   * ldoc.
 

graphql/core/schema.lua

@@ -50,6 +50,12 @@ function schema:generateTypeMap(node)
   node.fields = type(node.fields) == 'function' and node.fields() or node.fields
   self.typeMap[node.name] = node
 
+  if node.__type == 'Union' then
+    for _, type in ipairs(node.types) do
+      self:generateTypeMap(type)
+    end
+  end
+
   if node.__type == 'Object' and node.interfaces then
     for _, interface in ipairs(node.interfaces) do
       self:generateTypeMap(interface)

graphql/tarantool_graphql.lua

@@ -86,6 +86,8 @@ local function avro_type(avro_schema)
             return 'string'
         elseif avro_schema == 'string*' then
             return 'string*'
+        elseif avro_schema == 'null' then
+            return 'null'
         end
     end
     error('unrecognized avro-schema type: ' .. json.encode(avro_schema))
@@ -252,8 +254,10 @@ local function convert_record_fields_to_args(fields, opts)
         if not skip_compound or (
                 avro_t ~= 'record' and avro_t ~= 'record*' and
                 avro_t ~= 'array' and avro_t ~= 'array*' and
-                avro_t ~= 'map' and avro_t ~= 'map*') then
-            local gql_class = gql_argument_type(field.type)
+                avro_t ~= 'map' and avro_t ~= 'map*' and
+                avro_t ~= 'union') then
+
+            local gql_class = gql_argument_type(field.type, field.name)
             args[field.name] = nullable(gql_class)
         end
     end
@@ -277,7 +281,7 @@ local function convert_record_fields(state, fields)
 
         res[field.name] = {
             name = field.name,
-            kind = gql_type(state, field.type),
+            kind = gql_type(state, field.type, nil, nil, field.name),
         }
     end
     return res
@@ -670,14 +674,175 @@ local convert_connection_to_field = function(state, connection, collection_name)
     end
 end
 
+--- The function 'boxes' given GraphQL type into GraphQL Object 'box' type.
+--- This serves two needs:
+--- 1) GraphQL Union types may contain only GraphQL Objects. GraphQL Scalar
+--- types may be put inside Union only if they are 'boxed' inside an Object.
+--- 2) GraphQL Union types must have specific form, described in @{create_gql_union}.
+--- 'Boxes' is a part of this specific form.
+---
+--- @tparam table gql_type GraphQL type to be boxed
+--- @tparam string avro_name type (or name, in record case) of avro-schema which
+--- was used to create `gql_type`. `avro_name` is used to provide avro-valid names
+--- for fields of boxed types
+--- @treturn table GraphQL Object. Object name is type of initial GraphQL + '_box'.
+--- Resulting Object has only one field. Field type is initial GraphQL type.
+--- Field name is `avro_name`. Such name is necessary to make GraphQL response
+--- avro-valid. 'Avro-valid' means the following: on every incoming GraphQL query
+--- avro-schema is created (a subset of initial avro-schema, used to configurate
+--- tarantool graphql). An 'Avro-valid' is about being valid from point of view of
+--- this subset avro-schema, generated for incoming query.
+--- Consider the following example of resulting GraphQL Object:
+--- String
+--- to
+--- String_box {
+---     string
+--- }
+local function box_type(gql_type, avro_name)
+    check(gql_type, 'gql_type', 'table')
+
+    local gql_true_type = nullable(gql_type)
+
+    local box_name = gql_true_type.name or gql_true_type.__type
+    box_name = box_name .. '_box'
+
+    local box_fields = {[avro_name] = {name = avro_name, kind = gql_type}}
+
+    return types.object({
+        name = box_name,
+        description = 'Box (wrapper) around union variant',
+        fields = box_fields,
+    })
+end
+
+--- The functions creates table of GraphQL types from avro-schema union type.
+local function create_union_types(avro_schema, state)
+    check(avro_schema, 'avro_schema', 'table')
+    assert(utils.is_array(avro_schema), 'union avro-schema must be an array ' ..
+        ', got\n' .. yaml.encode(avro_schema))
+
+    local union_types = {}
+    local determinant_to_type = {}
+    local is_nullable = false
+
+    for _, type in ipairs(avro_schema) do
+        -- If there is a 'null' type among 'union' types (in avro-schema union)
+        -- then resulting GraphQL Union type will be nullable
+        if type == 'null' then
+            is_nullable = true
+        else
+            local variant_type = gql_type(state, type)
+            local box_field_name = type.name or avro_type(type)
+            union_types[#union_types + 1] = box_type(variant_type, box_field_name)
+            local determinant = type.name or type.type or type
+            determinant_to_type[determinant] = union_types[#union_types]
+        end
+    end
+
+    return union_types, determinant_to_type, is_nullable
+end
+
+--- The function creates GraphQL Union type from given avro-schema union type.
+--- GraphQL responses, received from tarantool graphql instance should be
+--- successfully validated with initial avro-schema (which was used to configure
+--- this tarantool graphql instance), so GraphQL Union types must have specific
+--- format to be avro-valid. See example in @treturn for details.
+---
+--- @tparam table state
+--- @tparam table avro_schema avro-schema union type
+--- @tparam string union_name name for resulting GraphQL Union type
+--- @treturn table GraphQL Union type. Consider the following example:
+--- Avro-schema (inside a record):
+--- ...
+--- "name": "MyUnion", "type": [
+---     "null",
+---     "string",
+---     { "type": "record", "name": "Foo", "fields":[
+---         { "name": "foo1", "type": "string" },
+---         { "name": "foo2", "type": "string" }
+---     ]}
+--- ]
+--- ...
+--- GraphQL Union type (It will be nullable as avro-schema has 'null' variant):
+--- MyUnion {
+---     ... on String_box {
+---         string
+---     }
+---
+---     ... on Foo_box {
+---         Foo {
+---             foo1
+---             foo2
+---         }
+--- }
+local function create_gql_union(state, avro_schema, union_name)
+    check(avro_schema, 'avro_schema', 'table')
+    assert(utils.is_array(avro_schema), 'union avro-schema must be an array, ' ..
+        ' got ' .. yaml.encode(avro_schema))
+
+    -- check avro-schema constraints
+    for i, type in ipairs(avro_schema) do
+        assert(avro_type(type) ~= 'union', 'unions must not immediately ' ..
+            'contain other unions')
+
+        if type.name ~= nil then
+            for j, another_type in ipairs(avro_schema) do
+                if i ~= j then
+                    assert(type.name ~= another_type.name,
+                        'Unions may not contain more than one schema with ' ..
+                            'the same name')
+                end
+            end
+        else
+            for j, another_type in ipairs(avro_schema) do
+                if i ~= j then
+                    assert(avro_type(type) ~= avro_type(another_type),
+                        'Unions may not contain more than one schema with ' ..
+                            'the same type except for the named types: ' ..
+                            'record, fixed and enum')
+                end
+            end
+        end
+    end
+
+    -- create GraphQL union
+    local union_types, determinant_to_type, is_nullable =
+        create_union_types(avro_schema, state)
+
+    local union_type = types.union({
+        types = union_types,
+        name = union_name,
+        resolveType = function(result)
+            for determinant, type in pairs(determinant_to_type) do
+                if result[determinant] ~= nil then
+                    return type
+                end
+            end
+            error(('result object has no determinant field matching ' ..
+                'determinants for this union\nresult object:\n%sdeterminants:\n%s')
+                    :format(yaml.encode(result),
+                yaml.encode(determinant_to_type)))
+        end
+    })
+
+    if not is_nullable then
+        union_type = types.nonNull(union_type)
+    end
+
+    return union_type
+end
+
 --- The function converts passed avro-schema to a GraphQL type.
 ---
 --- @tparam table state for read state.accessor and previously filled
 --- state.nullable_collection_types (those are gql types)
 --- @tparam table avro_schema input avro-schema
 --- @tparam[opt] table collection table with schema_name, connections fields
 --- described a collection (e.g. tarantool's spaces)
----
+--- @tparam[opt] string collection_name name of `collection`
+--- @tparam[opt] string field_name it is only for an union generation,
+--- because avro-schema union has no name in it and specific name is necessary
+--- for GraphQL union
 --- If collection is passed, two things are changed within this function:
 ---
 --- 1. Connections from the collection will be taken into account to
@@ -688,7 +853,7 @@ end
 --- XXX As it is not clear now what to do with complex types inside arrays
 --- (just pass to results or allow to use filters), only scalar arrays
 --- is allowed for now. Note: map is considered scalar.
-gql_type = function(state, avro_schema, collection, collection_name)
+gql_type = function(state, avro_schema, collection, collection_name, field_name)
     assert(type(state) == 'table',
         'state must be a table, got ' .. type(state))
     assert(avro_schema ~= nil,
@@ -763,6 +928,8 @@ gql_type = function(state, avro_schema, collection, collection_name)
 
         local gql_map = types_map
         return avro_t == 'map' and types.nonNull(gql_map) or gql_map
+    elseif avro_t == 'union' then
+        return create_gql_union(state, avro_schema, field_name)
     else
         local res = convert_scalar_type(avro_schema, {raise = false})
         if res == nil then

graphql/utils.lua

@@ -204,4 +204,13 @@ function utils.table_size(t)
     return count
 end
 
+function utils.value_in(value, array)
+    for _, v in ipairs(array) do
+        if value == v then
+            return true
+        end
+    end
+    return false
+end
+
 return utils

test/local/avro_union.result

@@ -0,0 +1,82 @@
+RESULT
+---
+user_collection:
+- user_id: user_id_0
+  name: Nobody
+- user_id: user_id_1
+  name: Zlata
+  stuff:
+    string: Some string
+- user_id: user_id_2
+  name: Ivan
+  stuff:
+    int: 123
+- user_id: user_id_3
+  name: Jane
+  stuff:
+    map: {'salary': 333, 'deposit': 444}
+- user_id: user_id_4
+  name: Dan
+  stuff:
+    Foo:
+      foo1: foo1 string
+      foo2: foo2 string
+- user_id: user_id_5
+  name: Max
+  stuff:
+    array:
+    - {'salary': 'salary string', 'deposit': 'deposit string'}
+    - {'salary': 'string salary', 'deposit': 'string deposit'}
+...
+
+Validating results with initial avro-schema
+true
+---
+user_id: user_id_0
+name: Nobody
+...
+
+true
+---
+user_id: user_id_1
+name: Zlata
+stuff:
+  string: Some string
+...
+
+true
+---
+user_id: user_id_2
+name: Ivan
+stuff:
+  int: 123
+...
+
+true
+---
+user_id: user_id_3
+name: Jane
+stuff:
+  map: {'salary': 333, 'deposit': 444}
+...
+
+true
+---
+user_id: user_id_4
+name: Dan
+stuff:
+  Foo:
+    foo1: foo1 string
+    foo2: foo2 string
+...
+
+true
+---
+user_id: user_id_5
+name: Max
+stuff:
+  array:
+  - {'salary': 'salary string', 'deposit': 'deposit string'}
+  - {'salary': 'string salary', 'deposit': 'string deposit'}
+...
+