ashikawa-core 0.6.0 → 0.7.0

data/lib/ashikawa-core/connection.rb

@@ -1,136 +1,79 @@
-require "rest-client"
-require "json"
+require "forwardable"
+require "faraday"
+require "null_logger"
 require "uri"
-require "ashikawa-core/exceptions/index_not_found"
-require "ashikawa-core/exceptions/document_not_found"
-require "ashikawa-core/exceptions/collection_not_found"
-require "ashikawa-core/exceptions/unknown_path"
+require "ashikawa-core/request_preprocessor"
+require "ashikawa-core/response_preprocessor"
 
 module Ashikawa
   module Core
     # A Connection via HTTP to a certain host
     class Connection
+      extend Forwardable
+
       # The host part of the connection
       #
+      # @!method host
       # @return [String]
       # @api public
       # @example Get the host part of the connection
       #   connection = Connection.new("http://localhost:8529")
       #   connection.host # => "localhost"
-      attr_reader :host
+      def_delegator :@connection, :host
 
       # The scheme of the connection
       #
+      # @!method scheme
       # @return [String]
       # @api public
       # @example Get the scheme of the connection
       #   connection = Connection.new("http://localhost:8529")
       #   connection.scheme # => "http"
-      attr_reader :scheme
+      def_delegator :@connection, :scheme
 
       # The port of the connection
       #
+      # @!method port
       # @return [Fixnum]
       # @api public
       # @example Get the port of the connection
       #   connection = Connection.new("http://localhost:8529")
       #   connection.port # => 8529
-      attr_reader :port
-
-      # Username of the connection if using authentication
-      # @note you can set these properties with the `authenticate_with` method
-      #
-      # @return String
-      # @api public
-      # @example Get the username of the connection
-      #   connection = Connection.new("http://localhost:8529")
-      #   connection.authenticate_with(:username => 'james', :password => 'bond')
-      #   connection.username # => 'james'
-      attr_reader :username
-
-      # Password of the connection if using authentication
-      # @note you can set these properties with the `authenticate_with` method
-      #
-      # @return String
-      # @api public
-      # @example Get the password of the connection
-      #   connection = Connection.new("http://localhost:8529")
-      #   connection.authenticate_with(:username => 'james', :password => 'bond')
-      #   connection.password # => 'bond'
-      attr_reader :password
+      def_delegator :@connection, :port
 
       # Initialize a Connection with a given API String
       #
       # @param [String] api_string scheme, hostname and port as a String
+      # @option opts [Object] adapter The Faraday adapter you want to use. Defaults to Default Adapter
+      # @option opts [Object] logger The logger you want to use. Defaults to Null Logger.
       # @api public
       # @example Create a new Connection
       #  connection = Connection.new("http://localhost:8529")
-      def initialize(api_string = "http://localhost:8529")
-        uri     = URI(api_string)
-        @host   = uri.host
-        @port   = uri.port
-        @scheme = uri.scheme
+      def initialize(api_string, opts = {})
+        logger  = opts[:logger]  || NullLogger.instance
+        adapter = opts[:adapter] || Faraday.default_adapter
+        @connection = Faraday.new("#{api_string}/_api") do |connection|
+          connection.request  :ashikawa_request,  logger
+          connection.response :ashikawa_response, logger
+          connection.adapter *adapter
+        end
       end
 
       # Sends a request to a given path returning the parsed result
       # @note prepends the api_string automatically
       #
-      # @param [String] path the path you wish to send a request to.
-      # @option params [Hash] :post POST data in case you want to send a POST request.
-      # @return [Hash] parsed JSON response from the server
+      # @param [string] path the path you wish to send a request to.
+      # @option params [hash] :post post data in case you want to send a post request.
+      # @return [hash] parsed json response from the server
       # @api public
       # @example get request
       #   connection.send_request('/collection/new_collection')
       # @example post request
       #   connection.send_request('/collection/new_collection', :post => { :name => 'new_collection' })
       def send_request(path, params = {})
-        begin
-          raw = raw_result_for(path, params)
-        rescue RestClient::ResourceNotFound
-          resource_not_found_for(path)
-        end
-        JSON.parse(raw)
-      end
-
-      # Raise the fitting ResourceNotFoundException
-      #
-      # @raise [DocumentNotFoundException, CollectionNotFoundException, IndexNotFoundException]
-      # @return nil
-      # @api private
-      def resource_not_found_for(path)
-        path = path.split("/").delete_if { |part| part == "" }
-        resource = path.first
-
-        raise case resource
-          when "document" then DocumentNotFoundException
-          when "collection" then CollectionNotFoundException
-          when "index" then IndexNotFoundException
-          else UnknownPath
-        end
-      end
-
-      # Sends a request to a given path returning the raw result
-      # @note prepends the api_string automatically
-      #
-      # @example get request
-      #   connection.raw_result_for('/collection/new_collection')
-      # @example post request
-      #   connection.raw_result_for('/collection/new_collection', :post => { :name => 'new_collection' })
-      # @param [String] path the path you wish to send a request to.
-      # @option params [Hash] :post POST data in case you want to send a POST request.
-      # @return [String] raw response from the server
-      # @api public
-      def raw_result_for(path, params = {})
-        path   = full_path(path)
-        method = [:post, :put, :delete].find { |method_name|
-          params.has_key?(method_name)
-        } || :get
-
-        if [:post, :put].include?(method)
-          RestClient.send(method, path, params[method].to_json)
-        else
-          RestClient.send(method, path)
-        end
+        method = http_verb(params)
+        result = @connection.public_send(method, path, params[method])
+        result.body
       end
 
       # Checks if authentication for this Connection is active or not
@@ -143,7 +86,7 @@ module Ashikawa
       #   connection.authenticate_with(:username => 'james', :password => 'bond')
       #   connection.authentication? #=> true
       def authentication?
-        !!@username
+        !!@authentication
       end
 
       # Authenticate with given username and password
@@ -157,33 +100,22 @@ module Ashikawa
       #   connection = Connection.new("http://localhost:8529")
       #   connection.authenticate_with(:username => 'james', :password => 'bond')
       def authenticate_with(options = {})
-        if options.key? :username and options.key? :password
-          @username = options[:username]
-          @password = options[:password]
-        else
-          raise ArgumentError, 'missing username or password'
-        end
-
+        raise ArgumentError, 'missing username or password' unless options.key? :username and options.key? :password
+        @authentication = @connection.basic_auth(options[:username], options[:password])
         self
       end
 
-      # Return the full path for a given API path
-      #
-      # @param [String] path The API path
-      # @return [String] Full path
-      # @api public
-      # @example Get the full path
-      #   connection = Connection.new("http://localhost:8529")
-      #   connection.full_path('documents') #=> "http://localhost:8529/_api/documents"
-      #   connection.full_path('/documents') #=> "http://localhost:8529/_api/documents"
-      def full_path(path)
-        prefix = if authentication?
-          "#{@scheme}://#{@username}:#{@password}@#{@host}:#{@port}"
-        else
-          "#{@scheme}://#{@host}:#{@port}"
-        end
+      private
 
-        "#{prefix}/_api/#{path.gsub(/^\//, '')}"
+      # Return the HTTP Verb for the given parameters
+      #
+      # @param [Hash] params The params given to the method
+      # @return [Symbol] The HTTP verb used
+      # @api private
+      def http_verb(params)
+        [:post, :put, :delete].find { |method_name|
+          params.has_key?(method_name)
+        } || :get
       end
     end
   end

data/lib/ashikawa-core/cursor.rb

@@ -8,11 +8,11 @@ module Ashikawa
       include Enumerable
 
       # The ID of the cursor
-      # @return [Int]
+      # @return [String]
       # @api public
       # @example Get the id of the cursor
       #   cursor = Ashikawa::Core::Cursor.new(database, raw_cursor)
-      #   cursor.id #=> 1337
+      #   cursor.id #=> "1337"
       attr_reader :id
 
       # The number of documents
@@ -38,14 +38,20 @@ module Ashikawa
       # Iterate over the documents found by the cursor
       #
       # @yield [document]
-      # @return nil
+      # @return [nil, Enumerator] If no block is given, an Enumerator is returned
       # @api public
       # @example Print all documents
       #   cursor = Ashikawa::Core::Cursor.new(database, raw_cursor)
       #   cursor.each do |document|
       #     p document
       #   end
+      # @example Get an enumerator to iterate over all documents
+      #   cursor = Ashikawa::Core::Cursor.new(database, raw_cursor)
+      #   enumerator = cursor.each
+      #   enumerator.next #=> #<Document ...>
       def each
+        return to_enum(__callee__) unless block_given?
+
         begin
           @current.each do |raw_document|
             yield Document.new(@database, raw_document)
@@ -61,17 +67,18 @@ module Ashikawa
       #   cursor = Ashikawa::Core::Cursor.new(database, raw_cursor)
       #   cursor.delete
       def delete
-        @database.send_request("/cursor/#{@id}", :delete => {})
+        @database.send_request("cursor/#{@id}", :delete => {})
       end
 
       private
 
       # Pull the raw data from the cursor into this object
       #
+      # @param [Hash] raw_cursor
       # @return self
       # @api private
       def parse_raw_cursor(raw_cursor)
-        @id       = raw_cursor['id'].to_i if raw_cursor.has_key?('id')
+        @id       = raw_cursor['id']
         @has_more = raw_cursor['hasMore']
         @length   = raw_cursor['count'].to_i if raw_cursor.has_key?('count')
         @current  = raw_cursor['result']
@@ -84,7 +91,7 @@ module Ashikawa
       # @api private
       def next_batch
         return false unless @has_more
-        raw_cursor = @database.send_request("/cursor/#{@id}", :put => {})
+        raw_cursor = @database.send_request("cursor/#{@id}", :put => {})
         parse_raw_cursor(raw_cursor)
       end
     end

data/lib/ashikawa-core/database.rb

@@ -1,4 +1,4 @@
-require "ashikawa-core/exceptions/collection_not_found"
+require "ashikawa-core/exceptions/client_error/resource_not_found/collection_not_found"
 require "ashikawa-core/collection"
 require "ashikawa-core/connection"
 require "ashikawa-core/cursor"
@@ -6,8 +6,16 @@ require "forwardable"
 
 module Ashikawa
   module Core
+    # Configuration of Ashikawa::Core
+    Configuration = Struct.new(:url, :connection, :logger, :adapter)
+
     # An ArangoDB database
     class Database
+      COLLECTION_TYPES = {
+        :document => 2,
+        :edge => 3
+      }
+
       extend Forwardable
 
       # Delegate sending requests to the connection
@@ -19,19 +27,26 @@ module Ashikawa
 
       # Initializes the connection to the database
       #
-      # @param [Connection, String] connection A Connection object or a String to create a Connection object.
       # @api public
       # @example Access a Database by providing the URL
-      #  database = Ashikawa::Core::Database.new("http://localhost:8529")
+      #   database = Ashikawa::Core::Database.new do |config|
+      #     config.url = "http://localhost:8529"
+      #   end
       # @example Access a Database by providing a Connection
-      #  connection = Connection.new("http://localhost:8529")
-      #  database = Ashikawa::Core::Database.new connection
-      def initialize(connection)
-        if connection.class == String
-          @connection = Ashikawa::Core::Connection.new(connection)
-        else
-          @connection = connection
-        end
+      #   connection = Connection.new("http://localhost:8529")
+      #   database = Ashikawa::Core::Database.new do |config|
+      #     config.connection = connection
+      #   end
+      # @example Access a Database with a logger and custom HTTP adapter
+      #   database = Ashikawa::Core::Database.new do |config|
+      #     config.url = "http://localhost:8529"
+      #     config.adapter = my_adapter
+      #     config.logger = my_logger
+      #   end
+      def initialize()
+        configuration = Ashikawa::Core::Configuration.new
+        yield(configuration)
+        @connection = configuration.connection || setup_new_connection(configuration.url, configuration.logger, configuration.adapter)
       end
 
       # Returns a list of all collections defined in the database
@@ -44,8 +59,26 @@ module Ashikawa
       #   database["b"]
       #   database.collections # => [ #<Collection name="a">, #<Collection name="b">]
       def collections
-        server_response = send_request("/collection")
-        server_response["collections"].map { |collection| Ashikawa::Core::Collection.new(self, collection) }
+        response = send_request("collection")
+        response["collections"].map { |collection| Ashikawa::Core::Collection.new(self, collection) }
+      end
+
+      # Create a Collection based on name
+      #
+      # @param [String] collection_identifier The desired name of the collection
+      # @option opts [Boolean] :is_volatile Should the collection be volatile? Default is false
+      # @option opts [Boolean] :content_type What kind of content should the collection have? Default is :document
+      # @return [Collection]
+      # @api public
+      # @example Create a new, volatile collection
+      #   database = Ashikawa::Core::Database.new("http://localhost:8529")
+      #   database.create_collection("a", :isVolatile => true) # => #<Collection name="a">
+      def create_collection(collection_identifier, opts={})
+        params = { :name => collection_identifier }
+        params[:isVolatile] = true if opts[:is_volatile] == true
+        params[:type] = COLLECTION_TYPES[opts[:content_type]] if opts.has_key?(:content_type)
+        response = send_request("collection", :post => params)
+        Ashikawa::Core::Collection.new(self, response)
       end
 
       # Get or create a Collection based on name or ID
@@ -59,16 +92,18 @@ module Ashikawa
       # @example Get a Collection from the database by ID
       #   database = Ashikawa::Core::Database.new("http://localhost:8529")
       #   database["7254820"] # => #<Collection id=7254820>
-      def [](collection_identifier)
+      def collection(collection_identifier)
         begin
-          server_response = send_request("/collection/#{collection_identifier}")
+          response = send_request("collection/#{collection_identifier}")
         rescue CollectionNotFoundException
-          server_response = send_request("/collection", :post => { :name => collection_identifier })
+          response = send_request("collection", :post => { :name => collection_identifier })
         end
 
-        Ashikawa::Core::Collection.new(self, server_response)
+        Ashikawa::Core::Collection.new(self, response)
       end
 
+      alias :[] :collection
+
       # Return a Query initialized with this database
       #
       # @return [Query]
@@ -79,6 +114,21 @@ module Ashikawa
       def query
         Query.new(self)
       end
+
+      # Setup the connection object
+      #
+      # @param [String] url
+      # @param [Logger] logger
+      # @param [Adapter] adapter
+      # @return [Connection]
+      # @api private
+      def setup_new_connection(url, logger, adapter)
+        raise(ArgumentError, "Please provide either an url or a connection to setup the database") if url.nil?
+        Ashikawa::Core::Connection.new(url, {
+          :logger => logger,
+          :adapter => adapter
+        })
+      end
     end
   end
 end

data/lib/ashikawa-core/document.rb

@@ -1,21 +1,30 @@
-require 'ashikawa-core/exceptions/document_not_found'
+require 'ashikawa-core/exceptions/client_error/resource_not_found/document_not_found'
 
 module Ashikawa
   module Core
     # A certain Document within a certain Collection
     class Document
-      # The ID of the document without the Collection prefix
+      # The ID of the document (this includes the Collection prefix)
       #
-      # @return [Int]
+      # @return [String]
       # @api public
       # @example Get the ID for a Document
       #   document = Ashikawa::Core::Document.new(database, raw_document)
-      #   document.id # => 2345678
+      #   document.id # => "my_fancy_collection/2345678"
       attr_reader :id
 
+      # The key of the document (No collection prefix)
+      #
+      # @return [String]
+      # @api public
+      # @example Get the key for a Document
+      #   document = Ashikawa::Core::Document.new(database, raw_document)
+      #   document.key # => "2345678"
+      attr_reader :key
+
       # The current revision of the document
       #
-      # @return [Int]
+      # @return [String]
       # @api public
       # @example Get the Revision for a Document
       #   document = Ashikawa::Core::Document.new(database, raw_document)
@@ -31,9 +40,7 @@ module Ashikawa
       #   document = Ashikawa::Core::Document.new(database, raw_document)
       def initialize(database, raw_document)
         @database = database
-        @collection_id, @id = raw_document['_id'].split('/').map { |id| id.to_i } unless raw_document['_id'].nil?
-        @revision = raw_document['_rev'].to_i unless raw_document['_rev'].nil?
-        @content = raw_document.delete_if { |key, value| key.start_with?("_") }
+        parse_raw_document(raw_document)
       end
 
       # Raises an exception if the document is not persisted
@@ -69,7 +76,7 @@ module Ashikawa
       #   document.delete
       def delete
         check_if_persisted!
-        @database.send_request("document/#{@collection_id}/#{@id}", :delete => {})
+        send_request_for_document(:delete => {})
       end
 
       # Update the value of an attribute (Does not write to database)
@@ -107,7 +114,31 @@ module Ashikawa
       #   document.save
       def save()
         check_if_persisted!
-        @database.send_request("document/#{@collection_id}/#{@id}", :put => @content)
+        send_request_for_document(:put => @content)
+      end
+
+      protected
+
+      # Parse information returned from the server
+      #
+      # @param [Hash] raw_document
+      # @return self
+      # @api private
+      def parse_raw_document(raw_document)
+        @id       = raw_document['_id']
+        @key      = raw_document['_key']
+        @revision = raw_document['_rev']
+        @content  = raw_document.delete_if { |key, value| key.start_with?("_") }
+        self
+      end
+
+      # Send a request for this document with the given opts
+      #
+      # @param [Hash] opts Options for this request
+      # @return [Hash] The parsed response from the server
+      # @api private
+      def send_request_for_document(opts = {})
+        @database.send_request("document/#{@id}", opts)
       end
     end
   end