ashikawa-core 0.12.0 → 0.13.0

data/lib/ashikawa-core/graph.rb

@@ -0,0 +1,222 @@
+# -*- encoding : utf-8 -*-
+
+require 'ashikawa-core/vertex_collection'
+require 'ashikawa-core/edge_collection'
+
+module Ashikawa
+  module Core
+    # A certain graph in the database.
+    #
+    # @note All CRUD operations on related collections (edges and vertices) must be performed
+    #       through their corresponding graph class. Not doing so will eventually lead to inconsistency
+    #       and data corruption.
+    # @see http://docs.arangodb.org/HttpGharial/README.html
+    class Graph
+      extend Forwardable
+
+      # Sending requests is delegated to the database
+      def_delegator :@database, :send_request
+
+      # Prepared AQL statement for neighbors function on a specific edge collections
+      SPECIFIC_NEIGHBORS_AQL = <<-AQL.gsub(/^[ \t]*/, '')
+      FOR n IN GRAPH_NEIGHBORS(@graph, { _key:@vertex_key }, {edgeCollectionRestriction: @edge_collection})
+        RETURN n.vertex
+      AQL
+
+      # Prepared AQL statement for neighbors function on ALL edge collections
+      ALL_NEIGHBORS_AQL = <<-AQL.gsub(/^[ \t]*/, '')
+      FOR n IN GRAPH_NEIGHBORS(@graph, { _key:@vertex_key }, {})
+        RETURN n.vertex
+      AQL
+
+      # The database the Graph belongs to
+      #
+      # @return [Database] The associated database
+      # @api public
+      # @example
+      #   database = Ashikawa::Core::Database.new('http://localhost:8529')
+      #   raw_graph = {
+      #     'name' => 'example_1',
+      #     'edgeDefinitions' => [],
+      #     'orphanCollections' => []
+      #   }
+      #   graph = Ashikawa::Core::Graph.new(database, raw_collection)
+      #   graph.database #=> #<Database: ...>
+      attr_reader :database
+
+      # The name of the graph
+      #
+      # @return [String] The name of the graph
+      # @api public
+      # @example
+      #   database = Ashikawa::Core::Database.new('http://localhost:8529')
+      #   raw_graph = {
+      #     'name' => 'example_1',
+      #     'edgeDefinitions' => [],
+      #     'orphanCollections' => []
+      #   }
+      #   graph = Ashikawa::Core::Graph.new(database, raw_collection)
+      #   graph.name #=> 'example_1
+      attr_reader :name
+
+      # The revision of the Graph
+      #
+      # @return [String] The revision of the Graph
+      # @api public
+      attr_reader :revision
+
+      # The edge definitions for this Graph
+      #
+      # @return [Hash] The edge definitons of this Graph as a simple data structure
+      # @api public
+      attr_reader :edge_definitions
+
+      # Initialize a new graph instance
+      #
+      # @param [Database] database A reference to the database this graph belongs to
+      # @param [Hash] raw_graph The parsed JSON response from the database representing the graph
+      def initialize(database, raw_graph)
+        @database = database
+        parse_raw_graph(raw_graph)
+      end
+
+      def delete(options = {})
+        drop_collections = options.fetch(:drop_collections) { false }
+        send_request("gharial/#@name", delete: { dropCollections: drop_collections })
+      end
+
+      # Gets a list of vertex collections
+      #
+      # Due to the fact we need to fetch each of the collections by hand this will just return an
+      # enumerator which will lazily fetch the collections from the database.
+      #
+      # @return [Enumerator] An Enumerator referencing the vertex collections
+      def vertex_collections
+        Enumerator.new do |yielder|
+          vertex_collection_names.each do |collection_name|
+            yielder.yield vertex_collection(collection_name)
+          end
+        end
+      end
+
+      # The list of names of the vertex collections
+      #
+      # @return [Array] Names of all vertex collections
+      def vertex_collection_names
+        @orphan_collections | @edge_definitions.map { |edge_def| edge_def.values_at('from', 'to') }.flatten
+      end
+
+      # Adds a vertex collection to this graph
+      #
+      # If the collection does not yet exist it will be created. If it already exists it will just be added
+      # to the list of vertex collections.
+      #
+      # @param [String] collection_name The name of the vertex collection
+      # @return [VertexCollection] The newly created collection
+      def add_vertex_collection(collection_name)
+        response = send_request("gharial/#@name/vertex", post: { collection: collection_name })
+        parse_raw_graph(response['graph'])
+        vertex_collection(collection_name)
+      end
+
+      # Fetches a vertex collection associated with graph from the database
+      #
+      # @param [String] collection_name The name of the collection
+      # @return [VertexCollection] The fetched VertexCollection
+      def vertex_collection(collection_name)
+        raw_collection = send_request("collection/#{collection_name}")
+        VertexCollection.new(database, raw_collection, self)
+      end
+
+      # Checks if a collection is present in the list of vertices
+      #
+      # @param [String] collection_name The name of the collection to query
+      # @return [Boolean] True if the collection is present, false otherwise
+      def has_vertex_collection?(collection_name)
+        vertex_collection_names.any? { |name| name == collection_name }
+      end
+
+      # Gets a list of edge collections
+      #
+      # Due to the fact we need to fetch each of the collections by hand this will just return an
+      # enumerator which will lazily fetch the collections from the database.
+      #
+      # @return [Enumerator] An Enumerator referencing the edge collections
+      def edge_collections
+        Enumerator.new do |yielder|
+          edge_collection_names.each do |collection_name|
+            yielder.yield edge_collection(collection_name)
+          end
+        end
+      end
+
+      # The list of names of the edge collections
+      #
+      # @return [Array] Names of all edge collections
+      def edge_collection_names
+        @edge_definitions.map { |edge_def| edge_def['collection'] }
+      end
+
+      # Adds an edge definition to this Graph
+      #
+      # @param [Symbol] collection_name The name of the resulting edge collection
+      # @param [Hash] directions The specification between which vertices the edges should be created
+      # @option [Array<Symbol>] :from A list of collections names from which the edge directs
+      # @option [Array<Symbol>] :to A list of collections names to which the edge directs
+      def add_edge_definition(collection_name, directions)
+        create_options = {
+          collection: collection_name,
+          from:       directions[:from],
+          to:         directions[:to]
+        }
+
+        response = send_request("gharial/#@name/edge", post: create_options)
+        parse_raw_graph(response['graph'])
+        edge_collection(collection_name)
+      end
+
+      # Fetches an edge collection from the database
+      #
+      # @param [String] collection_name The name of the desired edge
+      # @return [EdgeCollection] The edge collection for the given name
+      def edge_collection(collection_name)
+        response = send_request("collection/#{collection_name}")
+        EdgeCollection.new(database, response, self)
+      end
+
+      # Return a Cursor representing the neighbors for the given document and optional edge collections
+      #
+      # @param [Document] vertex The start vertex
+      # @param [options] options Additional options like restrictions on the edge collections
+      # @option [Array<Symbol>] :edges A list of edge collection to restrict the neighbors function on
+      # @return [Cursor] The cursor to the query result
+      def neighbors(vertex, options = {})
+        bind_vars = {
+          graph: name,
+          vertex_key: vertex.key
+        }
+        aql_string = ALL_NEIGHBORS_AQL
+
+        if options.has_key?(:edges)
+          aql_string = SPECIFIC_NEIGHBORS_AQL
+          bind_vars[:edge_collection] = [options[:edges]].flatten
+        end
+
+        database.query.execute(aql_string, bind_vars: bind_vars)
+      end
+
+      private
+
+      # Parses the raw graph structure as returned from the database
+      #
+      # @param [Hash] raw_graph The structure as returned from the database
+      # @api private
+      def parse_raw_graph(raw_graph)
+        @name               = raw_graph['name'] || raw_graph['_key']
+        @revision           = raw_graph['_rev']
+        @edge_definitions   = raw_graph.fetch('edgeDefinitions') { [] }
+        @orphan_collections = raw_graph.fetch('orphanCollections') { [] }
+      end
+    end
+  end
+end

data/lib/ashikawa-core/version.rb

@@ -2,6 +2,16 @@
 module Ashikawa
   module Core
     # Current version of Ashikawa::Core
-    VERSION = '0.12.0'
+    VERSION = '0.13.0'
+
+    # The lowest supported ArangoDB major version
+    ARANGODB_MAJOR_VERSION = 2
+
+    # The lowest supported ArangoDB minor version
+    ARANGODB_MINOR_VERSION = 2
+
+    def self.api_compatibility_version
+      (ARANGODB_MAJOR_VERSION * 10_000 + ARANGODB_MINOR_VERSION * 100).to_s
+    end
   end
 end

data/lib/ashikawa-core/vertex_collection.rb

@@ -0,0 +1,35 @@
+# -*- encoding : utf-8 -*-
+
+require 'ashikawa-core/collection'
+require 'ashikawa-core/exceptions/client_error/resource_not_found/collection_not_in_graph'
+
+module Ashikawa
+  module Core
+    # A vertex collection as it is returned from a graph
+    #
+    # @note This is basically just a regular collection with some additional attributes and methods to ease
+    #       working with collections in the graph module.
+    class VertexCollection < Collection
+      # The Graph instance this VertexCollection was originally fetched from
+      #
+      # @return [Graph] The Graph instance the collection was fetched from
+      # @api public
+      attr_reader :graph
+
+      # Create a new VertexCollection object
+      #
+      # @param [Database] database The database the connection belongs to
+      # @param [Hash] raw_collection The raw collection returned from the server
+      # @param [Graph] graph The graph from which this collection was fetched
+      # @raise [CollectionNotInGraphException] If the collection has not beed added to the graph yet
+      # @note You should not create instance manually but rather use Graph#add_vertex_collection
+      # @api public
+      def initialize(database, raw_collection, graph)
+        super(database, raw_collection)
+        @graph = graph
+
+        raise CollectionNotInGraphException unless @graph.has_vertex_collection?(name)
+      end
+    end
+  end
+end

data/lib/ashikawa-core/x_arango_version.rb

@@ -0,0 +1,26 @@
+# -*- encoding : utf-8 -*-
+
+module Ashikawa
+  module Core
+    # Sets the ArangoDB API compatibility header
+    class XArangoVersion < Faraday::Middleware
+      # The name of the x-arango-version header field
+      HEADER = 'X-Arango-Version'.freeze
+
+      # Initializes the middleware
+      #
+      # @param [Callable] app The faraday app
+      def initialize(app)
+        super(app)
+      end
+
+      # Sets the `x-arango-version` for each request
+      def call(env)
+        env[:request_headers][HEADER] = Ashikawa::Core.api_compatibility_version
+        @app.call(env)
+      end
+    end
+
+    Faraday::Request.register_middleware x_arango_version: -> { XArangoVersion }
+  end
+end

data/spec/acceptance/graph_spec.rb

@@ -0,0 +1,89 @@
+# -*- encoding : utf-8 -*-
+require 'acceptance/spec_helper'
+
+describe 'Graphs' do
+  subject { DATABASE.graph 'ponyville' }
+
+  let(:ponies) { subject.add_vertex_collection(:ponies) }
+  let(:places) { subject.add_vertex_collection(:places) }
+
+  let(:pinkie_pie) { ponies.create_document(name: 'Pinkie Pie', color: 'pink') }
+  let(:rainbow_dash) { ponies.create_document(name: 'Rainbow Dash', color: 'blue') }
+
+  let(:crystal_empire) { places.create_document(name: 'Crystal Empire') }
+  let(:cloudsdale) { places.create_document(name: 'Cloudsdale') }
+  let(:manehatten) { places.create_document(name: 'Manehatten') }
+
+  let(:friends_with) { subject.add_edge_definition(:friends_with, from: [:ponies], to: [:ponies]) }
+  let(:visited)      { subject.add_edge_definition(:visited, from: [:ponies], to: [:places]) }
+
+  before do
+    # required to create the required collections
+    ponies
+    places
+    friends_with
+    visited
+  end
+
+  after do
+    subject.delete(drop_collections: true)
+  end
+
+  it 'should have some basic information about the graph' do
+    edge_definitions = [
+      {
+        'collection' => 'visited',
+        'from'       => ['ponies'],
+        'to'         => ['places']
+      },
+      {
+        'collection' => 'friends_with',
+        'from'       => ['ponies'],
+        'to'         => ['ponies']
+      }
+    ]
+
+    expect(subject.name).to eq 'ponyville'
+    expect(subject.revision).not_to be_nil
+    expect(subject.edge_definitions).to match_array edge_definitions
+  end
+
+  it 'should know the vertex collections' do
+    expect(subject.vertex_collections).to include ponies
+    expect(subject.vertex_collections).to include places
+  end
+
+  it 'should know the edge collections' do
+    expect(subject.edge_collections).to include friends_with
+    expect(subject.edge_collections).to include visited
+  end
+
+  context 'connected vertices' do
+    before :each do
+      # There are only directed graphs
+      subject.edge_collection(:friends_with).add(from: pinkie_pie, to: rainbow_dash)
+      subject.edge_collection(:friends_with).add(from: rainbow_dash, to: pinkie_pie)
+
+      subject.edge_collection(:visited).add(from: pinkie_pie, to: crystal_empire)
+      subject.edge_collection(:visited).add(from: rainbow_dash, to: cloudsdale)
+      subject.edge_collection(:visited).add(from: rainbow_dash, to: crystal_empire)
+      subject.edge_collection(:visited).add(from: rainbow_dash, to: manehatten)
+    end
+
+    it 'should know all their neighbors' do
+      neighbors = ['Pinkie Pie', 'Pinkie Pie', 'Cloudsdale', 'Manehatten', 'Crystal Empire']
+      expect(subject.neighbors(rainbow_dash).map { |d| d['name'] }).to eq neighbors
+    end
+
+    it 'should know neighbors by type' do
+      neighbors = ['Cloudsdale', 'Manehatten', 'Crystal Empire']
+      expect(subject.neighbors(rainbow_dash, edges: :visited).map { |d| d['name'] }).to eq neighbors
+    end
+
+    it 'should remove edges between vertices' do
+      neighbors = ['Cloudsdale', 'Crystal Empire']
+      subject.edge_collection(:visited).remove(from: rainbow_dash, to: manehatten)
+      expect(subject.neighbors(rainbow_dash, edges: :visited).map { |d| d['name'] }).to eq neighbors
+    end
+  end
+end

data/spec/acceptance/spec_helper.rb

@@ -5,6 +5,8 @@ $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 require 'ashikawa-core'
 require 'logging'
 
+RANDOM_DB_PREFIX = 'ashikawa_spec_db_'
+
 PORT = ENV.fetch('ARANGODB_PORT', 8529)
 USERNAME = ENV.fetch('ARANGODB_USERNAME', 'root')
 PASSWORD = ENV.fetch('ARANGODB_PASSWORD', '')
@@ -33,7 +35,11 @@ end
 def database_with_random_name
   # This results in a database that has a valid name according to:
   # https://www.arangodb.org/manuals/2/NamingConventions.html#DatabaseNames
-  database_with_name("a#{rand.to_s[2, 10]}")
+  database_with_name("#{RANDOM_DB_PREFIX}#{rand.to_s[2, 10]}")
+end
+
+def random_databases
+  SYSTEM_DATABASE.all_databases.grep(/^#{RANDOM_DB_PREFIX}/).map(&method(:database_with_name))
 end
 
 # The database for the general specs
@@ -50,11 +56,18 @@ RSpec.configure do |config|
     c.syntax = :expect
   end
 
-  config.before(:each) do
+  config.before(:suite) do
     begin
       DATABASE.create
     rescue Ashikawa::Core::ClientError
     end
+  end
+
+  config.before(:each) do
     DATABASE.truncate
   end
+
+  config.after(:suite) do
+    random_databases.each(&:drop)
+  end
 end

data/spec/unit/collection_spec.rb

@@ -235,21 +235,29 @@ describe Ashikawa::Core::Collection do
 
     its(:content_type) { should be(:document) }
 
+    context 'building the content classes' do
+      it 'should build documents' do
+        expect(Ashikawa::Core::Document).to receive(:new)
+          .with(database, raw_document)
+
+        subject.build_content_class(raw_document)
+      end
+    end
+
     context 'when using the key' do
       let(:key) { 333 }
 
       it 'should receive a document by ID via fetch' do
         expect(database).to receive(:send_request)
           .with('document/60768679/333', {})
-        expect(Ashikawa::Core::Document).to receive(:new)
+        expect(subject).to receive(:build_content_class)
 
         subject.fetch(key)
       end
 
       it 'should receive a document by ID via []' do
-        expect(database).to receive(:send_request)
-          .with('document/60768679/333', {})
-        expect(Ashikawa::Core::Document).to receive(:new)
+        expect(subject).to receive(:fetch)
+          .with(key)
 
         subject[key]
       end
@@ -318,18 +326,25 @@ describe Ashikawa::Core::Collection do
 
     its(:content_type) { should be(:edge) }
 
+    context 'building the content classes' do
+      it 'should build documents' do
+        expect(Ashikawa::Core::Edge).to receive(:new)
+          .with(database, raw_document)
+
+        subject.build_content_class(raw_document)
+      end
+    end
+
     it 'should receive an edge by ID via fetch' do
       expect(database).to receive(:send_request)
         .with('edge/60768679/333', {})
-      expect(Ashikawa::Core::Edge).to receive(:new)
+      expect(subject).to receive(:build_content_class)
 
       subject.fetch(333)
     end
 
     it 'should receive an edge by ID via []' do
-      expect(database).to receive(:send_request)
-        .with('edge/60768679/333', {})
-      expect(Ashikawa::Core::Edge).to receive(:new)
+      expect(subject).to receive(:fetch).with(333)
 
       subject[333]
     end