guacamole 0.2.0 → 0.3.0

data/lib/guacamole/collection.rb

@@ -24,7 +24,7 @@ module Guacamole
     #   Convert a model to a document to save it to the database
     #
     #   You can use this method for your hand made storage or update methods.
-    #   Most of the time it makes more sense to call save or replace though,
+    #   Most of the time it makes more sense to call save or update though,
     #   they do the conversion and handle the communication with the database
     #
     #   @param [Model] model The model to be converted
@@ -97,10 +97,10 @@ module Guacamole
       def by_key(key)
         raise Ashikawa::Core::DocumentNotFoundException unless key
 
-        mapper.document_to_model connection.fetch(key)
+        mapper.document_to_model fetch_document(key)
       end
 
-      # Persist a model in the collection or replace it in the database, depending if it is already persisted
+      # Persist a model in the collection or update it in the database, depending if it is already persisted
       #
       # * If {Model#persisted? model#persisted?} is `false`, the model will be saved in the collection.
       #   Timestamps, revision and key will be set on the model.
@@ -109,7 +109,7 @@ module Guacamole
       #   by key. This will change the updated_at timestamp and revision
       #   of the provided model.
       #
-      # See also {#create create} and {#replace replace} for explicit usage.
+      # See also {#create create} and {#update update} for explicit usage.
       #
       # @param [Model] model The model to be saved
       # @return [Model] The provided model
@@ -117,12 +117,12 @@ module Guacamole
       #   podcast = Podcast.new(title: 'Best Show', guest: 'Dirk Breuer')
       #   PodcastsCollection.save(podcast)
       #   podcast.key #=> '27214247'
-      # @example Get a podcast, update its title, replace it
+      # @example Get a podcast, update its title, update it
       #   podcast = PodcastsCollection.by_key('27214247')
       #   podcast.title = 'Even better'
       #   PodcastsCollection.save(podcast)
       def save(model)
-        model.persisted? ? replace(model) : create(model)
+        model.persisted? ? update(model) : create(model)
       end
 
       # Persist a model in the collection
@@ -139,13 +139,17 @@ module Guacamole
       def create(model)
         return false unless model.valid?
 
-        add_timestamps_to_model(model)
-        create_document_from(model)
+        callbacks(model).run_callbacks :save, :create do
+          create_document_from(model)
+        end
         model
       end
 
       # Delete a model from the database
       #
+      # If you provide a key, we will fetch the model first to run the `:delete`
+      # callbacks for that model.
+      #
       # @param [String, Model] model_or_key The key of the model or a model
       # @return [String] The key
       # @example Delete a podcast by key
@@ -153,33 +157,47 @@ module Guacamole
       # @example Delete a podcast by model
       #   PodcastsCollection.delete(podcast)
       def delete(model_or_key)
-        key = if model_or_key.respond_to? :key
-                model_or_key.key
-              else
-                model_or_key
-              end
-        fetch_document(key).delete
-        key
+        document, model = consistently_get_document_and_model(model_or_key)
+
+        callbacks(model).run_callbacks :delete do
+          document.delete
+        end
+
+        model.key
+      end
+
+      # Gets the document **and** model instance for either a given model or a key.
+      #
+      # @api private
+      # @param [String, Model] model_or_key The key of the model or a model
+      # @return [Array<Ashikawa::Core::Document, Model>] Both the document and model for the given input
+      def consistently_get_document_and_model(model_or_key)
+        if model_or_key.respond_to?(:key)
+          [fetch_document(model_or_key.key), model_or_key]
+        else
+          [document = fetch_document(model_or_key), mapper.document_to_model(document)]
+        end
       end
 
-      # Replace a model in the database with its new version
+      # Update a model in the database with its new version
       #
-      # Replaces the currently saved version of the model with
+      # Updates the currently saved version of the model with
       # its new version. It searches for the entry in the database
       # by key. This will change the updated_at timestamp and revision
       # of the provided model.
       #
-      # @param [Model] model The model to be replaced
+      # @param [Model] model The model to be updated
       # @return [Model] The model
-      # @example Get a podcast, update its title, replace it
+      # @example Get a podcast, update its title, update it
       #   podcast = PodcastsCollection.by_key('27214247')
       #   podcast.title = 'Even better'
-      #   PodcastsCollection.replace(podcast)
-      def replace(model)
+      #   PodcastsCollection.update(podcast)
+      def update(model)
         return false unless model.valid?
 
-        model.updated_at = Time.now
-        replace_document_from(model)
+        callbacks(model).run_callbacks :save, :update do
+          replace_document_from(model)
+        end
         model
       end
 
@@ -269,15 +287,6 @@ module Guacamole
         mapper.instance_eval(&block)
       end
 
-      # Timestamp a fresh model
-      #
-      # @api private
-      def add_timestamps_to_model(model)
-        timestamp = Time.now
-        model.created_at = timestamp
-        model.updated_at = timestamp
-      end
-
       # Create a document from a model
       #
       # @api private
@@ -347,6 +356,15 @@ module Guacamole
 
         document
       end
+
+      # Gets the callback class for the given model class
+      #
+      # @api private
+      # @param [Model] model The model to look up callbacks for
+      # @return [Callbacks] An instance of the registered callback class
+      def callbacks(model)
+        Callbacks.callbacks_for(model)
+      end
     end
   end
 end

data/lib/guacamole/configuration.rb

@@ -6,6 +6,7 @@ require 'logger'
 require 'forwardable'
 require 'ashikawa-core'
 require 'yaml'
+require 'erb'
 
 require 'guacamole/document_model_mapper'
 
@@ -68,6 +69,39 @@ module Guacamole
   #
   #   @return [Object] current environment
   class Configuration
+    # A wrapper object to handle both configuration from a connection URI and a hash.
+    class ConfigStruct
+      attr_reader :url, :username, :password, :database
+
+      def initialize(config_hash_or_url)
+        case config_hash_or_url
+        when Hash
+          init_from_hash(config_hash_or_url)
+        when String
+          init_from_uri_string(config_hash_or_url)
+        end
+      end
+
+      private
+
+      def init_from_uri_string(uri_string)
+        uri       = URI.parse(uri_string)
+        @username = uri.user
+        @password = uri.password
+        uri.user  = nil
+        uri.path.match(%r{/_db/(?<db_name>\w+)/?}) { |match| @database = match[:db_name] }
+
+        @url      = "#{uri.scheme}://#{uri.hostname}:#{uri.port}"
+      end
+
+      def init_from_hash(hash)
+        @username = hash['username']
+        @password = hash['password']
+        @database = hash['database']
+        @url      = "#{hash['protocol']}://#{hash['host']}:#{hash['port']}"
+      end
+    end
+
     # @!visibility protected
     attr_accessor :database, :default_mapper, :logger
 
@@ -96,11 +130,51 @@ module Guacamole
       #
       # @param [String] file_name The file name of the configuration
       def load(file_name)
-        config = YAML.load_file(file_name)[current_environment.to_s]
+        yaml_content  = process_file_with_erb(file_name)
+        config        = YAML.load(yaml_content)[current_environment.to_s]
+
+        create_database_connection(build_config(config))
+        warn_if_database_was_not_yet_created
+      end
 
-        self.database = create_database_connection_from(config)
+      # Configures the database connection with a connection URI
+      #
+      # @params [String] connection_uri A URI to describe the database connection
+      def configure_with_uri(connection_uri)
+        create_database_connection build_config(connection_uri)
+      end
+
+      # Creates a config struct from either a hash or a DATABASE_URL
+      #
+      # @param [Hash, String] config Either a hash containing config params or a complete connection URI
+      # @return [ConfigStruct] A simple object with the required connection parameters
+      # @api private
+      def build_config(config)
+        ConfigStruct.new config
       end
 
+      # Creates the actual Ashikawa::Core::Database instance
+      #
+      # @param [ConfigStruct] config The config object to extract the config parameters from
+      # @return [Ashikawa::Core::Database] The configured database instance
+      # @api private
+      def create_database_connection(config)
+        self.database = Ashikawa::Core::Database.new do |arango_config|
+          arango_config.url           = config.url
+          arango_config.username      = config.username
+          arango_config.password      = config.password
+          arango_config.database_name = config.database if config.database
+          arango_config.logger        = logger
+        end
+      end
+
+      # The current environment.
+      #
+      # If you're in a Rails application this will return the Rails environment. If Rails is
+      # not available it will use `RACK_ENV` and if that is not available it will fall back to
+      # `GUACAMOLE_ENV`. This allows you to use Guacamole not only in Rails.
+      #
+      # @return [String] The current environment
       def current_environment
         return Rails.env if defined?(Rails)
         ENV['RACK_ENV'] || ENV['GUACAMOLE_ENV']
@@ -112,19 +186,6 @@ module Guacamole
         @configuration ||= new
       end
 
-      def create_database_connection_from(config)
-        Ashikawa::Core::Database.new do |arango_config|
-          arango_config.url      = db_url_from(config)
-          arango_config.username = config['username']
-          arango_config.password = config['password']
-          arango_config.logger   = logger
-        end
-      end
-
-      def db_url_from(config)
-        "#{config['protocol']}://#{config['host']}:#{config['port']}/_db/#{config['database']}"
-      end
-
       def rails_logger
         return Rails.logger if defined?(Rails)
       end
@@ -134,6 +195,22 @@ module Guacamole
         default_logger.level = Logger::INFO
         default_logger
       end
+
+      # Prints a warning to STDOUT and the logger if the configured database could not be found
+      #
+      # @note Ashikawa::Core doesn't know if the database is not present or the collection was not created.
+      #       Thus we will just give the user a warning if the database was not found upon initialization.
+      def warn_if_database_was_not_yet_created
+        database.send_request 'version' # The /version is database specific
+      rescue Ashikawa::Core::ResourceNotFound
+        warning_msg = "[WARNING] The configured database ('#{database.name}') cannot be found. Please run `rake db:create` to create it."
+        logger.warn warning_msg
+        warn warning_msg
+      end
+
+      def process_file_with_erb(file_name)
+        ERB.new(File.read(file_name)).result
+      end
     end
 
     # A list of active experimental features. Refer to `AVAILABLE_EXPERIMENTAL_FEATURES` to see

data/lib/guacamole/model.rb

@@ -70,6 +70,19 @@ module Guacamole
   #       attribute :contributor_names, Array[String]
   #     end
   #
+  # @!method self.callbacks(name_of_callbacks_class)
+  #   Registers a single callback class to be used for this model
+  #
+  #   @api public
+  #   @param [Symbol] name_of_callbacks_class The name of the the callback class to be used
+  #
+  #   @example
+  #     class BlogPost
+  #       include Guacamole::Model
+  #
+  #       callbacks :blog_post_callbacks
+  #     end
+  #
   # @!method self.validates
   #   This method is a shortcut to all default validators and any custom validator classes ending in 'Validator'
   #
@@ -164,6 +177,12 @@ module Guacamole
   #
   #   @param [Model] other the model to compare with
   #   @api public
+  #
+  # @!method callbacks
+  #   Returns the registered callback class instantiated with `self`
+  #
+  #   @api private
+  #   @return [Callback] The registered callback class instantiated with `self`
   module Model
     extend ActiveSupport::Concern
     # @!parse include ActiveModel::Validations
@@ -172,9 +191,16 @@ module Guacamole
     # I know that this is technically not true, but the reality is a parse error:
     # @!parse include Virtus
 
+    module ClassMethods
+      def callbacks(name_of_callbacks_class)
+        callback_class = name_of_callbacks_class.to_s.camelcase.constantize
+        Callbacks.register_callback self, callback_class
+      end
+    end
+
     included do
       include ActiveModel::Validations
-      include ActiveModel::Naming
+      extend ActiveModel::Naming
       include ActiveModel::Conversion
       include Virtus.model
 
@@ -192,6 +218,18 @@ module Guacamole
         key
       end
 
+      def valid_with_callbacks?(context = nil)
+        callbacks.run_callbacks :validate do
+          valid_without_callbacks?(context)
+        end
+      end
+      alias_method :valid_without_callbacks?, :valid?
+      alias_method :valid?, :valid_with_callbacks?
+
+      def callbacks
+        Guacamole::Callbacks.callbacks_for(self)
+      end
+
       def ==(other)
         other.instance_of?(self.class) &&
           attributes.all? do |attribute, value|

data/lib/guacamole/railtie.rb

@@ -18,15 +18,21 @@ module Guacamole
     # Add app/collections to autoload_paths
     initializer 'guacamole.setup_autoload_paths', before: :set_autoload_paths do |app|
       app.config.autoload_paths += %W(#{app.config.root}/app/collections)
+      app.config.autoload_paths += %W(#{app.config.root}/app/callbacks)
     end
 
     # We're not doing migrations (yet)
     config.send(:app_generators).orm :guacamole, migration: false
 
-    initializer 'guacamole.load-config' do
-      config_file = Rails.root.join('config', 'guacamole.yml')
-      if config_file.file?
+    initializer 'guacamole.configure_database_connection' do
+      if ENV['DATABASE_URL'].present?
+        Guacamole::Configuration.configure_with_uri ENV['DATABASE_URL']
+      elsif (config_file = Rails.root.join('config', 'guacamole.yml')).file?
         Guacamole::Configuration.load config_file
+      else
+        warn_msg = '[WARNING] No configuration could be found. Either provide a `guacamole.yml` or a connection URI with `ENV["DATABASE_URL"]`'
+        warn warn_msg
+        Guacamole.logger.warn warn_msg
       end
     end
 

data/lib/guacamole/version.rb

@@ -1,5 +1,5 @@
 # -*- encoding : utf-8 -*-
 module Guacamole
   # Current version of the gem
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end

data/lib/rails/generators/guacamole/callbacks/callbacks_generator.rb

@@ -0,0 +1,26 @@
+# -*- encoding : utf-8 -*-
+
+require 'rails/generators/guacamole_generator'
+
+module Guacamole
+  module Generators
+    class CallbacksGenerator < Base
+      desc 'Creates a Guacamole callback class'
+
+      class_option :model_class, type: :string, required: false, banner: 'CLASS_NAME | Default: NAME', desc: 'The model class this callback is used for.'
+
+      check_class_collision
+
+      def create_callback_file
+        model_file_name = (options[:model_class] || class_name).underscore
+        inject_into_file "app/models/#{model_file_name}.rb",
+          "\n\n  callbacks :#{class_name.underscore}_callbacks",
+          after: 'include Guacamole::Model'
+
+        template 'callbacks.rb.tt', File.join('app/callbacks', class_path, "#{file_name}_callbacks.rb")
+      end
+
+      hook_for :test_framework
+    end
+  end
+end

data/lib/rails/generators/guacamole/callbacks/templates/callbacks.rb.tt

@@ -0,0 +1,13 @@
+<% module_namespacing do -%>
+class <%= class_name %>Callbacks
+  include Guacamole::Callbacks
+
+  # Add your callbacks
+  # before_create :encrypt_password
+
+  # def encrypt_password
+  #   object.encrypted_password = BCrypt::Password.create(object.password)
+  # end
+end
+<% end -%>
+

data/lib/rails/generators/rspec/callbacks/callbacks_generator.rb

@@ -0,0 +1,14 @@
+# -*- encoding : utf-8 -*-
+
+require 'rails/generators/guacamole_generator'
+
+module Rspec
+  module Generators
+    class CallbacksGenerator < ::Guacamole::Generators::Base
+      def create_collection_spec
+        template 'callbacks_spec.rb.tt', File.join('spec/callbacks', class_path, "#{file_name}_callbacks_spec.rb")
+      end
+    end
+  end
+end
+