cathode 0.0.1 → 0.1.0

data/lib/cathode/base.rb

@@ -1,27 +1,96 @@
-require 'pry'
-require 'cathode/request'
-require 'cathode/resource'
-require 'cathode/action'
-require 'cathode/version'
+require 'cathode/engine'
+require 'cathode/railtie'
+require 'cathode/exceptions'
 
+# Cathode is a gem for creating API boilerplate for resourceful Rails
+# applications. It has first-class support for versions, model-backed resources,
+# default actions like `create` and `destroy`, and custom actions.
 module Cathode
-  class Base
-    @@versions = {}
+  autoload :Action,             'cathode/action'
+  autoload :ActionDsl,          'cathode/action_dsl'
+  autoload :CreateRequest,      'cathode/create_request'
+  autoload :CustomRequest,      'cathode/custom_request'
+  autoload :Debug,              'cathode/debug'
+  autoload :DeepClone,          'deep_clone'
+  autoload :DestroyRequest,     'cathode/destroy_request'
+  autoload :IndexRequest,       'cathode/index_request'
+  autoload :ObjectCollection,   'cathode/object_collection'
+  autoload :Query,              'cathode/query'
+  autoload :Request,            'cathode/request'
+  autoload :Resource,           'cathode/resource'
+  autoload :ResourceDsl,        'cathode/resource_dsl'
+  autoload :Semantic,           'semantic'
+  autoload :ShowRequest,        'cathode/show_request'
+  autoload :UpdateRequest,      'cathode/update_request'
+  autoload :Version,            'cathode/version'
+
+  # The actions whose default behavior is defined by Cathode.
+  DEFAULT_ACTIONS = [:index, :show, :create, :update, :destroy]
 
+  # Holds the top-level Cathode accessors for defining an API.
+  class Base
     class << self
+      attr_reader :tokens_required
+
+      # Defines an API
+      # @param block The API's versions and resources, defined using this
+      #   class's `version`, `resources`, and `resource` methods
+      def define(&block)
+        instance_eval(&block)
+      end
+
+      # Lists the collection of versions associated with this API
+      # @return [Cathode::ObjectCollection] the collection of versions
+      def versions
+        Version.all
+      end
+
+      # Defines a new version
+      # @param version_number [String, Fixnum, Float] A number or string
+      #   representing a SemVer-compliant version number. If a `Fixnum` or
+      #   `Float` is passed, it will be converted to a string before being
+      #   evaluated for SemVer compliance, so passing `1.5` is equivalent to
+      #   passing `'1.5.0'`.
+      # @param block A block defining the version's resources and actions, and
+      #   has access to the methods in the {Cathode::ActionDsl} and {Cathode::ResourceDsl}
+      def version(version_number, &block)
+        Version.define(version_number, &block)
+      end
+
+      # Defines a singular resource on version 1.0.0 of the API
+      # @param resource_name [Symbol] The resource's name
+      # @param params [Hash] Optional params, e.g. `{ actions: :all }`
+      # @param block A block defining the resource's actions and properties, run
+      #   inside the context of version 1.0.0 with access to the methods in the
+      #   {Cathode::ActionDsl} and {Cathode::ResourceDsl}
       def resource(resource_name, params = nil, &block)
         version 1 do
           resource resource_name, params, &block
         end
       end
 
-      def versions
-        @@versions
+      # Defines a plural resource on version 1.0.0 of the API
+      # @param resource_name [Symbol] The resource's name
+      # @param params [Hash] Optional params, e.g. `{ actions: :all }`
+      # @param block A block defining the resource's actions and properties, run
+      #   inside the context of version 1.0.0 with access to the methods in the
+      #   {Cathode::ActionDsl} and {Cathode::ResourceDsl}
+      def resources(resource_name, params = nil, &block)
+        version 1 do
+          resources resource_name, params, &block
+        end
       end
 
-      def version(version_number, &block)
-        version = Version.new(version_number, &block)
-        versions[version.version.to_s] = version
+      # Configures this API to require incoming requests to have a valid token
+      def require_tokens
+        @tokens_required = true
+      end
+
+    private
+
+      def reset!
+        versions.clear
+        @tokens_required = false
       end
     end
   end

data/lib/cathode/create_request.rb

@@ -0,0 +1,21 @@
+module Cathode
+  # Defines the default behavior for a create request.
+  class CreateRequest < Request
+    # Sets the default action to create a new resource. If the resource is
+    # singular, sets the parent resource `id` as well.
+    def default_action_block
+      proc do
+        begin
+          create_params = instance_eval(&@strong_params)
+          if resource.singular
+            create_params["#{parent_resource_name}_id"] = parent_resource_id
+          end
+          body model.create(create_params)
+        rescue ActionController::ParameterMissing => error
+          body error.message
+          status :bad_request
+        end
+      end
+    end
+  end
+end

data/lib/cathode/custom_request.rb

@@ -0,0 +1,5 @@
+module Cathode
+  # Holds a custom (non-`[index, show, create, update, delete]`) request. Custom
+  # requests have no default actions, so this is a no-op.
+  class CustomRequest < Request; end
+end

data/lib/cathode/debug.rb

@@ -0,0 +1,25 @@
+module Cathode
+  # Provides information about the Cathode API.
+  class Debug
+    class << self
+      # Gathers information about the API's versions, properties, resources, and
+      # actions.
+      # @return [String] A string listing the versions, resources, and actions
+      def info
+        output = ''
+        Cathode::Base.versions.each do |version|
+          output += "\nVersion #{version.version}"
+
+          version._resources.each do |resource|
+            output += "\n  #{resource.name}/"
+            resource.actions.each do |action|
+              output += "\n    #{action.name}"
+            end
+          end
+        end
+
+        output
+      end
+    end
+  end
+end

data/lib/cathode/destroy_request.rb

@@ -0,0 +1,13 @@
+module Cathode
+  # Defines the default behavior for a destroy request.
+  class DestroyRequest < Request
+    # Sets the default action to destroy a resource. If the resource is
+    # singular, destroys the parent's associated resource. Otherwise, destroys
+    # the resource directly.
+    def default_action_block
+      proc do
+        record.destroy
+      end
+    end
+  end
+end

data/lib/cathode/engine.rb

@@ -1,5 +1,14 @@
+require 'rails'
 module Cathode
+  # Define a Rails engine with an isolated `Cathode` namespace.
   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
+
     isolate_namespace Cathode
   end
 end

data/lib/cathode/exceptions.rb

@@ -1,3 +1,23 @@
 module Cathode
+  # Raised when a resource is initialized but there is no constant (ActiveRecord
+  # model) that matches it.
   class UnknownResourceError < NameError; end
+
+  # Raised when a nonexistent action is referred to.
+  class UnknownActionError < NameError; end
+
+  # Raised when an `attributes` block is not passed in a context that requires
+  # one.
+  class UnknownAttributesError < NameError; end
+
+  # Raised when a custom action is defined without an HTTP method.
+  class RequestMethodMissingError < NameError; end
+
+  # Raised when an ActiveModel association is not present in a context that
+  # requires one.
+  class MissingAssociationError < NameError; end
+
+  # Raised when an action's behavior has not been defined in a context that
+  # requires it.
+  class ActionBehaviorMissingError < NameError; end
 end

data/lib/cathode/index_request.rb

@@ -0,0 +1,40 @@
+module Cathode
+  # Defines the default behavior for an index request.
+  class IndexRequest < Request
+    # Determine the model to use depending on the request. If a sub-resource
+    # was requested, use the parent model to get the association. Otherwise, use
+    # all the resource's model's records.
+    def model
+      if @resource_tree.size > 1
+        parent_model_id = params["#{@resource_tree.first.name.to_s.singularize}_id"]
+        model = @resource_tree.first.model.find(parent_model_id)
+        @resource_tree.drop(1).each do |resource|
+          model = model.send resource.name
+        end
+        model
+      else
+        super.all
+      end
+    end
+
+    # Determine the default action to use depending on the request. If the
+    # `page` param was passed and the action allows paging, page the results.
+    # Otherwise, set the request body to all records.
+    def default_action_block
+      proc do
+        all_records = model
+
+        if allowed?(:paging) && params[:page]
+          page = params[:page]
+          per_page = params[:per_page] || 10
+          lower_bound = (per_page - 1) * page
+          upper_bound = lower_bound + per_page - 1
+
+          body all_records[lower_bound..upper_bound]
+        else
+          body all_records
+        end
+      end
+    end
+  end
+end

data/lib/cathode/object_collection.rb

@@ -0,0 +1,49 @@
+module Cathode
+  # Provides an enumerable interface for arrays of objects.
+  class ObjectCollection
+    attr_accessor :objects
+
+    delegate :each, to: :objects
+    delegate :select, to: :objects
+
+    def initialize
+      @objects = []
+    end
+
+    # Look up an object by its `name` property.
+    # @param name [Symbol] The object's name
+    # @return [Object]
+    def find(name)
+      objects.detect { |o| o.name == name }
+    end
+
+    # An array of all the `name` properties in this object.
+    # @return [Array]
+    def names
+      objects.map(&:name)
+    end
+
+    # Adds a new object to the collection.
+    # @param items [Object, Array] A single object or an array of objects to add
+    # @return [ObjectCollection] self
+    def add(items)
+      items = [items] unless items.is_a?(Array)
+      self.objects += items
+      self
+    end
+
+    # Delets an object from the collection by name.
+    # @param name [Symbol] The name of the object to remove
+    # @return [ObjectCollection] self
+    def delete(name)
+      objects.delete find(name)
+      self
+    end
+
+    # Forwards all missing methods to the `objects` array stored in this
+    # collection.
+    def method_missing(method, args)
+      objects.send method, args
+    end
+  end
+end

data/lib/cathode/query.rb

@@ -0,0 +1,24 @@
+module Cathode
+  # Holds the Cathode Query DSL interface.
+  class Query
+    attr_reader :results
+
+    # Initialize and parse a query.
+    # @param model [Class] A subclass of `ActiveRecord::Base`.
+    # @param query [String] The query to be executed
+    def initialize(model, query)
+      clauses = query.split ','
+      results = model
+      clauses.each do |clause|
+        words = clause.split
+        results = case words.first
+                  when 'where'
+                    results.where(words.drop(1).join ' ')
+                  else
+                    results.where(words.join ' ')
+                  end
+      end
+      @results = results
+    end
+  end
+end

data/lib/cathode/railtie.rb

@@ -0,0 +1,21 @@
+require 'rack/cors'
+
+module Cathode
+  # Defines a Railtie to hook into the Rails initialization process. Autoloads
+  # API code from the `app/api` directory and adds `Rack::Cors` to the
+  # application's middleware stack.
+  class Railtie < Rails::Railtie
+    initializer 'cathode.add_api_to_autoload_paths' do |app|
+      Dir[File.join(Rails.root, 'app', 'api', '**', '*.rb')].each { |f| require f }
+    end
+
+    initializer 'cathode.enable_cors' do |app|
+      app.config.middleware.use Rack::Cors do
+        allow do
+          origins '*'
+          resource '*', headers: :any, methods: [:get, :post, :put, :delete, :options]
+        end
+      end
+    end
+  end
+end

data/lib/cathode/request.rb

@@ -1,15 +1,147 @@
 module Cathode
+  # A `Request` object is created when a Rails request is intercepted by
+  # Cathode. This object is responsible for enforcing version headers as well as
+  # token authorization headers. After header enforcement, the object figures
+  # out which version and resource/action to use to process the request.
+  # Finally, the request's `_body` (HTTP response body) and `_status` (HTTP
+  # status code) are set and rendered from the controller that initiated the
+  # request.
   class Request
-    attr_reader :body,
-                :status
+    attr_reader :_body,
+                :_status,
+                :action,
+                :context,
+                :custom_logic,
+                :model,
+                :resource
 
-    def initialize(http_request, params)
-      version = http_request.headers['HTTP_ACCEPT_VERSION']
+    delegate :allowed?, to: :action
+    delegate :params, to: :context
 
-      resource = params['controller'].camelize.demodulize.downcase.to_sym
-      response = Version.perform_request_with_version(version, resource, params)
+    class << self
+      # Creates a request by initializing the appropriate subclass.
+      # @param context [ActionController] The controller responding to the
+      #   request
+      # @return [IndexRequest, ShowRequest, CreateRequest, UpdateRequest,
+      #   DestroyRequest, CustomRequest] The subclassed request
+      def create(context)
+        klass = case context.params[:action].to_sym
+                when :index
+                  IndexRequest
+                when :show
+                  ShowRequest
+                when :create
+                  CreateRequest
+                when :update
+                  UpdateRequest
+                when :destroy
+                  DestroyRequest
+                else
+                  CustomRequest
+                end
+        klass.new(context)
+      end
+    end
+
+    # Initializes the request
+    # @param context [ActionController] The controller responding to the request
+    def initialize(context)
+      @context = context
+
+      version_number = context.request.headers['HTTP_ACCEPT_VERSION']
+
+      if version_number.nil?
+        @_status, @_body = :bad_request, 'A version number must be passed in the Accept-Version header'
+        return self
+      end
+
+      version = Version.find(version_number)
+      unless version.present?
+        @_status, @_body = :bad_request, "Unknown API version: #{version_number}"
+        return self
+      end
+
+      action_name = params[:action]
+      if action_name == 'custom'
+        action_name = context.request.path.split('/').last
+      end
+
+      params[:controller].slice! 'cathode/'
+      resources = params[:controller].split('_').map(&:to_sym)
+      resource = version._resources.find(resources.first)
+      @resource_tree = [resource]
+      subresources = resources.drop(1).collect do |r|
+        resource = resource._resources.find(r)
+      end
+      @resource_tree += subresources
+      resource = @resource_tree.last
+
+      @resource = resource
+
+      if @resource_tree.size > 1
+        @action = resource.actions.find(action_name.to_sym)
+      else
+        unless version.action?(resource.try(:name) || '', action_name)
+          @_status = :not_found
+          return self
+        end
+        @action = version._resources.find(resource.name).actions.find(action_name.to_sym)
+      end
+
+      @strong_params = @action.strong_params
+      @_status = :ok
+
+      if action.override_block
+        context.instance_eval(&action.override_block)
+      else
+        action_block = action.action_block
+        if action_block.nil? && respond_to?(:default_action_block)
+          action_block = default_action_block
+        end
+
+        instance_eval(&action_block)
+      end
+
+      body if @_body.nil?
+    end
+
+  private
+
+    def attributes(&block)
+      block.call(params)
+    rescue ActionController::ParameterMissing => error
+      body error.message
+      status :bad_request
+    end
+
+    def model
+      resource.model
+    end
+
+    def parent_resource_id
+      params["#{parent_resource_name}_id"]
+    end
+
+    def parent_resource_name
+      resource.parent.name.to_s.singularize
+    end
+
+    def record
+      if resource.singular
+        parent_model = resource.parent.model.find(parent_resource_id)
+        parent_model.send resource.name
+      else
+        model.find params[:id]
+      end
+    end
+
+    def body(value = Hash.new, &block)
+      return if _body.present?
+      @_body = block_given? ? block.call : value
+    end
 
-      @status, @body = response[:status], response[:body]
+    def status(value = nil, &block)
+      @_status = block_given? ? block.call : value
     end
   end
 end