neo4j-http 0.0.2 → 1.0.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 819aaa895d72fbc40defc9cd543bf397fbfe856e1f615d560e9f9af80e247975
-  data.tar.gz: 72542a042e0e1ae65f1fcb6791990d7f562510db42931eebe716b62cf38c411e
+  metadata.gz: bf2b30d0cffb2fb720bf747a3198b89f92476be14e0110fe239b150c2fb6ea5f
+  data.tar.gz: 73531f1a3e1f22afa9033ff455d09c9400916750200fd2b06a0589c870384368
 SHA512:
-  metadata.gz: ee3c850f9bba7744d9dbb38f2a76755269ab3309977cea4ce9b01139a93a456e59cde24657fd3ba372198028168733e21edc034b0146a24c5d924216311724fa
-  data.tar.gz: 97dc54f49c8fdec52f8ec6cd0c9ba56e30c744edb07b8dceb972311d6ebe97b197954ccafc64e52d018b82154b397887ed89a980646dc5164ecc298db3bd7749
+  metadata.gz: 13acafdcb7be32279fc4b33e32f719a6dddb01da2d4bacef98639d3f8b10a6e170ed135a71335471bb22408d351a9e9979cea25ef5669e921ad1e0424e644037
+  data.tar.gz: 3e7e38447a5659fc75b8af9a349321b23a0cae4ccaa83f0d8200bb60f71fbd4e5323858db03ed06531d436fb74e8e1afcd7cb748dd445fab24d5ada295a5965b

data/README.md

@@ -1,6 +1,11 @@
 # Neo4j::Http
 
-The `Neo4j::Http` gem provides `Neo4j::Http::Client` as a thin wrapper around the [Neo4j HTTP API](https://neo4j.com/docs/http-api/current/).
+The `Neo4j::Http` gem provides `a thin wrapper around the [Neo4j HTTP API](https://neo4j.com/docs/http-api/current/) (not the legacy REST api which was removed in 4.0). It works with Neo4j 3.5 through the latest release (at the time of this writing is 4.4)
+
+## Why a new gem?
+The available gems to interact with Neo4j are generally: out of date relying on legacy APIs removed in 4.x, require the use of JRuby, or out of date C bindings.
+
+The goal of this gem is to provide a dependency free Ruby implementation that provides a simple wrapper to the [Neo4j HTTP API](https://neo4j.com/docs/http-api/current/)  to do most of what applications may need in order to leverage the power Neo4j provides.
 
 ## Installation
 
@@ -18,13 +23,96 @@ Or install it yourself as:
 
     $ gem install neo4j-http
 
+## Configuration
+
+The client is configured by default via a set of environment variables from [Neo4j::Http::Configuration](https://github.com/doximity/neo4j-http/blob/master/lib/neo4j/http/configuration.rb):
+
+* `NEO4J_URL`  - The base URL to connect to Neo4j at
+* `NEO4J_USER` - The user name to use when authenticating to neo4j
+* `NEO4J_PASSWORD` - The password of the user to be used for authentication
+* `NEO4J_DATABASE` - The database name to be used when connecting.  By default this will be nil and the path used for connecting to Neo4j wil be `/db/data/transaction/commit` to make it compliant with v3.5 of neo4j
+* `NEO4J_HTTP_USER_AGENT` - The user agent name provided in the request - defaults to `Ruby Neo4j Http Client`
+* `NEO4J_REQUEST_TIMEOUT_IN_SECONDS` - The number of seconds for the http request to time out if provided, defaults to nil
+
+These configuration values can also be set during initalization like:
+
+```ruby
+Neo4j::Http.configure do |config|
+  config.request_timeout_in_seconds = 42
+end
+```
+
+## Usage
+
+The core interface can be directly accessed on `Neo4::Http::Client` -
+
+### Execute arbitrary cypher commands
+```ruby
+Neo4j::Http::Client.execute_cypher('MATCH (n:User{id: $id}) return n LIMIT 25', id: 42)
+```
+
+### Upsert, find and delete nodes
+```ruby
+node = Neo4j::Http::Node.new(label: "User", uuid: SecureRandom.uuid)
+Neo4j::Http::Client.upsert_node(node)
+Neo4j::Http::Client.find_node_by(label: "User", uuid: node.uuid)
+Neo4j::Http::Client.find_nodes_by(label: "User", name: "Testing")
+Neo4j::Http::Client.delete_node(node)
+```
+
+### Create a new relationship, also creating the nodes if they do not exist
+```ruby
+user1 = Neo4j::Http::Node.new(label: "User", uuid: SecureRandom.uuid)
+user2 = Neo4j::Http::Node.new(label: "User", uuid: SecureRandom.uuid)
+relationship = Neo4j::Http::Relationship.new(label: "KNOWS")
+Neo4j::Http::Client.upsert_relationship(relationship: relationship, from: user1, to: user2, create_nodes: true)
+```
+
+### Find an existing relationship
+```ruby
+Neo4j::Http::Client.find_relationship(relationship: relationship, from: user1, to: user2)
+```
+
+### Delete the relationship if it exists
+```ruby
+Neo4j::Http::Client.delete_relationship(relationship: relationship, from: user1, to: user2)
+```
+
+Each of the methods exposed on `Neo4j::Http::Client` above are provided by instances of each of the following adapters:
+* `Neo4j::Http::CypherClient` - provides an `execute_cypher` method which sends raw cypher commands to neo4j
+* `Neo4j::Http::NodeClient` - provides a higher level API for upserting and deleting Nodes
+* `Neo4j::Http::RelationshipClient` - provides a higher level API for upserting and deleting Relationships
+
+The Node and Relationship clients use the `CypherClient` under the hood.  Each of these provides simple access via a `default` class method, which uses the default `Neo4j::Http.config` for creating the connections. For example
+
+`Neo4j::Http::NodeClient.default`
+
+is equivalent to:
+
+```
+config = Neo4j::Http.config
+cypher_client = Neo4j::Http::CypherClient.new(config)
+node_client = Neo4j::Http::NodeClient.new(cypher_client)
+```
+
+to connect to a different Neo4j database, you can create a custom configuration like:
+```
+config = Neo4j::Http::Configuration.new({ database_name: 'test' })
+cypher_client = Neo4j::Http::CypherClient.new(config)
+node_client = Neo4j::Http::NodeClient.new(cypher_client)
+```
+
 ## Versioning
 
 This project follows [semantic versioning](https://semver.org).
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies.
+
+To run specs, you'll need a running neo4j instance available at `localhost:7474`.  If you have Docker installed, this is easily done by using the provided [docker-file](https://github.com/doximity/neo4j-http/blob/master/docker-compose.yml) - simply run `docker-compose up` within the project directory, and once running, you can then, run `rake spec` to run the tests in another terminal.
+
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`.
 
@@ -33,7 +121,7 @@ To release a new version, update the version number in `version.rb`, issue a pul
 ## Contributing
 
 1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
+2. Create your feature branch (`git switch -c my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request

data/lib/neo4j/http/auth_token.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Http
+    class AuthToken
+      def self.token(username, password)
+        new(username, password).token
+      end
+
+      def initialize(username, password)
+        @username = username
+        @password = password
+      end
+
+      # See: https://neo4j.com/docs/developer-manual/current/http-api/authentication/#http-api-authenticate-to-access-the-server
+      def token
+        return "" if @username.blank? || @password.blank?
+
+        Base64.encode64("#{@username}:#{@password}")
+      end
+    end
+  end
+end

data/lib/neo4j/http/client.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Http
+    class Client
+      CYPHER_CLIENT_METHODS = %i[execute_cypher].freeze
+      NODE_CLIENT_METHODS = %i[delete_node find_node_by find_nodes_by upsert_node].freeze
+      RELATIONSHIP_CLIENT_METHODS = %i[delete_relationship upsert_relationship].freeze
+      CLIENT_METHODS = (CYPHER_CLIENT_METHODS + NODE_CLIENT_METHODS + RELATIONSHIP_CLIENT_METHODS).freeze
+
+      class << self
+        delegate(*CLIENT_METHODS, to: :default)
+
+        def default
+          cypher_client = Http::CypherClient.new(Neo4j::Http.config)
+          node_client = Http::NodeClient.new(cypher_client)
+          relationship_client = Http::RelationshipClient.new(cypher_client)
+          @default ||= new(cypher_client, node_client, relationship_client)
+        end
+      end
+
+      attr_accessor :cypher_client, :node_client, :relationship_client
+
+      def initialize(cypher_client, node_client, relationship_client)
+        @cypher_client = cypher_client
+        @node_client = node_client
+        @relationship_client = relationship_client
+      end
+
+      delegate(*CYPHER_CLIENT_METHODS, to: :cypher_client)
+      delegate(*NODE_CLIENT_METHODS, to: :node_client)
+      delegate(*RELATIONSHIP_CLIENT_METHODS, to: :relationship_client)
+    end
+  end
+end

data/lib/neo4j/http/configuration.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Http
+    class Configuration
+      attr_accessor :database_name
+      attr_accessor :password
+      attr_accessor :request_timeout_in_seconds
+      attr_accessor :uri
+      attr_accessor :user
+      attr_accessor :user_agent
+
+      def initialize(options = ENV)
+        @uri = options.fetch("NEO4J_URL", "http://localhost:7474")
+        @user = options.fetch("NEO4J_USER", "")
+        @password = options.fetch("NEO4J_PASSWORD", "")
+        @database_name = options.fetch("NEO4J_DATABASE", nil)
+        @user_agent = options.fetch("NEO4J_HTTP_USER_AGENT", "Ruby Neo4j Http Client")
+        @request_timeout_in_seconds = options.fetch("NEO4J_REQUEST_TIMEOUT_IN_SECONDS", nil)
+      end
+
+      def transaction_path
+        # v3.5 - /db/data/transaction/commit
+        # v4.x - /db/#{database_name}/tx/commit
+        if database_name
+          "/db/#{database_name}/tx/commit"
+        else
+          "/db/data/transaction/commit"
+        end
+      end
+
+      def auth_token
+        Neo4j::Http::AuthToken.token(user, password)
+      end
+    end
+  end
+end

data/lib/neo4j/http/cypher_client.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require "faraday"
+require "faraday/retry"
+require "faraday_middleware"
+
+module Neo4j
+  module Http
+    class CypherClient
+      def self.default
+        @default ||= new(Neo4j::Http.config)
+      end
+
+      def initialize(configuration)
+        @configuration = configuration
+      end
+
+      def execute_cypher(cypher, parameters = {})
+        request_body = {
+          statements: [
+            {statement: cypher,
+             parameters: parameters.as_json}
+          ]
+        }
+
+        response = connection.post(transaction_path, request_body)
+        results = check_errors!(cypher, response, parameters)
+
+        Neo4j::Http::Results.parse(results&.first || {})
+      end
+
+      def connection
+        build_connection
+      end
+
+      protected
+
+      delegate :auth_token, :transaction_path, to: :@configuration
+      def check_errors!(cypher, response, parameters)
+        raise Neo4j::Http::Errors::InvalidConnectionUrl, response.status if response.status == 404
+        body = response.body || {}
+        errors = body.fetch("errors", [])
+        return body.fetch("results", {}) unless errors.present?
+
+        error = errors.first
+        raise_error(error, cypher, parameters)
+      end
+
+      def raise_error(error, cypher, parameters = {})
+        code = error["code"]
+        message = error["message"]
+        klass = find_error_class(code)
+        parameters = JSON.pretty_generate(parameters.as_json)
+        raise klass, "#{code} - #{message}\n cypher: #{cypher} \n parameters given: \n#{parameters}"
+      end
+
+      def find_error_class(code)
+        Neo4j::Http::Errors.const_get(code.gsub(".", "::"))
+      rescue
+        Neo4j::Http::Errors::Neo4jCodedError
+      end
+
+      def build_connection
+        Faraday.new(url: @configuration.uri, headers: build_http_headers, request: build_request_options) do |f|
+          f.request :json # encode req bodies as JSON
+          f.request :retry # retry transient failures
+          f.response :json # decode response bodies as JSON
+        end
+      end
+
+      def build_request_options
+        request_options = {}
+
+        timeout = @configuration.request_timeout_in_seconds.to_i
+        request_options[:timeout] = timeout if timeout.positive?
+
+        request_options
+      end
+
+      def build_http_headers
+        {
+          "User-Agent" => @configuration.user_agent,
+          "Accept" => "application/json"
+        }.merge(authentication_headers)
+      end
+
+      def authentication_headers
+        return {} if auth_token.blank?
+
+        {"Authentication" => "Basic #{auth_token}"}
+      end
+    end
+  end
+end

data/lib/neo4j/http/errors.rb

@@ -0,0 +1,22 @@
+module Neo4j
+  module Http
+    module Errors
+      Neo4jError = Class.new(StandardError)
+      InvalidConnectionUrl = Class.new(Neo4jError)
+      Neo4jCodedError = Class.new(Neo4jError)
+
+      # These are specific Errors Neo4j can raise
+      module Neo
+        module ClientError
+          module Statement
+            SyntaxError = Class.new(Neo4jCodedError)
+          end
+
+          module Schema
+            ConstraintValidationFailed = Class.new(Neo4jCodedError)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/http/node.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Http
+    class Node < ObjectWrapper
+      DEFAULT_PRIMARY_KEY_NAME = "uuid"
+      def initialize(label:, graph_node_primary_key_name: DEFAULT_PRIMARY_KEY_NAME, **attributes)
+        super
+      end
+    end
+  end
+end

data/lib/neo4j/http/node_client.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Http
+    class NodeClient
+      def self.default
+        @default ||= new(CypherClient.default)
+      end
+
+      def initialize(cypher_client)
+        @cypher_client = cypher_client
+      end
+
+      def upsert_node(node)
+        raise "#{node.key_name} value cannot be blank - (node keys: #{node.to_h.keys})" if node.key_value.blank?
+
+        cypher = <<-CYPHER
+          MERGE (node:#{node.label} {#{node.key_name}: $key_value})
+          ON CREATE SET node += $attributes
+          ON MATCH SET node += $attributes
+          return node
+        CYPHER
+
+        results = @cypher_client.execute_cypher(cypher, key_value: node.key_value, attributes: node.attributes)
+
+        results.first&.fetch("node")
+      end
+
+      def delete_node(node)
+        cypher = <<-CYPHER
+          MATCH (node:#{node.label} {#{node.key_name}: $key_value})
+          WITH node
+          DETACH DELETE node
+          RETURN node
+        CYPHER
+
+        results = @cypher_client.execute_cypher(cypher, key_value: node.key_value)
+        results.first&.fetch("node")
+      end
+
+      def find_node_by(label:, **attributes)
+        selectors = attributes.map { |key, value| "#{key}: $attributes.#{key}" }.join(", ")
+        cypher = "MATCH (node:#{label} { #{selectors} }) RETURN node LIMIT 1"
+        results = @cypher_client.execute_cypher(cypher, attributes: attributes)
+        return if results.empty?
+        results.first&.fetch("node")
+      end
+
+      def find_nodes_by(label:, attributes:, limit: 100)
+        selectors = build_selectors(attributes)
+        cypher = "MATCH (node:#{label}) where #{selectors} RETURN node LIMIT #{limit}"
+        results = @cypher_client.execute_cypher(cypher, attributes: attributes)
+        results.map { |result| result["node"] }
+      end
+
+      protected
+
+      def build_selectors(attributes, node_name: :node)
+        attributes.map do |key, value|
+          if value.is_a?(Array)
+            "#{node_name}.#{key} IN $attributes.#{key}"
+          else
+            "#{node_name}.#{key} = $attributes.#{key}"
+          end
+        end.join(" AND ")
+      end
+    end
+  end
+end

data/lib/neo4j/http/object_wrapper.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Http
+    class ObjectWrapper
+      attr_reader :attributes,
+        :key_name,
+        :key_value,
+        :label,
+        :original_attributes
+
+      def initialize(label:, graph_node_primary_key_name: nil, **attributes)
+        @original_attributes = (attributes || {}).with_indifferent_access
+        @attributes = original_attributes.dup.with_indifferent_access
+        @key_name = graph_node_primary_key_name
+        @key_value = @attributes.delete(key_name)
+        @label = label
+      end
+
+      delegate :[], :to_h, :as_json, :to_json, to: :@original_attributes
+
+      def method_missing(method_name, *args, &block)
+        if @original_attributes.has_key?(method_name)
+          original_attributes[method_name]
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        @original_attributes.has_key?(method_name) || super
+      end
+    end
+  end
+end

data/lib/neo4j/http/relationship.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Http
+    class Relationship < ObjectWrapper
+    end
+  end
+end

data/lib/neo4j/http/relationship_client.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Neo4j
+  module Http
+    class RelationshipClient
+      def self.default
+        @default ||= new(CypherClient.default)
+      end
+
+      def initialize(cypher_client)
+        @cypher_client = cypher_client
+      end
+
+      def upsert_relationship(relationship:, from:, to:, create_nodes: false)
+        match_or_merge = create_nodes ? "MERGE" : "MATCH"
+        from_selector = build_match_selector(:from, from)
+        to_selector = build_match_selector(:to, to)
+        relationship_selector = build_match_selector(:relationship, relationship)
+
+        on_match = ""
+        if relationship.attributes.present?
+          on_match = <<-CYPHER
+            ON CREATE SET relationship += $relationship_attributes
+            ON MATCH SET relationship += $relationship_attributes
+          CYPHER
+        end
+
+        cypher = +<<-CYPHER
+          #{match_or_merge} (#{from_selector})
+          #{match_or_merge} (#{to_selector})
+          MERGE (from) - [#{relationship_selector}] - (to)
+          #{on_match}
+          RETURN from, to, relationship
+        CYPHER
+
+        results = @cypher_client.execute_cypher(
+          cypher,
+          from: from,
+          to: to,
+          relationship: relationship,
+          relationship_attributes: relationship.attributes
+        )
+        results&.first
+      end
+
+      def find_relationship(from:, relationship:, to:)
+        from_match_clause = build_match_selector(:from, from)
+        to_match_clause = build_match_selector(:to, to)
+        relationship_clause = build_match_selector(:relationship, relationship)
+        cypher = <<-CYPHER
+          MATCH (#{from_match_clause}) - [#{relationship_clause}] - (#{to_match_clause})
+          RETURN from, to, relationship
+        CYPHER
+
+        results = @cypher_client.execute_cypher(cypher, from: from, to: to, relationship: relationship)
+        results&.first
+      end
+
+      def build_match_selector(name, data)
+        selector = +"#{name}:#{data.label}"
+        selector << " {#{data.key_name}: $#{name}.#{data.key_name}}" if data.key_name.present?
+        selector
+      end
+
+      def delete_relationship(relationship:, from:, to:)
+        from_selector = build_match_selector(:from, from)
+        to_selector = build_match_selector(:to, to)
+        relationship_selector = build_match_selector(:relationship, relationship)
+        cypher = <<-CYPHER
+          MATCH (#{from_selector}) - [#{relationship_selector}] - (#{to_selector})
+          WITH from, to, relationship
+          DELETE relationship
+          RETURN from, to
+        CYPHER
+
+        results = @cypher_client.execute_cypher(cypher, from: from, to: to)
+        results&.first
+      end
+    end
+  end
+end

data/lib/neo4j/http/results.rb

@@ -0,0 +1,27 @@
+require "forwardable"
+
+module Neo4j
+  module Http
+    class Results
+      # Example result set:
+      # [{"columns"=>["n"], "data"=>[{"row"=>[{"name"=>"Foo", "uuid"=>"8c7dcfda-d848-4937-a91a-2e6debad2dd6"}], "meta"=>[{"id"=>242, "type"=>"node", "deleted"=>false}]}]}]
+      #
+      def self.parse(results)
+        columns = results["columns"]
+        data = results["data"]
+
+        data.map do |result|
+          row = result["row"] || []
+          meta = result["meta"] || []
+          compacted_data = row.each_with_index.map do |attributes, index|
+            row_meta = meta[index] || {}
+            attributes["_neo4j_meta_data"] = row_meta if attributes.is_a?(Hash)
+            attributes
+          end
+
+          columns.zip(compacted_data).to_h.with_indifferent_access
+        end
+      end
+    end
+  end
+end

data/lib/neo4j/http/version.rb

@@ -1,5 +1,5 @@
 module Neo4j
   module Http
-    VERSION = "0.0.2"
+    VERSION = "1.0.0.pre"
   end
 end

data/lib/neo4j/http.rb

@@ -1,6 +1,34 @@
 require "neo4j/http/version"
 
+require "active_support"
+require "active_support/core_ext/module/delegation"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/object/json"
+require "active_support/core_ext/hash/indifferent_access"
+
+require "neo4j/http/auth_token"
+require "neo4j/http/client"
+require "neo4j/http/configuration"
+require "neo4j/http/cypher_client"
+require "neo4j/http/object_wrapper"
+require "neo4j/http/node"
+require "neo4j/http/node_client"
+require "neo4j/http/relationship"
+require "neo4j/http/relationship_client"
+require "neo4j/http/results"
+
+require "neo4j/http/errors"
+
 module Neo4j
   module Http
+    extend self
+
+    def config
+      @congiguration ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: neo4j-http
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 1.0.0.pre
 platform: ruby
 authors:
 - Ryan Stawarz
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-04-12 00:00:00.000000000 Z
+date: 2022-04-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -91,6 +91,17 @@ files:
 - README.md
 - Rakefile
 - lib/neo4j/http.rb
+- lib/neo4j/http/auth_token.rb
+- lib/neo4j/http/client.rb
+- lib/neo4j/http/configuration.rb
+- lib/neo4j/http/cypher_client.rb
+- lib/neo4j/http/errors.rb
+- lib/neo4j/http/node.rb
+- lib/neo4j/http/node_client.rb
+- lib/neo4j/http/object_wrapper.rb
+- lib/neo4j/http/relationship.rb
+- lib/neo4j/http/relationship_client.rb
+- lib/neo4j/http/results.rb
 - lib/neo4j/http/version.rb
 homepage: https://github.com/doximity/neo4j-http
 licenses:
@@ -110,11 +121,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.2.32
+rubygems_version: 3.3.11
 signing_key: 
 specification_version: 4
 summary: A simple HTTP client for Neo4j