grumlin 0.20.2 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e2a547fb7cbcfe53c2fab5486236b4d1021b8c4fe487307003571b24ea9e04d8
-  data.tar.gz: b1f73d016d9779f63a0d19c2c02afc5b975544a479aa9e9a1f5424edfde2911f
+  metadata.gz: 519d93b97b2cd8f07a1e11e75e45b0b7ca780947e82b3624d5e6c7c6d719ec27
+  data.tar.gz: 5eed9eab9e99fe02246995adbc8c01988bd21d150df234946a575d01cda518f2
 SHA512:
-  metadata.gz: 5e8c6fa1bea702a974a9c0b22ec7c3f914ccceaf7c12f4bc8b5f8ce94eace7edd6dce4e47f318189e3e1b7af8c5e8ace6b00479283823274e3badfe25b6b0b07
-  data.tar.gz: cbb5bbfd192542785f041157232097ed01fe0d1444c20fc7c5606c1873229a7d7577183b8919f475085b5e7bf6700fae6cc987e0024fe6263cfab61f44ce898c
+  metadata.gz: 76cd4990acd94d119b2a716e25b10d35bdc970e794a77de4d25dcc7e3f67f5129236ff1c037a4f0f0c3208643afca9695b6dc602bb84ae01d61a84c1b89364fe
+  data.tar.gz: afda51dc7010f1fc508e96b203727ebee971597b6425aa2ec29932d7957e1b2b12d8959526a5fc10d92e46926e94dab1ca3d62eb583bbb36498f99bbd3e11689

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    grumlin (0.20.2)
+    grumlin (0.22.0)
       async-pool (~> 0.3)
       async-websocket (~> 0.19)
       oj (~> 3.13)
@@ -21,11 +21,11 @@ GEM
       console (~> 1.10)
       nio4r (~> 2.3)
       timers (~> 4.1)
-    async-http (0.56.6)
+    async-http (0.57.0)
       async (>= 1.25)
       async-io (>= 1.28)
       async-pool (>= 0.2)
-      protocol-http (~> 0.22.0)
+      protocol-http (~> 0.23.1)
       protocol-http1 (~> 0.14.0)
       protocol-http2 (~> 0.14.0)
       traces (~> 0.4.0)
@@ -37,7 +37,7 @@ GEM
       rspec (~> 3.0)
       rspec-files (~> 1.0)
       rspec-memory (~> 1.0)
-    async-websocket (0.19.0)
+    async-websocket (0.19.2)
       async-http (~> 0.54)
       async-io (~> 1.23)
       protocol-websocket (~> 0.7.0)
@@ -72,7 +72,7 @@ GEM
       racc (~> 1.4)
     nokogiri (1.13.6-x86_64-linux)
       racc (~> 1.4)
-    oj (3.13.17)
+    oj (3.13.20)
     overcommit (0.59.1)
       childprocess (>= 0.6.3, < 5)
       iniparse (~> 1.4)
@@ -81,7 +81,7 @@ GEM
     parser (3.1.2.0)
       ast (~> 2.4.1)
     protocol-hpack (1.4.2)
-    protocol-http (0.22.6)
+    protocol-http (0.23.1)
     protocol-http1 (0.14.4)
       protocol-http (~> 0.22)
     protocol-http2 (0.14.2)

data/README.md

@@ -46,9 +46,38 @@ Or install it yourself as:
 ```ruby
 Grumlin.configure do |config|
   config.url = "ws://localhost:8182/gremlin"
+
+  # make sure you select right provider for better compatibility
+  config.provider = :tinkergraph
 end
 ```
 
+#### Providers
+
+Currently `Grumlin` supports 2 providers:
+- tinkergraph (default)
+- neptune
+
+As different providers may have or may have not support for specific features it's recommended to
+explicitly specify the provider you use.
+
+#### Provider features
+
+Every provider is described by a set of features. In the future `Grumlin` may decide to disable or enable 
+some parts of it's functionality to comply provider's supported features.
+
+To check current providers supported features use
+
+```ruby
+Grumlin.features
+```
+
+Current differences between providers:
+
+| Feature      | TinkerGraph                                                                                                                                               |AWS Neptune|
+|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|
+| Transactions | Transaction semantic is ignoroed, data is always writen, `tx.rollback` does nothing, an info is printed every time transactions are used with TinkerGraph |Full support
+
 ### Traversing graphs
 
 **Warning**: Not all steps and expressions defined in the reference documentation are supported.
@@ -216,21 +245,32 @@ Each `return_mode` is mapped to a particular termination step:
 - `:traversal` - do not execute the query and return the traversal as is
 
 `Grumlin::Repository` also provides a set of generic CRUD operations:
-- `add_vertex(label, id = nil, **properties)`
-- `add_edge(label, id = nil, from:, to:, **properties)`
-- `drop_vertex(id)`
-- `drop_edge(id = nil, from: nil, to: nil, label: nil)`
+- `add_vertex(label, id = nil, start: g, **properties)`
+- `add_edge(label, id = nil, from:, to:, start: g, **properties)`
+- `drop_vertex(id, start: g)`
+- `drop_edge(id = nil, from: nil, to: nil, label: nil, start: g)`
 
 and a few methods that emulate upserts:
-- `upsert_vertex(label, id, create_properties: {}, update_properties: {}, on_failure: :retry, **params)` 
-- `upsert_edge(label, from:, to:, create_properties: {}, update_properties: {}, on_failure: :retry, **params)`
-- `upsert_edges(edges, batch_size: 100, on_failure: :retry, **params)`
-- `upsert_vertices(edges, batch_size: 100, on_failure: :retry, **params)`
+- `upsert_vertex(label, id, create_properties: {}, update_properties: {}, on_failure: :retry, start: g, **params)` 
+- `upsert_edge(label, from:, to:, create_properties: {}, update_properties: {}, on_failure: :retry, start: g, **params)`
+- `upsert_edges(edges, batch_size: 100, on_failure: :retry, start: g, **params)`
+- `upsert_vertices(edges, batch_size: 100, on_failure: :retry, start: g, **params)`
 
 All of them support 3 different modes for error handling: `:retry`, `:ignore` and `:raise`. Retry mode is implemented
 with [retryable](https://github.com/nfedyashev/retryable). **params will be merged to the default config for upserts 
 and passed to `Retryable.retryable`. In case if you want to modify retryable behaviour you are to do so.
 
+If you want to use these methods inside a transaction simply pass your `gtx` as `start` parameter:
+```ruby
+g.tx do |gtx|
+  add_vertex(:vertex, start: gtx)
+end
+```
+
+If you don't want to define you own repository, simply use
+
+`Grumlin::Repository.new` returns an instance of an anonymous class extending `Grumlin::Repository`. 
+
 **Usage**
 
 To execute the query defined in a query block one simply needs to call a method with the same name:
@@ -254,6 +294,24 @@ it may be useful for debugging. Note that one needs to call a termination step m
 
 method will return profiling data of the results.
 
+#### Transactions
+
+Since 0.22.0 `Grumlin` supports transactions when working with providers that supports them:
+```ruby
+# Using Transaction directly
+tx = g.tx
+gtx = tx.begin
+gtx.addV(:vertex).iterate
+tx.commit # or tx.rollback
+
+# Using with a block
+g.tx do |gtx|
+  gtx.addV(:vertex).iterate
+  # raise Grumlin::Rollback to manually rollback
+  # any other exception will also rollback the transaction and will be reraised 
+end # commits automatically
+```
+
 #### IRB
 
 An example of how to start an IRB session with support for executing gremlin queries:

data/gremlin_server/Dockerfile

@@ -1,4 +1,4 @@
-FROM tinkerpop/gremlin-server
+FROM tinkerpop/gremlin-server:3.5.3
 
 RUN rm -rf /opt/gremlin-server/ext/tinkergraph-gremlin
 

data/grumlin.gemspec

@@ -20,7 +20,7 @@ Gem::Specification.new do |spec|
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = "https://github.com/zhulik/grumlin"
-  spec.metadata["changelog_uri"] = "https://github.com/zhulik/grumlin/blob/master/CHANGELOG.md"
+  spec.metadata["changelog_uri"] = "https://github.com/babbel/grumlin/releases"
   spec.metadata["rubygems_mfa_required"] = "true"
 
   spec.files = Dir.chdir(File.expand_path(__dir__)) do

data/lib/grumlin/action.rb

@@ -4,18 +4,19 @@ module Grumlin
   class Action < Steppable
     attr_reader :name, :args, :params, :next_step, :configuration_steps, :previous_step, :shortcut
 
-    def initialize(name, args: [], params: {}, previous_step: nil, pool: nil)
-      super()
+    # client is only used when a traversal is a part of transaction
+    def initialize(name, args: [], params: {}, previous_step: nil, pool: Grumlin.default_pool, session_id: nil)
+      super(pool: pool, session_id: session_id)
+
       @name = name.to_sym
       @args = args # TODO: add recursive validation: only json types or Action
       @params = params # TODO: add recursive validation: only json types
       @previous_step = previous_step
       @shortcut = shortcuts[@name]
-      @pool = pool || Grumlin.default_pool
     end
 
     def configuration_step?
-      CONFIGURATION_STEPS.include?(@name)
+      CONFIGURATION_STEPS.include?(@name) || name.to_sym == :tx
     end
 
     def start_step?
@@ -73,14 +74,18 @@ module Grumlin
     end
 
     def toList
-      @pool.acquire do |client|
-        client.write(bytecode)
-      end
+      client_write(bytecode)
     end
 
     def iterate
+      client_write(bytecode(no_return: true))
+    end
+
+    private
+
+    def client_write(payload)
       @pool.acquire do |client|
-        client.write(bytecode(no_return: true))
+        client.write(payload, session_id: @session_id)
       end
     end
   end

data/lib/grumlin/client.rb

@@ -24,8 +24,8 @@ module Grumlin
         @client.close
       end
 
-      def write(bytecode)
-        @client.write(bytecode)
+      def write(bytecode, session_id: nil)
+        @client.write(bytecode, session_id: session_id)
       ensure
         @count += 1
       end
@@ -94,14 +94,14 @@ module Grumlin
     end
 
     # TODO: support yielding
-    def write(bytecode)
+    def write(bytecode, session_id: nil)
       raise NotConnectedError unless connected?
 
-      request = to_query(bytecode)
-      channel = @request_dispatcher.add_request(request)
-      @transport.write(request)
+      request = to_query(bytecode, session_id: session_id)
 
+      channel = @request_dispatcher.add_request(request)
       begin
+        @transport.write(request)
         channel.dequeue.flat_map { |item| Typing.cast(item) }
       rescue Async::Stop, Async::TimeoutError
         close(check_requests: false)
@@ -124,15 +124,19 @@ module Grumlin
       Transport.new(@url, parent: @parent, **@client_options)
     end
 
-    def to_query(bytecode)
+    def to_query(bytecode, session_id:)
       {
         requestId: SecureRandom.uuid,
-        op: "bytecode",
-        processor: "traversal",
+        op: :bytecode,
+        processor: session_id ? :session : :traversal,
         args: {
-          gremlin: { :@type => "g:Bytecode", :@value => bytecode.serialize },
-          aliases: { g: :g }
-        }
+          gremlin: {
+            :@type => "g:Bytecode",
+            :@value => bytecode.serialize
+          },
+          aliases: { g: :g },
+          session: session_id
+        }.compact
       }
     end
   end

data/lib/grumlin/config.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Grumlin
+  class Config
+    attr_accessor :url, :pool_size, :client_concurrency, :client_factory, :provider
+
+    SUPPORTED_PROVIDERS = %i[neptune tinkergraph].freeze
+
+    class ConfigurationError < Grumlin::Error; end
+
+    class UnknownProviderError < ConfigurationError; end
+
+    def initialize
+      @pool_size = 10
+      @client_concurrency = 5
+      @provider = :tinkergraph
+      @client_factory = ->(url, parent) { Grumlin::Client.new(url, parent: parent) }
+    end
+
+    def validate!
+      return if SUPPORTED_PROVIDERS.include?(provider.to_sym)
+
+      raise UnknownProviderError, "provider '#{provider}' is unknown. Supported providers: #{SUPPORTED_PROVIDERS}"
+    end
+  end
+end

data/lib/grumlin/dummy_transaction.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Grumlin
+  class DummyTransaction < Transaction
+    attr_reader :uuid
+
+    include Console
+
+    def initialize(traversal_start_class, pool: Grumlin.default_pool) # rubocop:disable Lint/MissingSuper, Lint/UnusedMethodArgument
+      @traversal_start_class = traversal_start_class
+
+      logger.info(self) do
+        "#{Grumlin.config.provider} does not support transactions. commit and rollback are ignored, data will be saved"
+      end
+    end
+
+    def commit
+      nil
+    end
+
+    def rollback
+      nil
+    end
+  end
+end

data/lib/grumlin/features/feature_list.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Grumlin
+  module Features
+    class FeatureList
+      def user_supplied_ids?
+        raise(NotImplementedError) if @user_supplied_ids.nil?
+
+        @user_supplied_ids
+      end
+
+      def supports_transactions?
+        raise(NotImplementedError) if @supports_transactions.nil?
+
+        @supports_transactions
+      end
+    end
+  end
+end

data/lib/grumlin/features/neptune_features.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Grumlin
+  module Features
+    class NeptuneFeatures < FeatureList
+      def initialize
+        super
+        @user_supplied_ids = true
+        @supports_transactions = true
+      end
+    end
+  end
+end

data/lib/grumlin/features/tinkergraph_features.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Grumlin
+  module Features
+    class TinkergraphFeatures < FeatureList
+      def initialize
+        super
+        @user_supplied_ids = true
+        @supports_transactions = false
+      end
+    end
+  end
+end

data/lib/grumlin/features.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Grumlin
+  module Features
+    class << self
+      FEATURES = {
+        neptune: NeptuneFeatures.new,
+        tinkergraph: TinkergraphFeatures.new
+      }.freeze
+
+      def for(provider)
+        FEATURES[provider]
+      end
+    end
+  end
+end

data/lib/grumlin/repository/instance_methods.rb

@@ -8,7 +8,7 @@ module Grumlin
       extend Forwardable
 
       UPSERT_RETRY_PARAMS = {
-        on: [Grumlin::AlreadyExistsError, Grumlin::ConcurrentInsertFailedError],
+        on: [Grumlin::AlreadyExistsError, Grumlin::ConcurrentModificationError],
         sleep_method: ->(n) { Async::Task.current.sleep(n) },
         tries: 3,
         sleep: ->(n) { (n**2) + 1 + rand }
@@ -22,51 +22,51 @@ module Grumlin
         self.class.shortcuts
       end
 
-      def drop_vertex(id)
-        g.V(id).drop.iterate
+      def drop_vertex(id, start: g)
+        start.V(id).drop.iterate
       end
 
-      def drop_edge(id = nil, from: nil, to: nil, label: nil) # rubocop:disable Metrics/AbcSize
+      def drop_edge(id = nil, from: nil, to: nil, label: nil, start: g) # rubocop:disable Metrics/AbcSize
         raise ArgumentError, "either id or from:, to: and label: must be passed" if [id, from, to, label].all?(&:nil?)
-        return g.E(id).drop.iterate unless id.nil?
+        return start.E(id).drop.iterate unless id.nil?
 
         raise ArgumentError, "from:, to: and label: must be passed" if [from, to, label].any?(&:nil?)
 
-        g.V(from).outE(label).where(__.inV.hasId(to)).limit(1).drop.iterate
+        start.V(from).outE(label).where(__.inV.hasId(to)).limit(1).drop.iterate
       end
 
-      def add_vertex(label, id = nil, **properties)
+      def add_vertex(label, id = nil, start: g, **properties)
         id ||= properties[T.id]
         properties = except(properties, T.id)
 
-        t = g.addV(label)
+        t = start.addV(label)
         t = t.props(T.id => id) unless id.nil?
         t.props(**properties).next
       end
 
-      def add_edge(label, id = nil, from:, to:, **properties)
+      def add_edge(label, id = nil, from:, to:, start: g, **properties)
         id ||= properties[T.id]
         properties = except(properties, T.label)
         properties[T.id] = id
 
-        g.addE(label).from(__.V(from)).to(__.V(to)).props(**properties).next
+        start.addE(label).from(__.V(from)).to(__.V(to)).props(**properties).next
       end
 
-      def upsert_vertex(label, id, create_properties: {}, update_properties: {}, on_failure: :retry, **params)
+      def upsert_vertex(label, id, create_properties: {}, update_properties: {}, on_failure: :retry, start: g, **params) # rubocop:disable Metrics/ParameterLists
         with_upsert_error_handling(on_failure, params) do
           create_properties, update_properties = cleanup_properties(create_properties, update_properties)
 
-          g.upsertV(label, id, create_properties, update_properties).id.next
+          start.upsertV(label, id, create_properties, update_properties).id.next
         end
       end
 
       # vertices:
       # [["label", "id", {create: :properties}, {update: properties}]]
       # params can override Retryable config from UPSERT_RETRY_PARAMS
-      def upsert_vertices(vertices, batch_size: 100, on_failure: :retry, **params)
+      def upsert_vertices(vertices, batch_size: 100, on_failure: :retry, start: g, **params)
         vertices.each_slice(batch_size) do |slice|
           with_upsert_error_handling(on_failure, params) do
-            slice.reduce(g) do |t, (label, id, create_properties, update_properties)|
+            slice.reduce(start) do |t, (label, id, create_properties, update_properties)|
               create_properties, update_properties = cleanup_properties(create_properties, update_properties)
 
               t.upsertV(label, id, create_properties, update_properties)
@@ -77,20 +77,21 @@ module Grumlin
 
       # Only from and to are used to find the existing edge, if one wants to assign an id to a created edge,
       # it must be passed as T.id in create_properties.
-      def upsert_edge(label, from:, to:, create_properties: {}, update_properties: {}, on_failure: :retry, **params) # rubocop:disable Metrics/ParameterLists
+      def upsert_edge(label, from:, to:, create_properties: {}, update_properties: {}, # rubocop:disable Metrics/ParameterLists
+                      on_failure: :retry, start: g, **params)
         with_upsert_error_handling(on_failure, params) do
           create_properties, update_properties = cleanup_properties(create_properties, update_properties, T.label)
-          g.upsertE(label, from, to, create_properties, update_properties).id.next
+          start.upsertE(label, from, to, create_properties, update_properties).id.next
         end
       end
 
       # edges:
       # [["label", "from", "to", {create: :properties}, {update: properties}]]
       # params can override Retryable config from UPSERT_RETRY_PARAMS
-      def upsert_edges(edges, batch_size: 100, on_failure: :retry, **params)
+      def upsert_edges(edges, batch_size: 100, on_failure: :retry, start: g, **params)
         edges.each_slice(batch_size) do |slice|
           with_upsert_error_handling(on_failure, params) do
-            slice.reduce(g) do |t, (label, from, to, create_properties, update_properties)|
+            slice.reduce(start) do |t, (label, from, to, create_properties, update_properties)|
               create_properties, update_properties = cleanup_properties(create_properties, update_properties, T.label)
 
               t.upsertE(label, from, to, create_properties, update_properties)

data/lib/grumlin/repository.rb

@@ -10,6 +10,7 @@ module Grumlin
     }.freeze
 
     def self.extended(base)
+      super
       base.extend(Grumlin::Shortcuts)
       base.include(Repository::InstanceMethods)
 
@@ -17,6 +18,12 @@ module Grumlin
       base.shortcuts_from(Grumlin::Shortcuts::Upserts)
     end
 
+    def self.new
+      @repository ||= Class.new do # rubocop:disable Naming/MemoizedInstanceVariableName
+        extend Grumlin::Repository
+      end.new
+    end
+
     def query(name, return_mode: :list, postprocess_with: nil, &query_block) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       return_mode = validate_return_mode!(return_mode)
       postprocess_with = validate_postprocess_with!(postprocess_with)

data/lib/grumlin/request_dispatcher.rb

@@ -10,23 +10,6 @@ module Grumlin
       206 => :partial_content
     }.freeze
 
-    ERRORS = {
-      499 => InvalidRequestArgumentsError,
-      500 => ServerError,
-      597 => ScriptEvaluationError,
-      599 => ServerSerializationError,
-      598 => ServerTimeoutError,
-
-      401 => ClientSideError,
-      407 => ClientSideError,
-      498 => ClientSideError
-    }.freeze
-
-    VERTEX_ALREADY_EXISTS = "Vertex with id already exists:"
-    EDGE_ALREADY_EXISTS = "Edge with id already exists:"
-    CONCURRENT_VERTEX_INSERT_FAILED = "Failed to complete Insert operation for a Vertex due to conflicting concurrent"
-    CONCURRENT_EDGE_INSERT_FAILED = "Failed to complete Insert operation for an Edge due to conflicting concurrent"
-
     class DispatcherError < Grumlin::Error; end
 
     class RequestAlreadyAddedError < DispatcherError; end
@@ -47,14 +30,16 @@ module Grumlin
 
     # builds a response object, when it's ready sends it to the client via a channel
     # TODO: sometimes response does not include requestID, no idea how to handle it so far.
-    def add_response(response) # rubocop:disable Metrics/AbcSize
+    def add_response(response) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       request_id = response[:requestId]
       raise UnknownRequestError unless ongoing_request?(request_id)
 
       begin
         request = @requests[request_id]
 
-        check_errors!(response[:status], request[:request])
+        RequestErrorFactory.build(request, response).tap do |err|
+          raise err unless err.nil?
+        end
 
         case SUCCESS[response.dig(:status, :code)]
         when :success
@@ -91,29 +76,5 @@ module Grumlin
       request = @requests.delete(request_id)
       request[:channel].close
     end
-
-    def check_errors!(status, query)
-      if (error = ERRORS[status[:code]])
-        raise (
-          already_exists_error(status) ||
-          concurrent_insert_error(status) ||
-          error
-        ).new(status, query)
-      end
-
-      return unless SUCCESS[status[:code]].nil?
-
-      raise(UnknownResponseStatus, status)
-    end
-
-    def already_exists_error(status)
-      return VertexAlreadyExistsError if status[:message]&.include?(VERTEX_ALREADY_EXISTS)
-      return EdgeAlreadyExistsError if status[:message]&.include?(EDGE_ALREADY_EXISTS)
-    end
-
-    def concurrent_insert_error(status)
-      return ConcurrentVertexInsertFailedError if status[:message]&.include?(CONCURRENT_VERTEX_INSERT_FAILED)
-      return ConcurrentEdgeInsertFailedError if status[:message]&.include?(CONCURRENT_EDGE_INSERT_FAILED)
-    end
   end
 end

data/lib/grumlin/request_error_factory.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Grumlin
+  class RequestErrorFactory
+    ERRORS = {
+      499 => InvalidRequestArgumentsError,
+      500 => ServerError,
+      597 => ScriptEvaluationError,
+      599 => ServerSerializationError,
+      598 => ServerTimeoutError,
+
+      401 => ClientSideError,
+      407 => ClientSideError,
+      498 => ClientSideError
+    }.freeze
+
+    # Neptune presumably returns message as a JSON string of format
+    # {"detailedMessage":"",
+    #  "requestId":"UUID",
+    #  "code":"ConcurrentModificationException"}
+    # Currencly we simply search for substings to identify the exact error
+    # TODO: parse json and use `code` instead
+    VERTEX_ALREADY_EXISTS = "Vertex with id already exists:"
+    EDGE_ALREADY_EXISTS = "Edge with id already exists:"
+    CONCURRENT_VERTEX_INSERT_FAILED = "Failed to complete Insert operation for a Vertex due to conflicting concurrent"
+    CONCURRENT_EDGE_INSERT_FAILED = "Failed to complete Insert operation for an Edge due to conflicting concurrent"
+    CONCURRENCT_MODIFICATION_FAILED = "Failed to complete operation due to conflicting concurrent"
+
+    class << self
+      def build(request, response)
+        status = response[:status]
+        query = request[:request]
+
+        if (error = ERRORS[status[:code]])
+          return (
+            already_exists_error(status) ||
+            concurrent_modification_error(status) ||
+            error
+          ).new(status, query)
+        end
+
+        return unless RequestDispatcher::SUCCESS[status[:code]].nil?
+
+        UnknownResponseStatus.new(status)
+      end
+
+      def already_exists_error(status)
+        return VertexAlreadyExistsError if status[:message]&.include?(VERTEX_ALREADY_EXISTS)
+        return EdgeAlreadyExistsError if status[:message]&.include?(EDGE_ALREADY_EXISTS)
+      end
+
+      def concurrent_modification_error(status)
+        return ConcurrentVertexInsertFailedError if status[:message]&.include?(CONCURRENT_VERTEX_INSERT_FAILED)
+        return ConcurrentEdgeInsertFailedError if status[:message]&.include?(CONCURRENT_EDGE_INSERT_FAILED)
+        return ConcurrentModificationError if status[:message]&.include?(CONCURRENCT_MODIFICATION_FAILED)
+      end
+    end
+  end
+end

data/lib/grumlin/shortcuts/properties.rb

@@ -5,11 +5,12 @@ module Grumlin
     module Properties
       extend Grumlin::Shortcuts
 
-      shortcut :props do |**props|
-        props.reduce(self) do |tt, (prop, value)| # rubocop:disable Style/EachWithObject
-          next tt.property(prop, value) unless value.nil? # nils are not supported
+      shortcut :props do |cardinality = nil, **props|
+        props.reduce(self) do |tt, (prop, value)|
+          next tt if value.nil? # nils are not supported
+          next tt.property(prop, value) if cardinality.nil?
 
-          tt
+          tt.property(cardinality, prop, value)
         end
       end
 

data/lib/grumlin/shortcuts/upserts.rb

@@ -10,8 +10,8 @@ module Grumlin
             .fold
             .coalesce(
               __.unfold,
-              __.addV(label).props(**create_properties.merge(T.id => id))
-            ).props(**update_properties)
+              __.addV(label).props(Cardinality.single, **create_properties.merge(T.id => id))
+            ).props(Cardinality.single, **update_properties)
       end
 
       shortcut :upsertE do |label, from, to, create_properties = {}, update_properties = {}|

data/lib/grumlin/steppable.rb

@@ -4,13 +4,18 @@ module Grumlin
   class Steppable
     extend Forwardable
 
+    attr_reader :session_id
+
     START_STEPS = Grumlin.definitions.dig(:steps, :start).map(&:to_sym).freeze
     REGULAR_STEPS = Grumlin.definitions.dig(:steps, :regular).map(&:to_sym).freeze
     CONFIGURATION_STEPS = Grumlin.definitions.dig(:steps, :configuration).map(&:to_sym).freeze
 
     ALL_STEPS = START_STEPS + CONFIGURATION_STEPS + REGULAR_STEPS
 
-    def initialize
+    def initialize(pool: Grumlin.default_pool, session_id: nil)
+      @pool = pool
+      @session_id = session_id
+
       return if respond_to?(:shortcuts)
 
       raise "steppable must not be initialized directly, use Grumlin::Shortcuts::Storage#g or #__ instead"
@@ -18,12 +23,12 @@ module Grumlin
 
     ALL_STEPS.each do |step|
       define_method step do |*args, **params|
-        shortcuts.action_class.new(step, args: args, params: params, previous_step: self)
+        shortcuts.action_class.new(step, args: args, params: params, previous_step: self, session_id: @session_id)
       end
     end
 
     def step(name, *args, **params)
-      shortcuts.action_class.new(name, args: args, params: params, previous_step: self)
+      shortcuts.action_class.new(name, args: args, params: params, previous_step: self, session_id: @session_id)
     end
 
     def_delegator :shortcuts, :__

data/lib/grumlin/steps.rb

@@ -32,7 +32,9 @@ module Grumlin
     end
 
     def add(name, args: [], params: {})
-      return add_configuration_step(name, args: args, params: params) if CONFIGURATION_STEPS.include?(name)
+      if CONFIGURATION_STEPS.include?(name) || name.to_sym == :tx
+        return add_configuration_step(name, args: args, params: params)
+      end
 
       StepData.new(name, args: cast_arguments(args), params: params).tap do |step|
         @steps << step

data/lib/grumlin/steps_serializers/bytecode.rb

@@ -10,17 +10,19 @@ module Grumlin
 
       def serialize
         steps = ShortcutsApplyer.call(@steps)
-        no_return = @params[:no_return] || false
-
-        {
-          step: (steps.steps + (no_return ? [NONE_STEP] : [])).map { |s| serialize_step(s) }
-        }.tap do |v|
-          v.merge!(source: steps.configuration_steps.map { |s| serialize_step(s) }) if steps.configuration_steps.any?
+        no_return = @params.fetch(:no_return, false)
+        {}.tap do |result|
+          result[:step] = serialize_steps(steps.steps + (no_return ? [NONE_STEP] : [])) if steps.steps.any?
+          result[:source] = serialize_steps(steps.configuration_steps) if steps.configuration_steps.any?
         end
       end
 
       private
 
+      def serialize_steps(steps)
+        steps.map { |s| serialize_step(s) }
+      end
+
       def serialize_step(step)
         [step.name].tap do |result|
           step.args.each do |arg|

data/lib/grumlin/transaction.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Grumlin
+  class Transaction
+    attr_reader :session_id
+
+    include Console
+
+    COMMIT = Grumlin::Repository.new.g.step(:tx, :commit).bytecode
+    ROLLBACK = Grumlin::Repository.new.g.step(:tx, :rollback).bytecode
+
+    def initialize(traversal_start_class, pool: Grumlin.default_pool)
+      @traversal_start_class = traversal_start_class
+      @pool = pool
+
+      @session_id = SecureRandom.uuid
+    end
+
+    def begin
+      @traversal_start_class.new(session_id: @session_id)
+    end
+
+    def commit
+      finalize(COMMIT)
+    end
+
+    def rollback
+      finalize(ROLLBACK)
+    end
+
+    private
+
+    def finalize(action)
+      @pool.acquire do |client|
+        client.write(action, session_id: @session_id)
+      end
+    end
+  end
+end

data/lib/grumlin/traversal_start.rb

@@ -4,6 +4,27 @@ module Grumlin
   class TraversalStart < Steppable
     include WithExtension
 
+    class TraversalError < Grumlin::Error; end
+    class AlreadyBoundToTransactionError < TraversalError; end
+
+    def tx
+      raise AlreadyBoundToTransactionError if @session_id
+
+      transaction = tx_class.new(self.class, pool: @pool)
+      return transaction unless block_given?
+
+      begin
+        yield transaction.begin
+      rescue Grumlin::Rollback
+        transaction.rollback
+      rescue StandardError
+        transaction.rollback
+        raise
+      else
+        transaction.commit
+      end
+    end
+
     def to_s(*)
       self.class.to_s
     end
@@ -11,5 +32,11 @@ module Grumlin
     def inspect
       self.class.inspect
     end
+
+    private
+
+    def tx_class
+      Grumlin.features.supports_transactions? ? Transaction : DummyTransaction
+    end
   end
 end

data/lib/grumlin/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Grumlin
-  VERSION = "0.20.2"
+  VERSION = "0.22.0"
 end

data/lib/grumlin.rb

@@ -33,6 +33,9 @@ loader.do_not_eager_load(test_helpers)
 module Grumlin
   class Error < StandardError; end
 
+  class TransactionError < Error; end
+  class Rollback < TransactionError; end
+
   class UnknownError < Error; end
 
   class ConnectionError < Error; end
@@ -98,7 +101,8 @@ module Grumlin
   class VertexAlreadyExistsError < AlreadyExistsError; end
   class EdgeAlreadyExistsError < AlreadyExistsError; end
 
-  class ConcurrentInsertFailedError < ServerError; end
+  class ConcurrentModificationError < ServerError; end
+  class ConcurrentInsertFailedError < ConcurrentModificationError; end
 
   class ConcurrentVertexInsertFailedError < ConcurrentInsertFailedError; end
   class ConcurrentEdgeInsertFailedError < ConcurrentInsertFailedError; end
@@ -127,27 +131,26 @@ module Grumlin
 
   class WrongQueryResult < RepositoryError; end
 
-  class Config
-    attr_accessor :url, :pool_size, :client_concurrency, :client_factory
-
-    def initialize
-      @pool_size = 10
-      @client_concurrency = 5
-      @client_factory = ->(url, parent) { Grumlin::Client.new(url, parent: parent) }
-    end
-  end
-
   @pool_mutex = Mutex.new
 
   class << self
     def configure
       yield config
+
+      config.validate!
     end
 
     def config
       @config ||= Config.new
     end
 
+    # returns a subset of features for currently configured backend.
+    # The features lists are hardcoded as there is no way to get them
+    # from the remote server.
+    def features
+      Features.for(config.provider) # no memoization as provider may be changed
+    end
+
     def default_pool
       if Thread.current.thread_variable_get(:grumlin_default_pool)
         return Thread.current.thread_variable_get(:grumlin_default_pool)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: grumlin
 version: !ruby/object:Gem::Version
-  version: 0.20.2
+  version: 0.22.0
 platform: ruby
 authors:
 - Gleb Sinyavskiy
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-07-22 00:00:00.000000000 Z
+date: 2022-08-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async-pool
@@ -96,7 +96,6 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".tool-versions"
-- CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
 - Gemfile.lock
@@ -117,6 +116,8 @@ files:
 - lib/grumlin/action.rb
 - lib/grumlin/benchmark/repository.rb
 - lib/grumlin/client.rb
+- lib/grumlin/config.rb
+- lib/grumlin/dummy_transaction.rb
 - lib/grumlin/edge.rb
 - lib/grumlin/expressions/cardinality.rb
 - lib/grumlin/expressions/column.rb
@@ -129,12 +130,17 @@ files:
 - lib/grumlin/expressions/t.rb
 - lib/grumlin/expressions/text_p.rb
 - lib/grumlin/expressions/with_options.rb
+- lib/grumlin/features.rb
+- lib/grumlin/features/feature_list.rb
+- lib/grumlin/features/neptune_features.rb
+- lib/grumlin/features/tinkergraph_features.rb
 - lib/grumlin/path.rb
 - lib/grumlin/property.rb
 - lib/grumlin/repository.rb
 - lib/grumlin/repository/error_handling_strategy.rb
 - lib/grumlin/repository/instance_methods.rb
 - lib/grumlin/request_dispatcher.rb
+- lib/grumlin/request_error_factory.rb
 - lib/grumlin/shortcut.rb
 - lib/grumlin/shortcuts.rb
 - lib/grumlin/shortcuts/properties.rb
@@ -152,6 +158,7 @@ files:
 - lib/grumlin/test/rspec.rb
 - lib/grumlin/test/rspec/db_cleaner_context.rb
 - lib/grumlin/test/rspec/gremlin_context.rb
+- lib/grumlin/transaction.rb
 - lib/grumlin/transport.rb
 - lib/grumlin/traversal_start.rb
 - lib/grumlin/traversal_strategies/options_strategy.rb
@@ -168,7 +175,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/zhulik/grumlin
   source_code_uri: https://github.com/zhulik/grumlin
-  changelog_uri: https://github.com/zhulik/grumlin/blob/master/CHANGELOG.md
+  changelog_uri: https://github.com/babbel/grumlin/releases
   rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []

data/CHANGELOG.md

@@ -1,71 +0,0 @@
-## [0.16.0] - 2022-03-11
-
-- Query building is rewritten from scratch. No public APIs were changed. [Details](https://github.com/babbel/grumlin/pull/64)
-- Add support for [TextP](https://tinkerpop.apache.org/javadocs/current/core/org/apache/tinkerpop/gremlin/process/traversal/TextP.html)
-
-## [0.15.4] - 2022-01-20
-
-- Move step and expression definitions to a yaml file for better diffs
-- Add `definitions:format` rake task
-
-## [0.15.3] - 2022-01-18
-
-- Fix passing nils as step arguments. Even if they are not supported by the server, they should not be omitted.
-
-## [0.15.2] - 2022-01-17
-
-- New steps: `map` and `identity`
-
-## [0.15.1] - 2022-01-17
-
-- Fix passing arrays as step arguments
-
-## [0.15.0] - 2022-01-11
-
-- Add `properties` step
-- Add proper support for bulked results
-- Add support for `Property` objects
-
-## [0.14.5] - 2021-12-27
-
-- Fix params handling
-- Add `aggregate` step
-- Add `Order.shuffle`
-
-## [0.14.4] - 2021-12-17
-
-- `Grumlin::Repository.shorcuts_from` do not raise `ArgumentError` when importing an already existing shortcut
-  pointing to the same block. This fixes importing shortcuts from another repository.
-
-## [0.14.2] - 2021-12-13
-
-- Fix `Module` bloating
-- Add `Operator` expressions
-- Add `__.coalesce` and `__.constant`
-- Add steps: `sum`, `sack`
-- Add configuration steps: `withSack`
-- Rename `Grumlin::Expressions::Tool` to `Grumlin::Expressions::Expression`
-
-
-## [0.14.2] - 2021-12-12
-
-- Better exceptions
-- Add `choose` step
-- Add `__.hasNot`, `__.is`, `__.select`
-
-## [0.14.0] - 2021-12-07
-
-- Add initial support for [configuration steps](https://tinkerpop.apache.org/docs/current/reference/#configuration-steps)
-- Add the `withSideEffect` configuration step
-- Fix passing keyword arguments to regular steps
-- *Drop support for ruby 2.6*
-
-## [0.13.0] - 2021-12-03
-
-- Add `Shortcuts` and `Repository`
-- Allow executing any gremlin steps by name using `Grumlin::AnonymousStep#step`
-- Rename `Grumlin::Tools` to `Grumlin::Expressions`
-
-## [0.1.0] - 2021-05-25
-
-- Initial release