boltless 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1d776e0f6ae5034f522faf66e8900c225d0799bc9b73257b681e9afd7b912f02
+  data.tar.gz: 3ed2ba355d515b9dfd620616772e083c097d02b401a847f43939c87024119fef
+SHA512:
+  metadata.gz: 34e8e551fd39dd5069e3b58934ec7834eb9629defc3ca2accb185449cbb956c297bbd36f7a340cca836182d0b67c09b64719112ffc4d7179bd0eac158534da9d
+  data.tar.gz: cc5f3dabddbf7845f0a43126c3b3919d92a6873718f1895cd95d8b05c7ac2a29c787b18e7dae3b1074677ab3ef5c9295ec03fc57d8b0b76a50f66c2d900513d1

data/Gemfile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in boltless.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+(directories %w[lib spec]).select do |d|
+  if Dir.exist?(d)
+    d
+  else
+    UI.warning("Directory #{d} does not exist")
+  end
+end
+
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+# NOTE: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separately)
+#  * 'just' rspec: 'rspec'
+
+guard :rspec, cmd: 'bundle exec rspec' do
+  watch('spec/spec_helper.rb') { 'spec' }
+  watch(%r{^lib/boltless.rb}) { 'spec' }
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/boltless/([^\\]+)\.rb$}) do |m|
+    "spec/boltless/#{m[1]}_spec.rb"
+  end
+  watch(%r{^lib/boltless/([^\\]+)/(.*)\.rb$}) do |m|
+    "spec/#{m[1]}/#{m[2]}_spec.rb"
+  end
+end

data/Makefile

@@ -0,0 +1,138 @@
+MAKEFLAGS += --warn-undefined-variables -j1
+SHELL := bash
+.SHELLFLAGS := -eu -o pipefail -c
+.DEFAULT_GOAL := all
+.DELETE_ON_ERROR:
+.SUFFIXES:
+.PHONY:
+
+# Environment switches
+MAKE_ENV ?= docker
+COMPOSE_RUN_SHELL_FLAGS ?= --rm
+BASH_RUN_SHELL_FLAGS ?=
+
+# Directories
+VENDOR_DIR ?= vendor/bundle
+GEMFILES_DIR ?= gemfiles
+
+# Host binaries
+BASH ?= bash
+COMPOSE ?= docker-compose
+ID ?= id
+MKDIR ?= mkdir
+RM ?= rm
+
+# Container binaries
+BUNDLE ?= bundle
+APPRAISAL ?= appraisal
+RAKE ?= rake
+RUBOCOP ?= rubocop
+GUARD ?= guard
+YARD ?= yard
+
+# Files
+GEMFILES ?= $(subst _,-,$(patsubst $(GEMFILES_DIR)/%.gemfile,%,\
+	$(wildcard $(GEMFILES_DIR)/*.gemfile)))
+TEST_GEMFILES := $(GEMFILES:%=test-%)
+
+# Define a generic shell run wrapper
+# $1 - The command to run
+ifeq ($(MAKE_ENV),docker)
+define run-shell
+	$(COMPOSE) run $(COMPOSE_RUN_SHELL_FLAGS) \
+		-e LANG=en_US.UTF-8 -e LANGUAGE=en_US.UTF-8 -e LC_ALL=en_US.UTF-8 \
+		-e HOME=/tmp -e BUNDLE_APP_CONFIG=/app/.bundle \
+		-u `$(ID) -u` test \
+		bash $(BASH_RUN_SHELL_FLAGS)  -c 'sleep 0.1; echo; $(1)'
+endef
+else ifeq ($(MAKE_ENV),baremetal)
+define run-shell
+	$(1)
+endef
+endif
+
+all:
+	# Boltless
+	#
+	# install            Install the dependencies
+	# test               Run the whole test suite
+	# clean              Clean the dependencies
+	# watch              Watch for code changes and rerun the test suite
+	#
+	# docs               Generate the Ruby documentation of the library
+	# stats              Print the code statistics (library and test suite)
+	# notes              Print all the notes from the code
+	# release            Release a new Gem version (maintainers only)
+	#
+	# shell              Run an interactive shell on the container
+	# shell-irb          Run an interactive IRB shell on the container
+
+.interactive:
+	@$(eval BASH_RUN_SHELL_FLAGS = --login)
+
+install:
+	# Install the dependencies
+	@$(MKDIR) -p $(VENDOR_DIR)
+	@$(call run-shell,$(BUNDLE) check || $(BUNDLE) install --path $(VENDOR_DIR))
+	@$(call run-shell,$(BUNDLE) exec $(APPRAISAL) install)
+
+test: \
+	test-specs \
+	test-style
+
+test-specs:
+	# Run the whole test suite
+	@$(call run-shell,$(BUNDLE) exec $(RAKE) stats spec)
+
+$(TEST_GEMFILES): GEMFILE=$(@:test-%=%)
+$(TEST_GEMFILES):
+	# Run the whole test suite ($(GEMFILE))
+	@$(call run-shell,$(BUNDLE) exec $(APPRAISAL) $(GEMFILE) $(RAKE))
+
+test-style: \
+	test-style-ruby
+
+test-style-ruby:
+	# Run the static code analyzer (rubocop)
+	@$(call run-shell,$(BUNDLE) exec $(RUBOCOP) -a)
+
+watch: install .interactive
+	# Watch for code changes and rerun the test suite
+	@$(call run-shell,$(BUNDLE) exec $(GUARD))
+
+clean:
+	# Clean the dependencies
+	@$(RM) -rf $(VENDOR_DIR)
+
+clean-containers:
+	# Clean running containers
+ifeq ($(MAKE_ENV),docker)
+	@$(COMPOSE) down
+endif
+
+distclean: clean clean-containers
+
+shell:
+	# Run an interactive shell on the container
+	@$(call run-shell,$(BASH) -i)
+
+shell-irb:
+	# Run an interactive IRB shell on the container
+	@$(call run-shell,bin/console)
+
+docs:
+	# Build the API documentation
+	@$(call run-shell,$(BUNDLE) exec $(YARD) -q && \
+		$(BUNDLE) exec $(YARD) stats --list-undoc --compact)
+
+notes:
+	# Print the code statistics (library and test suite)
+	@$(call run-shell,$(BUNDLE) exec $(RAKE) notes)
+
+stats:
+	# Print all the notes from the code
+	@$(call run-shell,$(BUNDLE) exec $(RAKE) stats)
+
+release:
+	# Release a new gem version
+	@$(BUNDLE) exec $(RAKE) release

data/Rakefile

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'countless/rake_tasks'
+require 'pp'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+# Configure all code statistics directories
+Countless.configure do |config|
+  config.stats_base_directories = [
+    { name: 'Top-levels', dir: 'lib',
+      pattern: %r{/lib(/boltless)?/[^/]+\.rb$} },
+    { name: 'Top-levels specs', test: true, dir: 'spec',
+      pattern: %r{/spec(/boltless)?/[^/]+_spec\.rb$} },
+    { name: 'Extensions', pattern: 'lib/boltless/extensions/**/*.rb' },
+    { name: 'Extensions specs', test: true,
+      pattern: 'spec/boltless/extensions/**/*_spec.rb' },
+    { name: 'Errors', pattern: 'lib/boltless/errors/**/*.rb' },
+    { name: 'Errors specs', test: true,
+      pattern: 'spec/boltless/errors/**/*_spec.rb' }
+  ]
+end

data/docker-compose.yml

@@ -0,0 +1,19 @@
+version: "3"
+services:
+  test:
+    image: ruby:2.7
+    network_mode: bridge
+    working_dir: /app
+    links:
+      - neo4j
+    volumes:
+      - .:/app
+
+  neo4j:
+    image: hausgold/neo4j:4.4
+    network_mode: bridge
+    ports: ["7474", "7687"]
+    volumes:
+      - .:/app:${DOCKER_MOUNT_MODE:-rw}
+    environment:
+      MDNS_HOSTNAME: neo4j.boltless.local

data/lib/boltless/configuration.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Boltless
+  # The configuration for the Boltless gem.
+  class Configuration
+    include ActiveSupport::Configurable
+
+    # The base URL of the neo4j HTTP API (port 7474 for HTTP, port 7473
+    # for HTTPS when configured at server side)
+    config_accessor(:base_url) { 'http://neo4j:7474' }
+
+    # The username for the neo4j database (used for HTTP Basic Authentication)
+    config_accessor(:username) { 'neo4j' }
+
+    # The password for the neo4j database (used for HTTP Basic Authentication)
+    config_accessor(:password) { 'neo4j' }
+
+    # The default user database of the neo4j instance/cluster, for the
+    # community edition this is always +neo4j+, only a single user database is
+    # supported with the community editon. You can always specify which
+    # database to operate on, on each top-level querying method (eg.
+    # +Boltless.execute(.., database: 'custom')+
+    config_accessor(:default_db) { 'neo4j' }
+
+    # The seconds to wait for a connection from the pool,
+    # when all connections are currently in use
+    config_accessor(:connection_pool_timeout) { 15.seconds }
+
+    # The size of the connection pool, make sure it matches your application
+    # server (eg. Puma) thread pool size, in order to avoid
+    # timeouts/bottlenecks
+    config_accessor(:connection_pool_size) { 10 }
+
+    # The overall timeout for a single HTTP request (including connecting,
+    # transmitting and response completion)
+    config_accessor(:request_timeout) { 10.seconds }
+
+    # We allow the neo4j server to bootup for the configured time. This allows
+    # parallel starts of the user application and the neo4j server, without
+    # glitching.
+    config_accessor(:wait_for_upstream_server) { 30.seconds }
+
+    # Configure a logger for the gem
+    config_accessor(:logger) do
+      Logger.new($stdout).tap do |logger|
+        logger.level = :info
+      end
+    end
+
+    # Whenever we should log the neo4j queries, including benchmarking. When
+    # disabled we reduce the logging overhead even more as no debug logs hit
+    # the logger at all. Enable this for testing purposes or for local
+    # development. (Heads up: No parameter sanitation is done, so passwords etc
+    # will be logged with this enabled) Setting the value to +:debug+ will
+    # print the actual Cypher statements before any request is sent. This may
+    # be helpful inspection of slow/never-ending Cypher statements.
+    config_accessor(:query_log_enabled) { false }
+
+    # We allow the http.rb gem to be configured by the user for special needs.
+    # Just assign a user given block here and you can reconfigure the client.
+    # Just make sure to return the configured +HTTP::Client+ instance
+    # afterwards.
+    config_accessor(:http_client_configure) do
+      proc do |connection|
+        connection
+      end
+    end
+  end
+end

data/lib/boltless/errors/invalid_json_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Boltless
+  module Errors
+    # This exception is raised whenever we were not able to produce or
+    # consume JSON data.
+    class InvalidJsonError < RequestError; end
+  end
+end

data/lib/boltless/errors/request_error.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Boltless
+  module Errors
+    # A generic request error wrapper, from the low-level http.rb gem
+    class RequestError < StandardError
+      # We allow to read our details
+      attr_accessor :message
+      attr_reader :response
+
+      # Create a new generic request error instance.
+      #
+      # @param message [String] the error message
+      # @param response [HTTP::Response, nil] the HTTP response,
+      #   or +nil+ when not available
+      # @return [Errors::RequestError] the new error instance
+      def initialize(message, response: nil)
+        super(message)
+        @message = message
+        @response = response
+      end
+    end
+  end
+end

data/lib/boltless/errors/response_error.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Boltless
+  module Errors
+    # A generic response error, for everything neo4j want to tell us
+    class ResponseError < StandardError
+      # We allow to read our details
+      attr_accessor :message
+      attr_reader :code, :response
+
+      # Create a new generic response error instance.
+      #
+      # @param message [String] the error message
+      # @param code [String, nil] the neo4j error code,
+      #   or +nil+ when not available
+      # @param response [HTTP::Response, nil] the HTTP response,
+      #   or +nil+ when not available
+      # @return [Errors::RequestError] the new error instance
+      def initialize(message, code: nil, response: nil)
+        formatted = "#{message} (#{code})" if message && code
+        formatted = code unless message
+        formatted ||= message
+        super(formatted)
+        @message = formatted
+        @code = code
+        @response = response
+      end
+    end
+  end
+end

data/lib/boltless/errors/transaction_begin_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Boltless
+  module Errors
+    # This exception is raised when we failed to start a new transaction
+    # at the neo4j server.
+    class TransactionBeginError < RequestError; end
+  end
+end

data/lib/boltless/errors/transaction_in_bad_state_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Boltless
+  module Errors
+    # This exception is raised when a transaction is going to be used, but is
+    # not usable in its current state. This may happen when a not-yet-started
+    # transaction should send a query, or when an already rolled back
+    # transaction should be used, etc.
+    class TransactionInBadStateError < RequestError; end
+  end
+end

data/lib/boltless/errors/transaction_not_found_error.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Boltless
+  module Errors
+    # This exception is raised when there is no open transaction at the neo4j
+    # server with the given identifier. The neo4j server closes an
+    # idling/inactive transaction after 60 seconds by default (after the last
+    # interaction). This value can be configured at the neo4j server.
+    class TransactionNotFoundError < RequestError; end
+  end
+end

data/lib/boltless/errors/transaction_rollback_error.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Boltless
+  module Errors
+    # This exception is raised when we failed to rollback a transaction
+    # at the neo4j server, or when another error caused a transaction rollback.
+    class TransactionRollbackError < RequestError
+      # We allow to read our details
+      attr_reader :errors
+
+      # Create a new generic response error instance.
+      #
+      # @param message [String] the error message
+      # @param errors [Array<Errors::ResponseError>, Errors::ResponseError]
+      #   a single/multiple response errors
+      # @param response [HTTP::Response, nil] the HTTP response,
+      #   or +nil+ when not available
+      # @return [Errors::TransactionRollbackError] the new error instance
+      def initialize(message, errors: [], response: nil)
+        @errors = Array(errors)
+        message += "\n\n#{@errors.map { |err| "* #{err.message}" }.join("\n")}"
+        super(message, response: response)
+      end
+    end
+  end
+end

data/lib/boltless/extensions/configuration_handling.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Boltless
+  module Extensions
+    # A top-level gem-module extension to handle configuration needs.
+    module ConfigurationHandling
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Retrieve the current configuration object.
+        #
+        # @return [Configuration] the current configuration object
+        def configuration
+          @configuration ||= Configuration.new
+        end
+
+        # Configure the concern by providing a block which takes
+        # care of this task. Example:
+        #
+        #   Boltless.configure do |conf|
+        #     # conf.xyz = [..]
+        #   end
+        def configure
+          yield(configuration)
+        end
+
+        # Reset the current configuration with the default one.
+        def reset_configuration!
+          @configuration = Configuration.new
+        end
+
+        # A shortcut to the configured logger.
+        delegate :logger, to: :configuration
+      end
+    end
+  end
+end

data/lib/boltless/extensions/connection_pool.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Boltless
+  module Extensions
+    # A top-level gem-module extension to add easy-to-use connection pool.
+    #
+    # rubocop:disable Metrics/BlockLength because this is how
+    #   an +ActiveSupport::Concern+ looks like
+    module ConnectionPool
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Check if the neo4j server is ready to rumble. This comes in handy in
+        # local scenarios when the neo4j server is booted in parallel to the
+        # user application. Then it may be necessary to wait for the neo4j
+        # server to come up, before sending real requests which may otherwise
+        # be ignored.
+        #
+        # @param connection [HTTP::Client]
+        # @return [HTTP::Client] the given connection
+        #
+        # @raise [HTTP::Error] in case the upstream server did not come up
+        #
+        # rubocop:disable Metrics/MethodLength because of the
+        #   retry logic
+        # rubocop:disable Metrics/AbcSize dito
+        def wait_for_server!(connection)
+          # Check if the server already accepted connections
+          return connection if @upstream_is_ready
+
+          # Otherwise we setup the retry counter and
+          # increment it for the current try
+          @upstream_retry_count ||= 0
+          @upstream_retry_count += 1
+
+          # We didn't checked the upstream server yet
+          body = connection.get('/').to_s
+          raise "Upstream server not available: #{body}" \
+            unless body.include? 'neo4j_version'
+
+          # When we reached this point, the remote connection is established,
+          # so we reset the retry counter
+          @upstream_retry_count = 0
+
+          # Everything looks good, when we passed this point
+          @upstream_is_ready = true
+
+          # Return the given connection
+          connection
+        rescue HTTP::Error, RuntimeError => e
+          # Something is bad, we got a timeout or the response body
+          # was unexpected, so lets try it again
+          retry_sleep = 2.seconds
+
+          # We allow the service to be unavailable for 30 seconds
+          max_retries = (
+            configuration.wait_for_upstream_server / retry_sleep
+          ).ceil
+          raise e if @upstream_retry_count >= max_retries
+
+          logger.warn do
+            '> neo4j is unavailable, retry in 2 seconds' \
+              " (#{@upstream_retry_count}/#{max_retries}, " \
+              "#{configuration.base_url})"
+              .colorize(:yellow)
+          end
+          sleep(retry_sleep)
+          retry
+        end
+        # rubocop:enable Metrics/MethodLength
+        # rubocop:enable Metrics/AbcSize
+
+        # A memoized connection pool for our HTTP API clients.
+        #
+        # @see https://github.com/mperham/connection_pool
+        # @return [::ConnectionPool] the connection pool instance
+        #
+        # rubocop:disable Metrics/MethodLength because of the
+        #   connection configuration
+        # rubocop:disable Metrics/AbcSize dito
+        def connection_pool
+          @connection_pool ||= begin
+            conf = Boltless.configuration
+
+            ::ConnectionPool.new(
+              size: conf.connection_pool_size,
+              timeout: conf.connection_pool_timeout
+            ) do
+              HTTP
+                .use({ normalize_uri: { normalizer: ->(uri) { uri } } })
+                .use(:auto_inflate)
+                .timeout(conf.request_timeout.to_i)
+                .basic_auth(
+                  user: conf.username,
+                  pass: conf.password
+                )
+                .headers(
+                  'User-Agent' => "Boltless/#{Boltless::VERSION}",
+                  'Accept-Encoding' => 'gzip',
+                  'Accept' => 'application/json',
+                  'Content-Type' => 'application/json',
+                  'X-Stream' => 'true'
+                )
+                .encoding('UTF-8')
+                .persistent(conf.base_url)
+                .yield_self do |connection|
+                  conf.http_client_configure.call(connection)
+                end
+            end
+          end
+        end
+        # rubocop:enable Metrics/MethodLength
+        # rubocop:enable Metrics/AbcSize
+      end
+
+      included do
+        # Install an shutdown handler for our connection pool
+        at_exit do
+          connection_pool.shutdown do |connection|
+            connection&.close
+          end
+        end
+      end
+    end
+    # rubocop:enable Metrics/BlockLength
+  end
+end