boltless 1.0.0

data/lib/boltless/transaction.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+module Boltless
+  # A single neo4j transaction representation.
+  #
+  # When passing Cypher statements you can tweak some HTTP API result options
+  # while passing the following keys to the Cypher parameters (they wont be
+  # sent to neo4j):
+  #
+  #   * +with_stats: true|false+: whenever to include statement
+  #     statistics, or not (see: https://bit.ly/3SKXfC8)
+  #   * +result_as_graph: true|false+: whenever to return the result as a graph
+  #     structure that can be visualized (see: https://bit.ly/3doJw3Z)
+  #
+  # Error handling details (see: https://bit.ly/3pdqTCy):
+  #
+  # > If there is an error in a request, the server will roll back the
+  # > transaction. You can tell if the transaction is still open by inspecting
+  # > the response for the presence/absence of the transaction key.
+  class Transaction
+    # We allow to read some internal configurations
+    attr_reader :access_mode, :id, :raw_state
+
+    # We allow to access helpful utilities straigth from here
+    delegate :build_cypher, :prepare_label, :prepare_type, :prepare_string,
+             :to_options, :resolve_cypher,
+             to: Boltless
+
+    # Setup a new neo4j transaction management instance.
+    #
+    # @param connection [HTTP::Client] a ready to use persistent
+    #   connection object
+    # @param database [String, Symbol] the neo4j database to use
+    # @param access_mode [String, Symbol] the neo4j
+    #   transaction mode (+:read+, or +:write+)
+    # @param raw_results [Boolean] whenever to return the plain HTTP API JSON
+    #  results (as plain +Hash{Symbol => Mixed}/Array+ data), or not (then we
+    #  return +Array<Boltless::Result>+ structs
+    def initialize(connection, database: Boltless.configuration.default_db,
+                   access_mode: :write, raw_results: false)
+      @request = Request.new(connection, access_mode: access_mode,
+                                         database: database,
+                                         raw_results: raw_results)
+      @access_mode = access_mode
+      @raw_state = :not_yet_started
+    end
+
+    # Return the transaction state as +ActiveSupport::StringInquirer+
+    # for convenience.
+    #
+    # @return [ActiveSupport::StringInquirer] the transaction state
+    def state
+      ActiveSupport::StringInquirer.new(@raw_state.to_s)
+    end
+
+    # Begin a new transaction. No exceptions will be rescued.
+    #
+    # @return [TrueClass] when the transaction was successfully started
+    #
+    # @raise [Errors::RequestError] when an error occurs, see request object
+    #   for fine-grained details
+    def begin!
+      # We do not allow messing around in wrong states
+      unless @raw_state == :not_yet_started
+        raise Errors::TransactionInBadStateError,
+              "Transaction already #{@raw_state}"
+      end
+
+      @id = @request.begin_transaction
+      @raw_state = :open
+      true
+    end
+
+    # Begin a new transaction. We rescue all errors transparently.
+    #
+    # @return [Boolean] whenever the transaction was successfully started,
+    #   or not
+    def begin
+      handle_errors(false) { begin! }
+    end
+
+    # Run a single Cypher statement inside the transaction. This results
+    # in a single HTTP API request for the statement.
+    #
+    # @param cypher [String] the Cypher statement to run
+    # @param args [Hash{Symbol => Mixed}] the additional Cypher parameters
+    # @return [Hash{Symbol => Mixed}] the raw neo4j results
+    #
+    # @raise [Errors::RequestError] when an error occurs, see request object
+    #   for fine-grained details
+    def run!(cypher, **args)
+      # We do not allow messing around in wrong states
+      raise Errors::TransactionInBadStateError, 'Transaction not open' \
+        unless @raw_state == :open
+
+      @request.run_query(@id, Request.statement_payload(cypher, **args)).first
+    end
+
+    # Run a single Cypher statement inside the transaction. This results in a
+    # single HTTP API request for the statement. We rescue all errors
+    # transparently.
+    #
+    # @param cypher [String] the Cypher statement to run
+    # @param args [Hash{Symbol => Mixed}] the additional Cypher parameters
+    # @return [Array<Hash{Symbol => Mixed}>, nil] the raw neo4j results,
+    #   or +nil+ in case of errors
+    def run(cypher, **args)
+      handle_errors { run!(cypher, **args) }
+    end
+
+    # Run a multiple Cypher statement inside the transaction. This results
+    # in a single HTTP API request for all the statements.
+    #
+    # @param statements [Array<Hash>] the Cypher statements to run
+    # @return [Array<Hash{Symbol => Mixed}>] the raw neo4j results
+    #
+    # @raise [Errors::RequestError] when an error occurs, see request object
+    #   for fine-grained details
+    def run_in_batch!(*statements)
+      # We do not allow messing around in wrong states
+      raise Errors::TransactionInBadStateError, 'Transaction not open' \
+        unless @raw_state == :open
+
+      @request.run_query(@id, *Request.statement_payloads(*statements))
+    end
+
+    # Run a multiple Cypher statement inside the transaction. This results
+    # in a single HTTP API request for all the statements. We rescue all errors
+    # transparently.
+    #
+    # @param statements [Array<Hash>] the Cypher statements to run
+    # @return [Array<Hash{Symbol => Mixed}>, nil] the raw neo4j results,
+    #   or +nil+ in case of errors
+    #
+    # @raise [Errors::RequestError] when an error occurs, see request object
+    #   for fine-grained details
+    def run_in_batch(*statements)
+      handle_errors { run_in_batch!(*statements) }
+    end
+
+    # Commit the transaction, while also sending finalizing Cypher
+    # statement(s). This results in a single HTTP API request for all the
+    # statement(s). You can also omit the statement(s) in order to just commit
+    # the transaction.
+    #
+    # @param statements [Array<Hash>] the Cypher statements to run
+    # @return [Array<Hash{Symbol => Mixed}>] the raw neo4j results
+    #
+    # @raise [Errors::RequestError] when an error occurs, see request object
+    #   for fine-grained details
+    def commit!(*statements)
+      # We do not allow messing around in wrong states
+      raise Errors::TransactionInBadStateError, 'Transaction not open' \
+        unless @raw_state == :open
+
+      @request.commit_transaction(
+        @id,
+        *Request.statement_payloads(*statements)
+      ).tap { @raw_state = :closed }
+    end
+
+    # Commit the transaction, while also sending finalizing Cypher
+    # statement(s). This results in a single HTTP API request for all the
+    # statement(s). You can also omit the statement(s) in order to just commit
+    # the transaction. We rescue all errors transparently.
+    #
+    # @param statements [Array<Hash>] the Cypher statements to run
+    # @return [Array<Hash{Symbol => Mixed}>, nil] the raw neo4j results,
+    #   or +nil+ in case of errors
+    #
+    # @raise [Errors::RequestError] when an error occurs, see request object
+    #   for fine-grained details
+    def commit(*statements)
+      handle_errors { commit!(*statements) }
+    end
+
+    # Rollback this transaction. No exceptions will be rescued.
+    #
+    # @return [TrueClass] when the transaction was successfully rolled back
+    #
+    # @raise [Errors::RequestError] when an error occurs, see request object
+    #   for fine-grained details
+    def rollback!
+      # We do not allow messing around in wrong states
+      raise Errors::TransactionInBadStateError, 'Transaction not open' \
+        unless @raw_state == :open
+
+      @request.rollback_transaction(@id)
+      @raw_state = :closed
+      true
+    end
+
+    # Rollback this transaction. We rescue all errors transparently.
+    #
+    # @return [Boolean] whenever the transaction was successfully rolled back,
+    #   or not
+    def rollback
+      handle_errors(false) { rollback! }
+    end
+
+    # Handle all request/response errors of the low-level connection for
+    # our non-bang methods in a generic way.
+    #
+    # @param error_result [Proc, Mixed] the object to return on errors, when a
+    #   proc is given, we call it with the actual exception object as parameter
+    #   and use the result of the proc as return value
+    # @yield the given block
+    # @return [Mixed] the result of the block, or on exceptions the
+    #   given +error_result+
+    def handle_errors(error_result = nil)
+      yield
+    rescue Errors::RequestError, Errors::ResponseError,
+           Errors::TransactionInBadStateError => e
+      # When an error occured, the transaction is automatically rolled back by
+      # neo4j, so we cannot handle any further interaction
+      cleanup
+      @raw_state = :closed
+
+      # When we got a proc/lambda as error result, call it
+      return error_result.call(e) if error_result.is_a? Proc
+
+      # Otherwise use the error result as it is
+      error_result
+    end
+
+    # Clean the transaction, in order to make it unusable for further
+    # interaction. This prevents users from leaking the transaction context and
+    # mess around with the connection pool.
+    def cleanup
+      @request = nil
+      @raw_state = :cleaned
+    end
+  end
+end

data/lib/boltless/version.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# The gem version details.
+module Boltless
+  # The version of the +boltless+ gem
+  VERSION = '1.0.0'
+
+  class << self
+    # Returns the version of gem as a string.
+    #
+    # @return [String] the gem version as string
+    def version
+      VERSION
+    end
+
+    # Returns the version of the gem as a +Gem::Version+.
+    #
+    # @return [Gem::Version] the gem version as object
+    def gem_version
+      Gem::Version.new VERSION
+    end
+  end
+end

data/lib/boltless.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require 'zeitwerk'
+require 'http'
+require 'connection_pool'
+require 'oj'
+require 'fast_jsonparser'
+require 'colorize'
+require 'active_support'
+require 'active_support/concern'
+require 'active_support/core_ext/module/delegation'
+require 'active_support/core_ext/numeric/time'
+require 'active_support/core_ext/enumerable'
+require 'pp'
+
+# The gem root namespace. Everything is bundled here.
+module Boltless
+  # Setup a Zeitwerk autoloader instance and configure it
+  loader = Zeitwerk::Loader.for_gem
+
+  # Finish the auto loader configuration
+  loader.setup
+
+  # Load standalone code
+  require 'boltless/version'
+
+  # Include top-level features
+  include Extensions::ConfigurationHandling
+  include Extensions::ConnectionPool
+  include Extensions::Transactions
+  include Extensions::Operations
+  include Extensions::Utilities
+
+  # Make sure to eager load all SDK constants
+  loader.eager_load
+end

data/spec/benchmark/transfer.rb

@@ -0,0 +1,57 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'boltless'
+require 'benchmark'
+
+Boltless.configure do |conf|
+  conf.base_url = 'http://172.17.0.4:7474'
+end
+
+Benchmark.bm do |x|
+  cycles = 150
+
+  cypher = <<~CYPHER
+    MATCH (n:User { id: $subject }) -[:ROLE*]-> () -[r:READ]-> (o)
+    WITH
+      o.id AS id,
+      null AS all,
+      r.through AS through,
+      r.condition_keys AS keys,
+      r.condition_values AS values
+    RETURN DISTINCT id, all, through, keys, values
+  CYPHER
+
+  x.report('.transaction (raw results)') do
+    cycles.times do
+      Boltless.transaction(raw_results: true) do |tx|
+        tx.run(cypher, subject: '2d07b107-2a11-436e-a66d-6e0e0272d78e')
+      end.first[:data].count
+    end
+  end
+
+  x.report('.transaction') do
+    cycles.times do
+      Boltless.transaction(raw_results: false) do |tx|
+        tx.run(cypher, subject: '2d07b107-2a11-436e-a66d-6e0e0272d78e')
+      end.first.count
+    end
+  end
+end
+
+# == Old hard-mapping
+#                            user     system      total        real
+# .transaction (raw results) 66.999341  22.444895  89.444236 (227.354975)
+# .transaction               133.277385  23.208360 156.485745 (291.491150)
+#
+# .transaction (raw results) avg(real/150) 1.51569s
+# .transaction               avg(real/150) 1.94327s (1.3x slower)
+
+# == New lazy mapping
+#                            user     system      total        real
+# .transaction (raw results) 67.460811  22.520042  89.980853 (229.456833)
+# .transaction               73.468645  22.909531  96.378176 (237.652516)
+#
+# .transaction (raw results) avg(real/150) 1.52971222s
+# .transaction               avg(real/150) 1.58435011s (±1.0x same-ish)

data/spec/boltless/extensions/configuration_handling_spec.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Boltless::Extensions::ConfigurationHandling do
+  let(:described_class) { Boltless }
+
+  before { described_class.reset_configuration! }
+
+  it 'allows the access of the configuration' do
+    expect(described_class.configuration).not_to be_nil
+  end
+
+  describe '.configure' do
+    it 'yields the configuration' do
+      expect do |block|
+        described_class.configure(&block)
+      end.to yield_with_args(described_class.configuration)
+    end
+  end
+
+  describe '.reset_configuration!' do
+    it 'resets the configuration to its defaults' do
+      described_class.configuration.request_timeout = 100
+      expect { described_class.reset_configuration! }.to \
+        change { described_class.configuration.request_timeout }
+    end
+  end
+
+  describe '.logger' do
+    it 'returns a Logger instance' do
+      expect(described_class.logger).to be_a(Logger)
+    end
+
+    it 'returns a logger with the default info level' do
+      expect(described_class.logger.level).to be_eql(Logger::INFO)
+    end
+  end
+end

data/spec/boltless/extensions/connection_pool_spec.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+RSpec.describe Boltless::Extensions::ConnectionPool do
+  let(:described_class) { Boltless }
+  let(:reload) do
+    proc do
+      described_class.connection_pool.shutdown(&:close)
+      described_class.instance_variable_set(:@connection_pool, nil)
+    end
+  end
+
+  after do
+    Boltless.reset_configuration!
+    reload.call
+  end
+
+  describe '.connection_pool' do
+    let(:action) { described_class.connection_pool }
+    let(:options) { action.checkout.default_options }
+    let(:auth) do
+      Base64.decode64(
+        options.headers['Authorization'].split(' ').last
+      ).split(':')
+    end
+
+    it 'returns a memoized connection pool instance' do
+      expect(described_class.connection_pool).to \
+        be(described_class.connection_pool)
+    end
+
+    it 'returns a HTTP client instance when requested' do
+      expect(action.checkout).to be_a(HTTP::Client)
+    end
+
+    it 'returns a configured HTTP client (pool size)' do
+      Boltless.configuration.connection_pool_size = 1
+      reload.call
+      expect(action.size).to be_eql(1)
+    end
+
+    it 'returns a configured HTTP client (connection aquire timeout)' do
+      Boltless.configuration.connection_pool_timeout = 1
+      reload.call
+      expect(action.instance_variable_get(:@timeout)).to be_eql(1)
+    end
+
+    it 'returns a configured HTTP client (persistent base URL)' do
+      Boltless.configuration.base_url = 'http://test:1234'
+      reload.call
+      expect(options.persistent).to be_eql('http://test:1234')
+    end
+
+    it 'returns a configured HTTP client (username)' do
+      Boltless.configuration.username = 'test'
+      reload.call
+      expect(auth.first).to be_eql('test')
+    end
+
+    it 'returns a configured HTTP client (password)' do
+      Boltless.configuration.password = 'test'
+      reload.call
+      expect(auth.last).to be_eql('test')
+    end
+
+    it 'returns a configured HTTP client (request timeout)' do
+      Boltless.configuration.request_timeout = 7
+      reload.call
+      expect(options.timeout_options[:global_timeout]).to be_eql(7)
+    end
+
+    it 'allows send requests' do
+      expect(action.checkout.get('/').to_s).to include('neo4j')
+    end
+  end
+
+  describe '.wait_for_server!' do
+    let(:connection) { described_class.connection_pool.checkout }
+    let(:action) { described_class.wait_for_server!(connection) }
+    let(:request_timeout) { 2.seconds }
+    let(:wait_for_upstream_server) { 2.seconds }
+    let(:logger) { Logger.new(log) }
+    let(:log) { StringIO.new }
+
+    before do
+      Boltless.configure do |conf|
+        conf.request_timeout = request_timeout
+        conf.wait_for_upstream_server = wait_for_upstream_server
+        conf.logger = logger
+      end
+      Boltless.instance_variable_set(:@upstream_is_ready, nil)
+      Boltless.instance_variable_set(:@upstream_retry_count, nil)
+      reload.call
+    end
+
+    context 'when the server is up and running' do
+      it 'returns the given connection' do
+        expect(action).to be(connection)
+      end
+
+      it 'memoizes the check' do
+        action
+        expect(connection).not_to receive(:get)
+        action
+      end
+    end
+
+    context 'when the server is not available' do
+      before do
+        Boltless.configuration.base_url = 'http://localhost:8751'
+        reload.call
+      end
+
+      it 'raises a HTTP::ConnectionError' do
+        expect { action }.to raise_error(HTTP::ConnectionError)
+      end
+
+      describe 'logging' do
+        let(:wait_for_upstream_server) { 2.1.seconds }
+
+        it 'logs a retry' do
+          suppress(HTTP::ConnectionError) { action }
+          expect(log.string).to \
+            include('neo4j is unavailable, retry in 2 seconds ' \
+                    '(1/2, http://localhost:8751)')
+        end
+      end
+    end
+  end
+end