rest_framework 0.0.0 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c71a3fea7904490cd834aff65231d4a18804e8cd487a07314e475a73d9a6500e
-  data.tar.gz: bde5421c92b4c960bc9b09b369a36b2d4df463b0722490c35cbaf00cdb6b6a66
+  metadata.gz: a3e577365f00c98803ebf7f4548c10e5e0cde9208d47de71ac5d5193d0e0c776
+  data.tar.gz: b0527bc192535edcd85a91587e11df09c30dff460701c826fe6574ec487bc003
 SHA512:
-  metadata.gz: 21db95368e8223a1b086e63b9724eb7cb35cb5eb42db9eedb5eca557662be24363f225ab69fb98d2996152c69d58218a5156fdaba1345330660c974313b3f912
-  data.tar.gz: 2f32d14d77eb8f60b29019afd81f6b926e2bd97268b2cd6d4828698adf4b66debea2959f00403913a6e74a970f858d960a4d3c9268a1f6fcccd9549c1aca992e
+  metadata.gz: 805f9fe5d4fcd15f5e360459af7246e52392115f3cf6ab3fe51a2128f16c4092e10ac0797767769992416818cdf5dc429790e128ad7a889119cdb134d739ea61
+  data.tar.gz: d0079b9e2cb005938d95aa83cccc3971849183be3209e2c08a2ebae5c357d6c9c571663cd496f68c4a5f8855ea2b804a46fbfcb73d839693b41ce781563599c0

data/README.md

@@ -1,5 +1,8 @@
 # REST Framework
 
+[![Gem Version](https://badge.fury.io/rb/rest_framework.svg)](https://badge.fury.io/rb/rest_framework)
+[![Build Status](https://travis-ci.org/gregschmit/rails-rest-framework.svg?branch=master)](https://travis-ci.org/gregschmit/rails-rest-framework)
+
 REST Framework helps you build awesome APIs in Ruby on Rails.
 
 **The Problem**: Building controllers for APIs usually involves writing a lot of redundant CRUD
@@ -24,6 +27,78 @@ Or install it yourself with:
 
     $ gem install rest_framework
 
+## Usage
+
+### Controller Mixins
+
+To transform a controller into a RESTful controller, you can either include `BaseControllerMixin`,
+`ReadOnlyModelControllerMixin`, or `ModelControllerMixin`. `BaseControllerMixin` provides a `root`
+action and a simple interface for routing arbitrary additional actions:
+
+```
+class ApiController < ApplicationController
+  include RESTFramework::BaseControllerMixin
+  @extra_actions = {test: [:get]}
+
+  def test
+    render inline: "Test successful!"
+  end
+end
+```
+
+`ModelControllerMixin` assists with providing the standard CRUD for your controller.
+
+```
+class Api::MoviesController < ApiController
+  include RESTFramework::ModelControllerMixin
+
+  @recordset = Movie.where(enabled: true)  # by default, @recordset would include all movies
+end
+```
+
+`ReadOnlyModelControllerMixin` only enables list/show actions, but since we're naming this
+controller in a way that doesn't make the model obvious, we can set that explicitly:
+
+```
+class Api::ReadOnlyMoviesController < ApiController
+  include RESTFramework::ReadOnlyModelControllerMixin
+
+  @model = Movie
+end
+```
+
+Note that you can also override `get_model` and `get_recordset` instance methods to override the API
+behavior dynamically per-request.
+
+### Routing
+
+You can use Rails' `resource`/`resources` routers to route your API, however if you want
+`@extra_actions` / `@extra_member_actions` to be routed automatically, then you can use the
+`rest_resource` / `rest_resources` routers provided by this gem. You can also use `rest_root` to route
+the root of your API:
+
+```
+Rails.application.routes.draw do
+  rest_root :api  # will find `api_controller` and route the `root` action to '/api'
+  namespace :api do
+    rest_resources :movies
+    rest_resources :read_only_movies
+  end
+end
+```
+
+Or if you want the API root to be routed to `Api::RootController#root`:
+
+```
+Rails.application.routes.draw do
+  namespace :api do
+    rest_root  # will route `Api::RootController#root` to '/' in this namespace ('/api')
+    rest_resources :movies
+    rest_resources :read_only_movies
+  end
+end
+```
+
 ## Development/Testing
 
 After you clone the repository, cd'ing into the directory should create a new gemset if you are
@@ -37,10 +112,10 @@ To run unit tests:
 
     $ rake test:unit
 
-To run integration tests on a sample app:
-
-    $ rake test:app
+To run integration tests:
 
-To run that sample app live:
+    $ rake test:integration
 
-    $ rake test:app:run
+To interact with the integration app, you can `cd test/integration` and operate it via the normal
+Rails interfaces. Ensure you run `rake db:schema:load` before running `rails server` or
+`rails console`.

data/app/views/layouts/rest_framework.html.erb

@@ -0,0 +1,38 @@
+<!doctype html>
+<html>
+  <head>
+    <title><%= @title %></title>
+    <%= render partial: 'rest_framework/head' %>
+  </head>
+
+  <body>
+    <div class="bg-dark">
+      <div class="w-100 m-0 p-0" style="height: .3em; background-color: #a00;"></div>
+      <nav class="navbar navbar-dark bg-dark">
+        <div class="container">
+          <span class="navbar-brand p-0">
+            <h1 class="text-light font-weight-light m-0 p-0" style="font-size: 1em"><%= @template_logo_text %></h1>
+          </span>
+        </div>
+      </nav>
+    </div>
+    <div class="container py-3">
+      <div class="container">
+        <div class="row">
+          <h1><%= @title %></h1>
+        </div>
+        <hr/>
+        <div class="row">
+          <h2>Payload</h2><br>
+          <div><pre><%= JSON.pretty_generate(JSON.parse(@serialized_payload)) %></pre></div>
+        </div>
+        <% unless @routes.blank? %>
+          <div class="row">
+            <h2>Routes</h2>
+            <%= render partial: 'rest_framework/routes' %>
+          </div>
+        <% end %>
+      </div>
+    </div>
+  </body>
+</html>

data/app/views/rest_framework/_head.html.erb

@@ -0,0 +1,19 @@
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+<%= csrf_meta_tags %>
+<%= csp_meta_tag rescue nil %>
+
+<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css" integrity="sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm" crossorigin="anonymous">
+<style>
+h1,h2,h3,h4,h5,h6 { width: 100%; }
+h1 { font-size: 2rem; }
+h2 { font-size: 1.7rem; }
+h3 { font-size: 1.5rem; }
+h4 { font-size: 1.3rem; }
+h5 { font-size: 1.1rem; }
+h6 { font-size: 1rem; }
+</style>
+
+<script src="https://code.jquery.com/jquery-3.2.1.slim.min.js" integrity="sha384-KJ3o2DKtIkvYIK3UENzmM7KCkRr/rE9/Qpg6aAZGJwFDMVNA/GpGFF93hXpG5KkN" crossorigin="anonymous"></script>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js" integrity="sha384-ApNbgh9B+Y1QKtv3Rn7W3mgPxhU9K/ScQsAP7hUibX39j7fakFPskvXusvfa0b4Q" crossorigin="anonymous"></script>
+<script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js" integrity="sha384-JZR6Spejh4U02d8jOt6vLEHfe/JQGiRRSQQxSfFWpi1MquVdAyjUar5+76PVCmYl" crossorigin="anonymous"></script>

data/app/views/rest_framework/_routes.html.erb

@@ -0,0 +1,18 @@
+<table class="table">
+  <thead>
+    <tr>
+      <th scope="col">Verb</th>
+      <th scope="col">Path</th>
+      <th scope="col">Action</th>
+    </tr>
+  </thead>
+  <tbody>
+    <% @routes.each do |r| %>
+    <tr>
+      <td><%= r[:verb] %></td>
+      <td><%= r[:path] %></td>
+      <td><%= r[:action] %></td>
+    </tr>
+    <% end %>
+  </tbody>
+</table>

data/lib/rest_framework.rb

@@ -2,5 +2,6 @@ module RESTFramework
 end
 
 require_relative "rest_framework/controllers"
+require_relative "rest_framework/engine"
 require_relative "rest_framework/routers"
 require_relative "rest_framework/version"

data/lib/rest_framework/VERSION_STAMP

@@ -1 +1 @@
-0.0.0
+0.0.6

data/lib/rest_framework/controllers/base.rb

@@ -1,6 +1,8 @@
 module RESTFramework
 
+  # This module provides helpers for mixin `ClassMethods` submodules.
   module ClassMethodHelpers
+    # This helper assists in providing reader interfaces for mixin properties.
     def _restframework_attr_reader(property, default: nil)
       method = <<~RUBY
         def #{property}
@@ -14,11 +16,13 @@ module RESTFramework
     end
   end
 
+  # This module provides the common functionality for any controller mixins, a `root` action, and
+  # the ability to route arbitrary actions with `@extra_actions`. This is also where `api_response`
+  # is defined.
   module BaseControllerMixin
     # Default action for API root.
-    # TODO: use api_response and show sub-routes.
     def root
-      render inline: "This is the root of your awesome API!"
+      api_response({message: "This is the root of your awesome API!"})
     end
 
     protected
@@ -26,39 +30,90 @@ module RESTFramework
     module ClassMethods
       extend ClassMethodHelpers
 
-      # Interface for getting class-level instance/class variables.
+      # Interface for getting class-level instance/class variables. Note: we check if they are
+      # defined first rather than rescuing NameError to prevent uninitialized variable warnings.
       private def _restframework_try_class_level_variable_get(name, default: nil)
-        begin
-          v = instance_variable_get("@#{name}")
+        instance_variable = "@#{name}"
+        if self.instance_variable_defined?(instance_variable)
+          v = self.instance_variable_get(instance_variable)
           return v unless v.nil?
-        rescue NameError
         end
-        begin
-          v = class_variable_get("@@#{name}")
+        class_variable = "@@#{name}"
+        if self.class_variable_defined?(class_variable)
+          v = self.class_variable_get(class_variable)
           return v unless v.nil?
-        rescue NameError
         end
         return default
       end
 
-      # Interface for registering exceptions handlers.
-      # private def _restframework_register_exception_handlers
-      #   rescue_from
-      # end
-
+      _restframework_attr_reader(:singleton_controller)
       _restframework_attr_reader(:extra_actions, default: {})
-      _restframework_attr_reader(:skip_actions, default: [])
+      _restframework_attr_reader(:template_logo_text, default: 'Rails REST Framework')
+
+      def skip_actions(skip_undefined: true)
+        # first, skip explicitly skipped actions
+        skip = _restframework_try_class_level_variable_get(:skip_actions, default: [])
+
+        # now add methods which don't exist, since we don't want to route those
+        if skip_undefined
+          [:index, :new, :create, :show, :edit, :update, :destroy].each do |a|
+            skip << a unless self.method_defined?(a)
+          end
+        end
+
+        return skip
+      end
     end
 
     def self.included(base)
       base.extend ClassMethods
     end
 
+    def _get_routes
+      begin
+        formatter = ActionDispatch::Routing::ConsoleFormatter::Sheet
+      rescue NameError
+        formatter = ActionDispatch::Routing::ConsoleFormatter
+      end
+      return ActionDispatch::Routing::RoutesInspector.new(Rails.application.routes.routes).format(
+        formatter.new
+      ).lines[1..].map { |r| r.split.last(3) }.map { |r|
+        {verb: r[0], path: r[1], action: r[2]}
+      }.select { |r| r[:path].start_with?(request.path) }
+    end
+
     # Helper alias for `respond_to`/`render`, and replace nil responses with blank ones.
-    def api_response(value, **kwargs)
+    def api_response(payload, html_kwargs: nil, json_kwargs: nil, **kwargs)
+      payload ||= ''  # replace nil with ''
+      html_kwargs ||= {}
+      json_kwargs ||= {}
+
+      # serialize
+      if self.respond_to?(:get_model_serializer_config, true)
+        serialized_payload = payload.to_json(self.get_model_serializer_config)
+      else
+        serialized_payload = payload.to_json
+      end
+
       respond_to do |format|
-        format.html
-        format.json { render json: value || '', **kwargs }
+        format.html {
+          kwargs = kwargs.merge(html_kwargs)
+          @template_logo_text ||= self.class.template_logo_text
+          @title ||= self.controller_name.camelize
+          @routes ||= self._get_routes
+          @payload = payload
+          @serialized_payload = serialized_payload
+          begin
+            render(**kwargs)
+          rescue ActionView::MissingTemplate  # fallback to rest_framework default view
+            kwargs[:template] = "rest_framework/default"
+          end
+          render(**kwargs)
+        }
+        format.json {
+          kwargs = kwargs.merge(json_kwargs)
+          render(json: serialized_payload || '', **kwargs)
+        }
       end
     end
   end

data/lib/rest_framework/controllers/models.rb

@@ -21,7 +21,6 @@ module RESTFramework
 
       _restframework_attr_reader(:model)
       _restframework_attr_reader(:recordset)
-      _restframework_attr_reader(:singleton_controller)
 
       _restframework_attr_reader(:fields)
       _restframework_attr_reader(:list_fields)
@@ -32,11 +31,14 @@ module RESTFramework
       _restframework_attr_reader(:extra_member_actions, default: {})
 
       # For model-based mixins, `@extra_collection_actions` is synonymous with `@extra_actions`.
-      def extra_actions
-        return (
+      # @param skip_undefined [Boolean] whether we should skip routing undefined actions
+      def extra_actions(skip_undefined: true)
+        actions = (
           _restframework_try_class_level_variable_get(:extra_collection_actions) ||
           _restframework_try_class_level_variable_get(:extra_actions, default: {})
         )
+        actions = actions.select { |a| self.method_defined?(a) } if skip_undefined
+        return actions
       end
     end
 
@@ -48,7 +50,7 @@ module RESTFramework
 
     # Get a list of fields for the current action.
     def get_fields
-      return @fields if @fields
+      return @fields if instance_variable_defined?(:@fields) && @fields
 
       # index action should use list_fields
       name = (action_name == 'index') ? 'list' : action_name
@@ -57,9 +59,8 @@ module RESTFramework
         @fields = self.class.send("#{name}_fields")
       rescue NameError
       end
-      @fields ||= self.class.fields || []
 
-      return @fields
+      return @fields ||= self.class.fields || []
     end
 
     # Get a configuration passable to `as_json` for the model.
@@ -109,10 +110,10 @@ module RESTFramework
     end
 
     # Internal interface for get_model, protecting against infinite recursion with get_recordset.
-    private def _get_model(from_internal_get_recordset: false)
-      return @model if @model
+    def _get_model(from_internal_get_recordset: false)
+      return @model if instance_variable_defined?(:@model) && @model
       return self.class.model if self.class.model
-      unless from_get_recordset  # prevent infinite recursion
+      unless from_internal_get_recordset  # prevent infinite recursion
         recordset = self._get_recordset(from_internal_get_model: true)
         return (@model = recordset.klass) if recordset
       end
@@ -124,10 +125,10 @@ module RESTFramework
     end
 
     # Internal interface for get_recordset, protecting against infinite recursion with get_model.
-    private def _get_recordset(from_internal_get_model: false)
-      return @recordset if @recordset
+    def _get_recordset(from_internal_get_model: false)
+      return @recordset if instance_variable_defined?(:@recordset) && @recordset
       return self.class.recordset if self.class.recordset
-      unless from_get_model  # prevent infinite recursion
+      unless from_internal_get_model  # prevent infinite recursion
         model = self._get_model(from_internal_get_recordset: true)
         return (@recordset = model.all) if model
       end
@@ -149,14 +150,14 @@ module RESTFramework
     # TODO: pagination classes like Django
     def index
       @records = self.get_filtered_recordset
-      api_response(@records, **self.get_model_serializer_config)
+      api_response(@records)
     end
   end
 
   module ShowModelMixin
     def show
       @record = self.get_record
-      api_response(@record, **self.get_model_serializer_config)
+      api_response(@record)
     end
   end
 
@@ -167,7 +168,7 @@ module RESTFramework
       rescue ActiveRecord::RecordInvalid => e
         api_response(e.record.messages, status: 400)
       end
-      api_response(@record, **self.get_model_serializer_config)
+      api_response(@record)
     end
   end
 
@@ -177,7 +178,7 @@ module RESTFramework
       if @record
         @record.attributes(self.get_update_params)
         @record.save!
-        api_response(@record, **self.get_model_serializer_config)
+        api_response(@record)
       else
         api_response({detail: "Record not found."}, status: 404)
       end

data/lib/rest_framework/engine.rb

@@ -0,0 +1,2 @@
+class RESTFramework::Engine < ::Rails::Engine
+end

data/lib/rest_framework/routers.rb

@@ -25,10 +25,10 @@ module ActionDispatch::Routing
 
       # convert class name to class
       begin
-        controller = mod.const_get(name, false)
+        controller = mod.const_get(name)
       rescue NameError
         if fallback_reverse_pluralization
-          controller = mod.const_get(name_reverse, false)
+          controller = mod.const_get(name_reverse)
         else
           raise
         end
@@ -41,7 +41,8 @@ module ActionDispatch::Routing
     # @param default_singular [Boolean] the default plurality of the resource if the plurality is
     #   not otherwise defined by the controller
     # @param name [Symbol] the resource name, from which path and controller are deduced by default
-    protected def _rest_resources(default_singular, name, **kwargs, &block)
+    # @param skip_undefined [Boolean] whether we should skip routing undefined actions
+    protected def _rest_resources(default_singular, name, skip_undefined: true, **kwargs, &block)
       controller = kwargs[:controller] || name
       if controller.is_a?(Class)
         controller_class = controller
@@ -50,9 +51,7 @@ module ActionDispatch::Routing
       end
 
       # set controller if it's not explicitly set
-      unless kwargs[:controller]
-        kwargs[:controller] = name
-      end
+      kwargs[:controller] = name unless kwargs[:controller]
 
       # determine plural/singular resource
       if kwargs.delete(:force_singular)
@@ -67,10 +66,14 @@ module ActionDispatch::Routing
       resource_method = singular ? :resource : :resources
 
       # call either `resource` or `resources`, passing appropriate modifiers
-      public_send(resource_method, name, except: controller_class.skip_actions, **kwargs) do
+      skip_undefined = kwargs.delete(:skip_undefined) || true
+      skip = controller_class.skip_actions(skip_undefined: skip_undefined)
+      public_send(resource_method, name, except: skip, **kwargs) do
         if controller_class.respond_to?(:extra_member_actions)
           member do
-            controller_class.extra_member_actions.each do |action, methods|
+            actions = controller_class.extra_member_actions
+            actions = actions.select { |k,v| controller_class.method_defined?(k) } if skip_undefined
+            actions.each do |action, methods|
               methods = [methods] if methods.is_a?(Symbol) || methods.is_a?(String)
               methods.each do |m|
                 public_send(m, action)
@@ -80,7 +83,9 @@ module ActionDispatch::Routing
         end
 
         collection do
-          controller_class.extra_actions.each do |action, methods|
+          actions = controller_class.extra_actions
+          actions = actions.select { |k,v| controller_class.method_defined?(k) } if skip_undefined
+          actions.each do |action, methods|
             methods = [methods] if methods.is_a?(Symbol) || methods.is_a?(String)
             methods.each do |m|
               public_send(m, action)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rest_framework
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.0.6
 platform: ruby
 authors:
 - Gregory N. Schmit
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-09-16 00:00:00.000000000 Z
+date: 2020-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -33,11 +33,16 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- app/views/layouts/rest_framework.html.erb
+- app/views/rest_framework/_head.html.erb
+- app/views/rest_framework/_routes.html.erb
+- app/views/rest_framework/default.html.erb
 - lib/rest_framework.rb
 - lib/rest_framework/VERSION_STAMP
 - lib/rest_framework/controllers.rb
 - lib/rest_framework/controllers/base.rb
 - lib/rest_framework/controllers/models.rb
+- lib/rest_framework/engine.rb
 - lib/rest_framework/routers.rb
 - lib/rest_framework/version.rb
 homepage: https://github.com/gregschmit/rails-rest-framework
@@ -50,6 +55,7 @@ post_install_message:
 rdoc_options: []
 require_paths:
 - lib
+- app
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="