toast 0.9.5 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1a702e1c3fefb8b0f86ae4169cf2bf0d5c06c59e
+  data.tar.gz: 7909991e0e45f40ab0f9889656a5fa0f64244bb2
+SHA512:
+  metadata.gz: ae832ad5e6df4d2b1fe56e52125fc2721029bd084c8c8ef7f1c1271d64bffbdea500f3fe9b3fbc3cdac7c47f9762cc3010cee3b8335c406aed1f084a8a2b20e7
+  data.tar.gz: b7c9bd99a118e16f6d722e5bc4323335e85f151be89e59457684426cee8b4c3bf8bd3afaea460620f3013da83d4d27f9e18fc9281505f3d55bef98e0bdd090d6

data/README.md

@@ -3,46 +3,58 @@
 Summary
 =======
 
-Toast is an extension to Ruby on Rails to build web services with low
-programming effort in a coherent way.  Toast extends ActiveRecord such
-that each model can be declared to be a web resource, exposing defined
-attributes for reading and writing using HTTP.
+Toast is a Rack application that hooks into Ruby on Rails. It exposes ActiveRecord models as a web service (REST API). The main difference from doing that with Ruby on Rails itself is it's DSL that covers all aspects of an API in one single configuration. For each model and API endpoint you define:
 
-Its main features are:
+  * what models and attributes are to be exposed
+  * what methods are supported  (GET, PATCH, DELETE, POST,...)
+  * hooks to handle authorization
+  * customized handlers 
 
-  * declaration of web resources based on ActiveRecord models
-  * generic controller handles all actions
-  * automated routing
-  * exposing data values with JSON maps
-  * exposing associations by links (URLs)
+When using Toast there's no Rails controller involved. Model classes and the API configuration is sufficient. 
 
-Toast works with
+Toast uses a REST/hypermedia style API, which is an own interpretation of the REST idea, not compatible with others like JSON API, Siren etc. It's design is much simpler and based on the idea of traversing opaque URIs. 
 
-  * Ruby on Rails >= 3.1.0 (currently tested up to 3.2.16)
-  * Ruby 1.8.7, 1.9.3, 2.0.0
+Other features are:
 
-See the [User Manual](https://github.com/robokopp/toast/wiki/User-Manual) for a detailed description.
+  * windowing of collections via _Range/Content-Range_ headers (paging)
+  * attribute selection per request 
+  * processing of URI parameters
+
+Toast v1 is build for Rails 5. The predecesssor v0.9 supports 3 and 4, but has a much different and smaller DSL.
+
+See the User Manual (to be published soon) for a detailed description.
 
 Status
-=====
+======
 
-Toast is ready for production and is being used in productive
-applications since 2012. However, misconfigurations can have undesired
-effects.
+Toast v1 for Rails 5 is a complete rewrite of v0.9, which was first published and used in production since 2012. 
+It comes now with secure defaults: Nothing is exposed unless declared, all endpoints have a default authorization hook responding with 401. 
 
-WARNING
-=======
+From my point of view it is production ready. I am in the process of porting a large API from v0.9 to v1 that uses all features and it looks very good so far. Of course minor issues will appear, please help to report and fix them. 
+
+Installation
+============
 
-A soon the gem is loaded a controller with ready routing is enabled
-serving the annotated model's data records at least for reading for
-everybody.
+with Bundler (Gemfile) from Rubygems:
+
+    source 'http://rubygems.org'
+    gem "toast"
+
+from Github:
+
+    gem "toast", :git => "https://github.com/robokopp/toast.git"
 
-You need to implement authorization yourself.
+then run
+
+    bundle
+    rails generate toast init
+      create  config/toast-api.rb
+      create  config/toast-api
 
 Example
 =======
 
-Let the table `bananas` have the following schema:
+Let the table _bananas_ have the following schema:
 
      create_table "bananas", :force => true do |t|
        t.string   "name"
@@ -51,104 +63,177 @@ Let the table `bananas` have the following schema:
        t.integer  "apple_id"
      end
 
-and let a corresponding model class have a *acts_as_resource* annotation:
+and let a corresponding model class have this code:
 
      class Banana < ActiveRecord::Base
        belongs_to :apple
        has_many :coconuts
 
-       scope :less_than_100, where("number < 100")
+       scope :less_than_100, where("number < 100")       
+     end
+
+Then we can define the API like this (in `config/toast-api/banana.rb`):
 
-       acts_as_resource do
-         # exposed attributes or association names
-         readables :coconuts, :apple
+      expose(Banana) {
+
+         readables :color
          writables :name, :number
 
-         # exposed class methods of Banana returning an Array of Banana records
-         collections :less_than_100, :all
-       end
-     end
+         via_get {
+            allow do |user, model, uri_params|
+              true
+            end
+         }
+
+         via_patch {
+            allow do |user, model, uri_params|
+              true
+            end          
+         }
+
+         via_delete {
+            allow do |user, model, uri_params|
+              true
+            end          
+         }
+
+         collection(:less_than_100) {
+           via_get {
+             allow do |user, model, uri_params|
+               true
+             end
+           }
+         }
+
+         collection(:all) {
+           max_window 16
+
+           via_get {
+             allow do |user, model, uri_params|
+               true
+             end
+           }
+
+           via_post {
+             allow do |user, model, uri_params|
+               true
+             end
+           }
+         }
+
+         association(:coconuts) {
+           via_get {
+             allow do |user, model, uri_params|
+               true
+             end
+
+             handler do |banana, uri_params|
+               if uri_params[:max_weight] =~ /\A\d+\z/
+                 banana.coconuts.where("weight <= #{uri_params[:max_weight]}")
+               else
+                 banana.coconuts
+               end.order(:weight)
+             end
+           }
+
+           via_post {
+             allow do |user, model, uri_params|
+               true
+             end
+           }          
+
+           via_link {
+             allow do |user, model, uri_params|
+               true
+             end
+           }          
+         }
+
+         association(:apple) {
+           via_get {
+             allow do |user, model, uri_params|
+               true
+             end
+           }          
+         }
+      }
+
+Note, that all `allow`-blocks returning _true_. In practice authorization logic should be applied. An `allow`-block must be defined for each endpoint because it defaults to return `false`, which causes a 401 response.
+
+The above definition exposes the model Banana as such:
+
+### Get a single resource representation:
+    GET http://www.example.com/bananas/23
+    --> 200,  '{"self":     "http://www.example.com/bananas/23"
+                "name":     "Fred",
+                "number":   33,
+                "color":    "yellow",
+                "coconuts": "http://www.example.com/bananas/23/coconuts",
+                "apple":    "http://www.example.com/bananas/23/apple" }'
 
-The above definition inside the `acts_as_resource` block exposes the
-records of the model Banana automatically via a generic controller to
-the outside world, accepting and delivering JSON representations of
-the records. Let the associated models Apple and Coconut be
-exposed as a resource, too:
+The representation of a record is a flat JSON map: _name_ → _value_, in case of associations _name_ → _URI_. The special key _self_ contains the URI from which this record can be fetch alone. _self_ can be treated as a  unique ID of the record (globally unique, if under a FQDN). 
 
-### Get a collection
-    GET /bananas
+### Get a collection (the :all collection)
+    GET http://www.example.com/bananas
     --> 200,  '[{"self":     "http://www.example.com/bananas/23",
                  "name":     "Fred",
                  "number":   33,
+                 "color":    "yellow",
                  "coconuts": "http://www.example.com/bananas/23/coconuts",
                  "apple":    "http://www.example.com/bananas/23/apple,
                 {"self":     "http://www.example.com/bananas/24",
-                  ... }, ... ]
-### Get a customized collection (filtered, paging, etc.)
-    GET /bananas/less_than_100
+                  ... }, ... ]'
+
+The default length of collections is limited to 42, this can be adjusted globally or for each endpoint separately. In this case no more than 16 will be delivered due to the `max_window 16` directive.
+
+### Get a customized collection
+    GET http://www.example.com/bananas/less_than_100
     --> 200, '[{BANANA}, {BANANA}, ...]'
 
-### Get a single resource representation:
-    GET /bananas/23
-    --> 200,  '{"self":     "http://www.example.com/bananas/23"
-                "name":     "Fred",
-                "number":   33,
-                "coconuts": "http://www.example.com/bananas/23/coconuts",
-                "apple":    "http://www.example.com/bananas/23/apple" }'
+Any scope can be published this way as well as any model class method returning a relation. 
+
+### Get an associated collection + filter
+    GET http://www.example.com/bananas/23/coconuts?max_weight=3
+    --> 200, '[{COCONUT},{COCONUT},...]',
 
-### Get an associated collection
-    "GET" /bananas/23/coconuts
-    --> 200, '[{COCNUT},{COCONUT},...]',
+ The COCONUT model must be exposed too. URI parameters can be processed in custom handlers for sorting and filtering. 
 
 ### Update a single resource:
-    PUT /bananas/23, '{"self":   "http://www.example.com/bananas/23"
-                       "name":   "Barney",
-                       "number": 44}'
+    PATCH http://www.example.com/bananas/23, '{"name": "Barney", "number": 44, "foo" => "bar"}'
     --> 200,  '{"self":     "http://www.example.com/bananas/23"
                 "name":     "Barney",
                 "number":   44,
+                "color":    "yellow",
                 "coconuts": "http://www.example.com/bananas/23/coconuts",
                 "apple":    "http://www.example.com/bananas/23/apple"}'
 
+Toast ingores unknown attributes, but prints warnings in it's log file. Only attributes from the 'writables' list will be updated. 
+
 ### Create a new record
-    "POST" /bananas,  '{"name": "Johnny",
-                        "number": 888}'
-    --> 201,  {"self":     "http://www.example.com/bananas/102"
+    POST http://www.example.com/bananas, '{"name": "Johnny", "number": 888}'
+    --> 201, '{"self":     "http://www.example.com/bananas/102"
                "name":     "Johnny",
-               "number":   888,
-               "coconuts": "http://www.example.com/bananas/102/coconuts" ,
-               "apple":    "http://www.example.com/bananas/102/apple }
+               "number":    888,
+               "color":     null,
+               "coconuts": "http://www.example.com/bananas/102/coconuts",
+               "apple":    "http://www.example.com/bananas/102/apple }'
 
 ### Create an associated record
-    "POST" /bananas/23/coconuts, '{COCONUT}'
-    --> 201,  {"self":"http://www.example.com/coconuts/432,
-               ...}
+    POST http://www.example.com/bananas/23/coconuts, '{COCONUT}'
+    --> 201,  {"self":"http://www.example.com/coconuts/432, ...}
 
+  
 ### Delete records
-    DELETE /bananas/23
+    DELETE http://www.example.com/bananas/23
     --> 200
 
-More details and configuration options are documented in the manual.
-
-Installation
-============
-
-With bundler from  (rubygems.org)
+### Linking records
 
-    gem "toast"
+    LINK "http://www.example.com/bananas/23/coconuts", 
+      Link:  "http://www.example.com/coconuts/31"
+    --> 200
 
-the latest Git:
+Toast uses the (unusual) methods LINK and UNLINK in order to express the action of linking or unlinking existing resources. The above request will add _Coconut#31_ to the association _Banana#coconuts_. 
 
-    gem "toast", :git => "https://github.com/robokopp/toast.git"
-
-Remarks
-=======
 
-REST is more than some pretty URIs, the use of the HTTP verbs and
-response codes. It's on the Toast user to invent meaningful media
-types that control the application's state and introduce
-semantics. With toast you can build REST services or tightly coupled
-server-client applications, which ever suits the task best. That's why
-TOAST stands for:
 
->  **TOast Ain't reST**

data/config/routes.rb

@@ -1,29 +1,3 @@
 Rails.application.routes.draw do
-
-  ActiveRecord::Base.descendants.each do |model|
-    next unless model.is_resourceful_model?
-
-    resource_name = model.to_s.pluralize.underscore
-
-    namespaces = []
-
-    # routes must be defined for all defined namespaces of a model
-    model.toast_configs.each do |tc|
-      # once per namespace
-      next if namespaces.include? tc.namespace
-
-      namespaces << tc.namespace
-
-      match("#{tc.namespace}/#{resource_name}(/:id(/:subresource))" => 'toast#catch_all',
-            :constraints => { :id => /\d+/ },
-            :resource => resource_name,
-            :as => resource_name,
-            :defaults => { :format => 'json' })
-
-      match("#{tc.namespace}/#{resource_name}/:subresource" => 'toast#catch_all',
-            :resource => resource_name,
-            :defaults => { :format => 'json' })
-    end
-  end
-
+  mount Toast::RackApp.new, at: '/*toast_path'
 end

data/lib/generators/toast/USAGE

@@ -0,0 +1 @@
+Use this generator to initialize Toast's main configuration file and the API config directory.

data/lib/generators/toast/templates/toast-api.rb.erb

@@ -0,0 +1,10 @@
+toast_settings {
+  max_window 42
+  link_unlink_via_post false
+
+  authenticate do |request|
+    # authenticate the request here (ActionDispatch::Request)
+    # returned object (except false) is passed as first argument to every allow-block for authorization
+    false
+  end
+}

data/lib/generators/toast/toast_generator.rb

@@ -0,0 +1,9 @@
+class ToastGenerator < Rails::Generators::NamedBase
+
+  source_root File.expand_path("../templates", __FILE__)
+
+  def init
+   	template "toast-api.rb.erb", 'config/toast-api.rb' 
+    empty_directory "config/toast-api/"
+  end
+end

data/lib/toast/canonical_request.rb

@@ -0,0 +1,179 @@
+require 'toast/request_helpers'
+
+class Toast::CanonicalRequest
+  include Toast::RequestHelpers
+  include Toast::Errors
+
+  def initialize id, base_config, auth, request
+    @id          = id
+    @base_config = base_config
+    @selected_attributes = request.query_parameters.delete(:toast_select).try(:split,',')
+    @uri_params  = request.query_parameters
+    @base_uri    = base_uri(request)
+    @verb        = request.request_method.downcase
+    @auth        = auth
+    @request     = request
+  end
+
+  def respond
+    if @verb.in? %w(get patch put delete)
+      self.send(@verb)
+    else
+      response :method_not_allowed,
+               headers: {'Allow' => allowed_methods(@base_config)},
+               msg: "method #{@verb.upcase} not supported for collection URIs"
+    end
+  end
+
+
+  private
+  def get
+    if @base_config.via_get.nil?
+      # not declared under expose {}
+      response :method_not_allowed,
+               headers: {'Allow' => allowed_methods(@base_config)},
+               msg: "GET not configured"
+    else
+      begin
+        model = @base_config.via_get.handler.call(
+          @base_config.model_class.find(@id), @uri_params
+        )
+
+        # call allow blocks to authorize
+        if @base_config.via_get.permissions.all?{|p| p.call(@auth, model, @uri_params)}
+          response :ok,
+                   headers: {"Content-Type" => @base_config.media_type},
+                   msg: "sent #{model.class}##{model.id}",
+                   body: represent(model, @base_config)
+        else
+          response :unauthorized, msg: "authorization failed"
+        end
+
+      rescue ActiveRecord::RecordNotFound
+        response :not_found, msg: "#{@base_config.model_class}##{@id} not found"
+
+      rescue BadRequest => error
+        response :bad_request, msg: "`#{error.message}' in: #{error.source_location}"
+
+      rescue => error
+        response :internal_server_error, msg: "exception from via_get handler: " + error.message
+      end
+    end
+  end
+
+  def put
+    patch
+  end
+
+  def patch
+    if @base_config.via_patch.nil?
+      # not declared under expose {}
+      response :method_not_allowed,
+               headers: {'Allow' => allowed_methods(@base_config)},
+               msg: "PATCH not configured"
+    else
+      begin
+        # decode payload
+        payload  = JSON.parse(@request.body.read)
+
+        # remove all attributes not in writables from payload
+        payload.delete_if do |attr,val|
+          unless attr.to_sym.in?(@base_config.writables)
+            Toast.logger.warn "<PATCH #{@request.fullpath}> received attribute `#{attr}' is not writable or unknown"
+            true
+          end
+        end
+
+        model_instance = @base_config.model_class.find(@id)
+        call_allow(@base_config.via_patch.permissions,
+                   @auth, model_instance, @uri_params)
+
+        if call_handler(@base_config.via_patch.handler,
+                        model_instance, payload, @uri_params)
+
+          response :ok, headers: {"Content-Type" => @base_config.media_type},
+                   msg: "updated #{@base_config.model_class}##{@id}",
+                   body: represent(@base_config.model_class.find(@id), @base_config)
+
+        else
+          message = model_instance.errors.count > 0 ?
+                      ": " + model_instance.errors.full_messages.join(',') : ''
+
+          response :conflict,
+                   msg: "patch of #{model_instance.class}##{model_instance.id} aborted#{message}"
+        end
+
+      rescue JSON::ParserError => error
+        response :internal_server_error, msg: "expect JSON body"
+
+      rescue ActiveRecord::RecordNotFound => error
+        response :not_found, msg: error.message
+
+      rescue BadRequest => error
+        response :bad_request, msg: "`#{error.message}' in: #{error.source_location}"
+
+      rescue AllowError => error
+        response :internal_server_error,
+                        msg: "exception raised in allow block: `#{error.orig_error.message}' in #{error.source_location}"
+      rescue HandlerError => error
+        response :internal_server_error,
+                        msg: "exception raised in via_patch handler: `#{error.orig_error.message}' in #{error.source_location}"
+      rescue NotAllowed => error
+        response :unauthorized, msg: "not authorized by allow block in: #{error.source_location}"
+
+      rescue => error
+        response :internal_server_error, msg: "exception from via_patch handler: "+ error.message
+      end
+    end
+  end
+
+  def delete
+    if @base_config.via_delete.nil?
+      # not declared
+      response :method_not_allowed,
+               headers: {'Allow' => allowed_methods(@base_config)},
+               msg: "DELETE not configured"
+    else
+      begin
+
+        model_instance = @base_config.model_class.find(@id)
+
+        call_allow(@base_config.via_delete.permissions,
+                   @auth, model_instance, @uri_params)
+
+        if call_handler(@base_config.via_delete.handler,
+                        model_instance, @uri_params)
+          response :no_content, msg: "deleted #{@base_config.model_class}##{@id}"
+        else
+
+          message = model_instance.errors.count > 0 ?
+                      ": " + model_instance.errors.full_messages.join(',') : ''
+
+          response :conflict,
+                   msg: "deletion of #{model_instance.class}##{model_instance.id} aborted#{message}"
+        end
+
+      rescue AllowError => error
+        return response :internal_server_error,
+                        msg: "exception raised in allow block: `#{error.orig_error.message}' in #{error.source_location}"
+
+      rescue BadRequest => error
+        response :bad_request, msg: "`#{error.message}' in: #{error.source_location}"
+
+      rescue HandlerError => error
+        return response :internal_server_error,
+                        msg: "exception raised in handler: `#{error.orig_error.message}' in #{error.source_location}"
+      rescue NotAllowed => error
+        return response :unauthorized, msg: "not authorized by allow block in: #{error.source_location}"
+
+      rescue ActiveRecord::RecordNotFound => error
+        response :not_found,
+                 msg: error.message
+
+      rescue => error
+        response :internal_server_error,
+                 msg: "exception from via_delete handler: #{error.message}"
+      end
+    end
+  end
+end