cathode 0.0.1 → 0.1.0

data/Rakefile

@@ -16,6 +16,7 @@ end
 
 APP_RAKEFILE = File.expand_path("../spec/dummy/Rakefile", __FILE__)
 load 'rails/tasks/engine.rake'
+load 'lib/tasks/cathode_tasks.rake'
 
 Bundler::GemHelper.install_tasks
 

data/app/controllers/cathode/base_controller.rb

@@ -1,47 +1,30 @@
-class Cathode::BaseController < ActionController::Base
-  before_action :process_access_filter
-
-  def index
-    render json: resources.load
-  end
-
-  def create
-    render json: model.create(resource_params)
-  end
-
-  def destroy
-    resource.destroy
-    head :ok
-  end
-
-  def show
-    make_request(request)
-  end
-
-private
-
-  def make_request(http_request)
-    request = Cathode::Request.new(http_request, params)
-    render json: request.body, status: request.status
-  end
-
-  def resources
-    model.all
-  end
-
-  def resource
-    model.find params[:id]
-  end
-
-  def resource_params
-    params[controller_name.singularize]
-  end
-
-  def model
-    controller_name.classify.constantize
-  end
-
-  def process_access_filter
-
+module Cathode
+  # Defines a basic controller for all Cathode controllers to inherit from.
+  # Intercepts all Rails requests and sends them off to {Request} with the
+  # context to to be processed.
+  class BaseController < ActionController::Base
+    %w(index show create update destroy custom).each do |method|
+      define_method method do
+        make_request
+      end
+    end
+
+  private
+
+    def make_request
+      if Cathode::Base.tokens_required
+        authenticate_or_request_with_http_token do |token|
+          Token.find_by token: token
+        end
+      end
+
+      request = Cathode::Request.create self
+
+      render json: request._body, status: request._status unless performed?
+    end
+
+    def resource_params
+      params[controller_name.singularize]
+    end
   end
 end

data/app/models/cathode/token.rb

@@ -0,0 +1,21 @@
+module Cathode
+  # Defines a token model to hold the API tokens.
+  class Token < ActiveRecord::Base
+    after_initialize :generate_token
+
+    validates :token, uniqueness: true
+
+    # Expires the token by deactivating it and updating its `expired_at` field.
+    # @return [Token] self
+    def expire
+      update active: false, expired_at: Time.now
+      self
+    end
+
+  private
+
+    def generate_token
+      self.token = SecureRandom.hex
+    end
+  end
+end

data/config/routes.rb

@@ -1,2 +1,18 @@
+def attach_resources(resources)
+  resources.each do |resource|
+    method = resource.singular ? :resource : :resources
+    send method, resource.name, controller: resource.controller_prefix.underscore, only: resource.default_actions.map(&:name) do
+      resource.custom_actions.each do |action|
+        match action.name => action.name, action: 'custom', via: action.http_method
+      end
+      attach_resources(resource._resources)
+    end
+  end
+end
+
 Cathode::Engine.routes.draw do
+  Cathode::Base.versions.each do |version|
+    attach_resources(version._resources)
+  end
+  match '*path' => 'base#custom', via: [:get, :post, :put, :delete]
 end

data/db/migrate/20140425164100_create_cathode_tokens.rb

@@ -0,0 +1,11 @@
+class CreateCathodeTokens < ActiveRecord::Migration
+  def change
+    create_table :cathode_tokens do |t|
+      t.boolean :active, default: true
+      t.datetime :expired_at
+      t.string :token
+
+      t.timestamps
+    end
+  end
+end

data/lib/cathode.rb

@@ -1,14 +1 @@
-require 'cathode/engine'
 require 'cathode/base'
-require 'cathode/exceptions'
-
-module Cathode
-  class Engine < ::Rails::Engine
-    config.generators do |g|
-      g.test_framework      :rspec,        :fixture => false
-      g.fixture_replacement :factory_girl, :dir => 'spec/factories'
-      g.assets false
-      g.helper false
-    end
-  end
-end

data/lib/cathode/_version.rb

@@ -1,3 +1,4 @@
 module Cathode
-  VERSION = "0.0.1"
+  # The current version of Cathode.
+  VERSION = '0.1.0'
 end

data/lib/cathode/action.rb

@@ -1,40 +1,78 @@
 module Cathode
+  # An `Action` can be added to a {Resource} or a {Version} and contains the
+  # default behavior of that action (if it is a default action), or the override
+  # behavior if it is a custom action or an overridden default action.
   class Action
+    include ActionDsl
+
+    attr_accessor :strong_params
     attr_reader :action_access_filter,
+                :action_block,
+                :http_method,
                 :name,
+                :override_block,
                 :resource
 
+    delegate :parent, to: :resource
 
-    def self.create(action, resource, &block)
-      klass = case action
-              when :index
-                IndexAction
-              when :show
-                ShowAction
-              when :create
-                CreateAction
-              when :update
-                UpdateAction
-              when :destroy
-                DestroyAction
-              end
-      klass.new(action, resource, &block)
+    class << self
+      # Creates an action by initializing the appropriate subclass
+      # @param action [Symbol] The action's name
+      # @param resource [Resource] The resource the action belongs to
+      # @param params [Hash] An optional params hash
+      # @param block The action's properties, defined with the {ActionDsl}
+      # @return [IndexAction, ShowAction, CreateAction, UpdateAction,
+      #   DestroyAction, CustomAction] The subclassed action
+      def create(action, resource, params = nil, &block)
+        klass = case action
+                when :index
+                  IndexAction
+                when :show
+                  ShowAction
+                when :create
+                  CreateAction
+                when :update
+                  UpdateAction
+                when :destroy
+                  DestroyAction
+                else
+                  CustomAction
+                end
+        klass.new(action, resource, params, &block)
+      end
     end
 
-    def initialize(action, resource, &block)
+    # Initializes the action
+    # @param action [Symbol] The action's name
+    # @param resource [Resource] The resource the action belongs to
+    # @param params [Hash] An optional params hash
+    # @param block The action's properties, defined with the {ActionDsl}
+    def initialize(action, resource, params = {}, &block)
       @name, @resource = action, resource
+      @allowed_subactions = []
 
-      self.instance_eval &block if block_given?
-    end
-
-    def perform(params)
-      if action_access_filter && !action_access_filter.call
-        return { status: :unauthorized }
+      if block_given?
+        if params[:override]
+          override &block
+        else
+          if [:index, :show, :create, :update, :destroy].include? action
+            instance_eval &block
+          else 
+            @action_block = block
+          end
+        end
       end
 
-      body = perform_action params
+      @http_method = params[:method] if params.present?
 
-      return { body: body, status: :ok }
+      after_initialize if respond_to? :after_initialize
+    end
+
+    # Whether a subaction is permitted
+    # @param subaction [Symbol] The subaction's name
+    # @return [Boolean]
+    def allowed?(subaction)
+      @allowed_subactions.include? subaction
     end
 
   private
@@ -46,37 +84,157 @@ module Cathode
     def access_filter(&filter)
       @action_access_filter = filter
     end
+
+    def allows(*subactions)
+      @allowed_subactions = subactions
+    end
+
+    def replace(&block)
+      @action_block = block
+    end
+
+    def override(&block)
+      @override_block = block
+    end
+
+    def overridden?
+      override_block.present?
+    end
+
+    def after_resource_initialized
+      self
+    end
+
+    # Requires that the action has an attributes block defined or one is defined
+    # at the resource level
+    module RequiresStrongParams
+      # Raises an error if there is no attributes block defined
+      def after_resource_initialized
+        if strong_params.nil?
+          if resource.strong_params.present?
+            @strong_params = resource.strong_params
+          else
+            fail UnknownAttributesError, "An attributes block was not specified for `#{name}' action on resource `#{resource.name}'"
+          end
+        end
+
+        super
+      end
+    end
+
+    # Raises an error if the action was defined on a resource whose parent
+    # doesn't have an association to the resource
+    module RequiresAssociation
+      # Defines the possible associations as `:resources` (`has_many`) or
+      # `:resource` (`has_one`)
+      def association_keys
+        [
+          resource.name.to_s.singularize.to_sym,
+          resource.name.to_s.pluralize.to_sym
+        ]
+      end
+
+      # Determines whether an expected association is present.
+      def after_resource_initialized
+        if parent.present? && !overridden?
+          reflections = parent.model.reflections
+
+          if association_keys.map { |key| reflections.include?(key) }.none?
+            raise MissingAssociationError, error_message
+          end
+        end
+
+        super
+      end
+    end
+
+    # Raises an error if the action was defined on a resource whose parent
+    # doesn't have a `has_one` association to the resource
+    module RequiresHasOneAssociation
+      include RequiresAssociation
+
+      # Defines the possible associations as `:resource` (`has_one`)
+      def association_keys
+        [resource.name.to_s.singularize.to_sym]
+      end
+
+      # Provides an error message to display if the association is missing.
+      def error_message
+        "Can't use default :#{name} action on `#{parent.name}' without a has_one `#{resource.name.to_s.singularize}' association"
+      end
+    end
+
+    # Raises an error if the action was defined on a resource whose parent
+    # doesn't have a `has_many` association to the resource
+    module RequiresHasManyAssociation
+      include RequiresAssociation
+
+      # Defines the possible associations as `:resources` (`has_many`).
+      def association_keys
+        [resource.name.to_s.pluralize.to_sym]
+      end
+
+      # Provides an error message to display if the association is missing.
+      def error_message
+        "Can't use default :#{name} action on `#{parent.name}' without a has_many or has_and_belongs_to_many `#{resource.name.to_s.singularize}' association"
+      end
+    end
+
+    # Requires the resource to define custom action behavior if it is a singular
+    # resource.
+    module RequiresCustomActionForSingular
+      # Raises an error if the resource is singular and attempting to use the
+      # default action without a parent resource
+      def after_resource_initialized
+        if resource.singular && !overridden? && resource.parent.nil?
+          raise Cathode::ActionBehaviorMissingError,
+            "Can't use default :#{name} action on singular resource `#{resource.name}'"
+        end
+
+        super
+      end
+    end
   end
 
+  # Provides additional behavior for index actions.
   class IndexAction < Action
-    def perform_action(params)
-      model.all
-    end
+    include RequiresCustomActionForSingular
+    include RequiresHasManyAssociation
   end
 
+  # Provides additional behavior for show actions.
   class ShowAction < Action
-    def perform_action(params)
-      model.find params[:id]
-    end
+    include RequiresCustomActionForSingular
+    include RequiresHasOneAssociation
   end
 
+  # Provides additional behavior for create actions.
   class CreateAction < Action
-    def perform_action(params)
-      model.create params
-    end
+    include RequiresCustomActionForSingular
+    include RequiresStrongParams
+    include RequiresAssociation
   end
 
+  # Provides additional behavior for update actions.
   class UpdateAction < Action
-    def perform_action(params)
-      record = model.find(params[:id])
-      record.update params
-      record.reload
-    end
+    include RequiresCustomActionForSingular
+    include RequiresStrongParams
+    include RequiresHasOneAssociation
   end
 
+  # Provides additional behavior for destroy actions.
   class DestroyAction < Action
-    def perform_action(params)
-      model.find(params[:id]).destroy
+    include RequiresCustomActionForSingular
+    include RequiresHasOneAssociation
+  end
+
+  # Provides additional behavior for non-default actions.
+  class CustomAction < Action
+    # Raises an error if the action was defined without an HTTP method
+    def after_initialize
+      if http_method.nil?
+        raise RequestMethodMissingError, "You must specify an HTTP method (get, put, post, delete) for action `#{@name}'"
+      end
     end
   end
 end

data/lib/cathode/action_dsl.rb

@@ -0,0 +1,60 @@
+module Cathode
+  # Holds the domain-specific language (DSL) for describing actions.
+  module ActionDsl
+    # Lists the actions that are default (i.e., `index`, `show`, `create`,
+    #   `update`, and `destroy`)
+    # @return [Array] The default actions
+    def default_actions
+      actions.select { |action| DEFAULT_ACTIONS.include? action.name }
+    end
+
+    # Lists the actions that are not default
+    # @return [Array] The custom actions
+    def custom_actions
+      actions - default_actions
+    end
+
+    # Lists all the actions; initializes an empty `ObjectCollection` if there
+    # aren't any yet
+    # @return [Array] The actions
+    def actions
+      @actions ||= ObjectCollection.new
+    end
+
+  protected
+
+    def action(action, params = {}, &block)
+      actions << Action.create(action, self, params, &block)
+    end
+
+    def get(action_name, &block)
+      action action_name, method: :get, &block
+    end
+
+    def post(action_name, &block)
+      action action_name, method: :post, &block
+    end
+
+    def put(action_name, &block)
+      action action_name, method: :put, &block
+    end
+
+    def delete(action_name, &block)
+      action action_name, method: :delete, &block
+    end
+
+    def replace_action(action_name, &block)
+      action action_name do
+        replace(&block)
+      end
+    end
+
+    def override_action(action_name, params = {}, &block)
+      action action_name, params.merge(override: true), &block
+    end
+
+    def attributes(&block)
+      @strong_params = block
+    end
+  end
+end