restfulness 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ddaa3efca8063cce4459e78242665f30c7aa7beb
-  data.tar.gz: 39fc6f40248c0a0453ce566fc97537920977e529
+  metadata.gz: 656fc9b27618b6b00f0cdc31dff51fc59081881b
+  data.tar.gz: eed7ea6153eb14c67d0888643287ed911bfb477a
 SHA512:
-  metadata.gz: 205f618a6e3d7968e9e365e5a90abbbe335ebc994179da9030bc6d57d2bcafacfa9b001f612beea36490e18a2ed8344a2e19e772d70071b266500ba31832b7ec
-  data.tar.gz: f2c6c07d14351f6f05e270f34df4b23b08dea402a82b0988cc8ed4076d960d379b88c1bc2384ebcfcb9b7b80c372d681a790558d40b241b09bd5c3fea4ca9a11
+  metadata.gz: d06a2ee69944bfd705f22516c246ec49293488e69bc7bc5f7357cbe3830ac1b283e5e5046063c4e22e427d5ddf2541811c2d49b0e285eb742c63c0f132b64564
+  data.tar.gz: b297d63290e7df33142641c2c8d072d97bb4494ece946b8ec6f2ddb4c44e10ac6cd997729689ede5fefb299f492c77b74e82b9646f04793ca49f77c473a99e70

data/README.md

@@ -27,7 +27,7 @@ module Twitter
       end
 
       desc "Return a personal timeline."
-     get :home_timeline do
+      get :home_timeline do
         authenticate!
         current_user.statuses.limit(20)
       end
@@ -128,8 +128,6 @@ run Rack::URLMap.new(
 )
 ```
 
-By default, Restfulness comes with a Rack compatible dispatcher, but in the future it might make sense to add others.
-
 If you want to run Restfulness standalone, simply create a `config.ru` that will load up your application:
 
 ```ruby
@@ -143,7 +141,7 @@ You can then run this with rackup:
 bundle exec rackup
 ```
 
-For an example, checkout the `/example` directory in the source code.
+For a very simple example project, checkout the `/example` directory in the source code.
 
 
 ### Routes
@@ -179,6 +177,7 @@ Resources are like Controllers in a Rails project. They handle the basic HTTP ac
  * `get`
  * `head`
  * `post`
+ * `patch`
  * `put`
  * `delete`
  * `options` - this is the only action provded by default
@@ -192,8 +191,8 @@ class ProjectResource < Restfulness::Resource
     project
   end
 
-  # Update the object
-  def put
+  # Update the existing object with some new attributes
+  def patch
     project.update(params)
   end
 
@@ -290,11 +289,99 @@ request.body               # "{'key':'value'}" - string payload
 request.params             # {'key' => 'value'} - usually a JSON deserialized object
 ```
 
+## Error Handling
+
+If you want your application to return anything other than a 200 (or 202) status, you have a couple of options that allow you to send codes back to the client.
+
+The easiest method is probably just to update the `response` code. Take the following example where we set a 403 response and the model's errors object in the payload:
+
+```ruby
+class ProjectResource < Restfulness::Resource
+  def patch
+    if project.update_attributes(request.params)
+      project
+    else
+      response.status = 403
+      project.errors
+    end
+  end
+end
+```
+
+The favourite method in Restfulness however is to use the `HTTPException` class and helper methods that will raise the error for you. For example:
+
+```ruby
+class ProjectResource < Restfulness::Resource
+  def patch
+    unless project.update_attributes(request.params)
+      forbidden!(project.errors)
+    end
+    project
+  end
+end
+```
+
+The `forbidden!` bang method will call the `error!` method, which in turn will raise an `HTTPException` with the appropriate status code. Exceptions are permitted to include a payload also, so you could override the `error!` method if you wished with code that will automatically re-format the payload. Another example:
+
+```ruby
+# Regular resource
+class ProjectResource < ApplicationResource
+  def patch
+    unless project.update_attributes(request.params)
+      forbidden!(project) # only send the project object!
+    end
+    project
+  end
+end
+
+# Main Application Resource
+class ApplicationResource < Restfulness::Resource
+  # Overwrite the regular error handler so we can provide
+  # our own format.
+  def error!(status, payload = "", opts = {})
+    case payload
+    when ActiveRecord::Base # or your favourite ORM
+      payload = {
+        :errors => payload.errors.full_messages
+      }
+    end
+    super(status, payload, opts)
+  end
+end
+
+```
+
+This can be a really nice way to mold your errors into a standard format. All HTTP exceptions generated inside resources will pass through `error!`, even those that a triggered by a callback. It gives a great way to provide your own more complete result, or even just resort to a simple string.
+
+The currently built in error methods are:
+
+ * `not_modified!`
+ * `bad_request!`
+ * `unauthorized!`
+ * `payment_required!`
+ * `forbidden!`
+ * `resource_not_found!`
+ * `request_timeout!`
+ * `conflict!`
+ * `gone!`
+ * `unprocessable_entity!`
+
+If you'd like to see me more, please send us a pull request! Failing that, you can create your own by writing something along the lines of:
+
+```ruby
+def im_a_teapot!(payload = "")
+  error!(418, payload)
+end
+```
+
+
 ## Caveats and TODOs
 
 Restfulness is still very much a work in progress. Here is a list of things that we'd like to improve or fix:
 
- * Support for more serializers, not just JSON.
+ * Support for more serializers and content types, not just JSON.
+ * Support path methods for automatic URL generation.
+ * Support redirect exceptions.
  * Reloading is a PITA (see note below).
  * Needs more functional testing.
  * Support for before and after filters in resources, although I'm slightly aprehensive about this.
@@ -335,6 +422,10 @@ Restfulness was created by Sam Lown <me@samlown.com> as a solution for building
 
 ## History
 
+### 0.2.0 - October 17, 2013
+
+Refactoring error handling and reporting so that it is easier to use and simpler.
+
 ### 0.1.0 - October 16, 2013
 
 First release!

data/example/README.md

@@ -33,7 +33,7 @@ Curl is your friend!
     curl -v http://localhost:9292/projects
     
     # Try updating it
-    curl -v -X PUT http://localhost:9292/project/project1 -H "Content-Type: application/json" -d "{\"name\":\"First Updated Project\"}"
+    curl -v -X PATCH http://localhost:9292/project/project1 -H "Content-Type: application/json" -d "{\"name\":\"First Updated Project\"}"
 
     # Finally remove it and check the list is empty
     curl -v -X DELETE http://localhost:9292/project/project1

data/example/app.rb

@@ -15,7 +15,7 @@ class ProjectResource < Restfulness::Resource
   def post
     $projects << Project.new(request.params)
   end
-  def put
+  def patch
     project.update(request.params)
   end
   def delete

data/lib/restfulness.rb

@@ -8,6 +8,9 @@ require 'rack/utils'
 require 'rack/showexceptions'
 require 'rack/builder'
 
+
+require "restfulness/resources/events"
+
 require "restfulness/application"
 require "restfulness/dispatcher"
 require "restfulness/exceptions"

data/lib/restfulness/dispatchers/rack.rb

@@ -11,27 +11,12 @@ module Restfulness
         request = Request.new(app)
         prepare_request(env, rack_req, request)
 
-
         # Prepare a suitable response
         response = Response.new(request)
         response.run
 
-
-        # No need to provide an empty response
-        log_response(response.code)
-        [response.code, response.headers, [response.payload || ""]]
-
-      rescue HTTPException => e
-        log_response(e.code)
-        [e.code, {}, [e.payload || ""]]
-
-      #rescue Exception => e
-      #  log_response(500)
-      #  puts
-      #  puts e.message
-      #  puts e.backtrace
-      #  # Something unknown went wrong
-      #  [500, {}, [STATUSES[500]]]
+        log_response(response.status)
+        [response.status, response.headers, [response.payload || ""]]
       end
 
       protected
@@ -60,6 +45,8 @@ module Restfulness
           :post
         when 'PUT'
           :put
+        when 'PATCH'
+          :patch
         when 'OPTIONS'
           :options
         else
@@ -67,8 +54,8 @@ module Restfulness
         end
       end
 
-      def log_response(code)
-        logger.info("Completed #{code} #{STATUSES[code]}")
+      def log_response(status)
+        logger.info("Completed #{status} #{STATUSES[status]}")
       end
 
       def prepare_headers(env)

data/lib/restfulness/exceptions.rb

@@ -3,13 +3,13 @@ module Restfulness
 
   class HTTPException < ::StandardError
 
-    attr_accessor :code, :payload, :headers
+    attr_accessor :status, :payload, :headers
 
-    def initialize(code, payload = nil, opts = {})
-      @code    = code
+    def initialize(status, payload = "", opts = {})
+      @status  = status
       @payload = payload
-      @headers = opts[:headers]
-      super(opts[:message] || STATUSES[code])
+      @headers = opts[:headers] || {}
+      super(opts[:message] || STATUSES[status])
     end
 
   end

data/lib/restfulness/request.rb

@@ -71,7 +71,7 @@ module Restfulness
       end
     end
 
-    [:get, :post, :put, :delete, :head, :options].each do |m|
+    [:get, :post, :put, :patch, :delete, :head, :options].each do |m|
       define_method("#{m}?") do
         action == m
       end

data/lib/restfulness/resource.rb

@@ -1,6 +1,7 @@
 module Restfulness
 
   class Resource
+    include Resources::Events
 
     attr_reader :request, :response
 
@@ -18,6 +19,8 @@ module Restfulness
     end
 
     def call
+      # At some point, we might add custom callbacks here. If you really need them though,
+      # you can wrap around the call method easily.
       send(request.action)
     end
 
@@ -49,14 +52,14 @@ module Restfulness
 
     def check_callbacks
       # Access control
-      raise HTTPException.new(405) unless method_allowed?
-      raise HTTPException.new(401) unless authorized?
-      raise HTTPException.new(403) unless allowed?
+      method_not_allowed! unless method_allowed?
+      unauthorized!       unless authorized?
+      forbidden!          unless allowed?
 
       # The following callbacks only make sense for certain methods
       if [:head, :get, :put, :delete].include?(request.action)
 
-        raise HTTPException.new(404) unless exists?
+        resource_not_found! unless exists?
 
         if [:get, :head].include?(request.action)
           # Resource status
@@ -66,26 +69,18 @@ module Restfulness
       end
     end
 
-    ##
-
-
     protected
 
-    def error(code, payload = nil, opts = {})
-      raise HTTPException.new(code, payload, opts)
-    end
-
     def logger
       Restfulness.logger
     end
 
-
     private
 
     def check_if_modified
       date = request.headers[:if_modified_since]
       if date && date == last_modified.to_s
-        raise HTTPException.new(304)
+        not_modified!
       end
       response.headers['Last-Modified'] = last_modified
     end
@@ -93,7 +88,7 @@ module Restfulness
     def check_etag
       tag = request.headers[:if_none_match]
       if tag && tag == etag.to_s
-        raise HTTPException.new(304)
+        not_modified!
       end
       response.headers['ETag'] = etag
     end

data/lib/restfulness/resources/events.rb

@@ -0,0 +1,45 @@
+module Restfulness
+  module Resources
+
+    # Special events that can be used in replies. The idea here is to cover
+    # the basic messages that most applications will deal with in their 
+    # resources.
+    module Events
+
+      # Event definitions go here. We only support a limited subset
+      # so that we don't end up with loads of methods that are not used.
+      # If you'd like to see another, please send us a pull request!
+      SUPPORTED_EVENTS = [
+        # 300 Events
+        [304, :not_modified],
+
+        # 400 Events
+        [400, :bad_request],
+        [401, :unauthorized],
+        [402, :payment_required],
+        [403, :forbidden],
+        [404, :resource_not_found],
+        [405, :method_not_allowed],
+        [408, :request_timeout],
+        [409, :conflict],
+        [410, :gone],
+        [422, :unprocessable_entity]
+      ]
+
+      # Main error event handler
+      def error!(code, payload = "", opts = {})
+        raise HTTPException.new(code, payload, opts)
+      end
+
+      SUPPORTED_EVENTS.each do |row|
+        define_method("#{row[1]}!") do |*args|
+          payload = args.shift || ""
+          opts    = args.shift || {}
+          error!(row[0], payload, opts)
+        end
+      end
+
+    end
+
+  end
+end

data/lib/restfulness/response.rb

@@ -7,14 +7,11 @@ module Restfulness
     attr_reader :request
 
     # Outgoing data
-    attr_reader :code, :headers, :payload
-
+    attr_reader :status, :headers, :payload
 
     def initialize(request)
       @request = request
-
-      # Default headers
-      @headers = {'Content-Type' => 'application/json; charset=utf-8'}
+      @headers = {}
     end
 
     def run
@@ -31,15 +28,15 @@ module Restfulness
         # Perform the actual work
         result = resource.call
 
-        @code    ||= (result ? 200 : 204)
-        @payload   = MultiJson.encode(result)
+        update_status_and_payload(result.nil? ? 204 : 200, result)
       else
-        logger.error("No route found")
-        # This is not something we can deal with, pass it on
-        @code    = 404
-        @payload = ""
+        update_status_and_payload(404)
       end
-      update_content_length
+
+    rescue HTTPException => e # Deal with HTTP exceptions
+      logger.error(e.message)
+      headers.update(e.headers)
+      update_status_and_payload(e.status, e.payload)
     end
 
     def logger
@@ -47,9 +44,34 @@ module Restfulness
     end
 
     protected
+
+    def update_status_and_payload(status, payload = "")
+      self.status  = status
+      self.payload = payload
+    end
+
+    def status=(code)
+      @status = code
+    end
+
+    def payload=(body)
+      if body.nil? || body.is_a?(String)
+        @payload = body.to_s
+        update_content_headers(:text)
+      else
+        @payload = MultiJson.encode(body)
+        update_content_headers(:json)
+      end
+    end
     
-    def update_content_length
-      @headers['Content-Length'] = @payload.bytesize.to_s
+    def update_content_headers(type = :json)
+      case type
+      when :json
+        headers['Content-Type'] = 'application/json; charset=utf-8'
+      else # Assume text
+        headers['Content-Type'] = 'text/plain; charset=utf-8'
+      end
+      headers['Content-Length'] = payload.to_s.bytesize.to_s
     end
 
   end

data/lib/restfulness/version.rb

@@ -1,3 +1,3 @@
 module Restfulness
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/spec/unit/exceptions_spec.rb

@@ -5,13 +5,13 @@ describe Restfulness::HTTPException do
   describe "#initialize" do
     it "should assign variables" do
       obj = Restfulness::HTTPException.new(200, "payload", :message => 'foo', :headers => {})
-      obj.code.should eql(200)
+      obj.status.should eql(200)
       obj.payload.should eql("payload")
       obj.message.should eql('foo')
       obj.headers.should eql({})
     end
 
-    it "should use status code for message if none provided" do
+    it "should use status status for message if none provided" do
       obj = Restfulness::HTTPException.new(200, "payload")
       obj.message.should eql('OK')
     end

data/spec/unit/resource_spec.rb

@@ -224,22 +224,4 @@ describe Restfulness::Resource do
     end
   end
 
-  describe "#error" do
-
-    class Get418Resource < Restfulness::Resource
-      def get
-        error(418, {})
-      end
-    end
-
-    it "should raise a new exception" do
-      klass = Get418Resource
-      obj = klass.new(request, response)
-      expect {
-        obj.get
-      }.to raise_error(Restfulness::HTTPException, "I'm A Teapot")
-    end
-
-  end
-
 end

data/spec/unit/resources/events_spec.rb

@@ -0,0 +1,68 @@
+
+require 'spec_helper'
+
+describe Restfulness::Resources::Events do
+
+  let :app do
+    Class.new(Restfulness::Application) do
+      routes do
+        # empty
+      end
+    end
+  end
+  let :request do
+    Restfulness::Request.new(app)
+  end
+  let :response do
+    Restfulness::Response.new(request)
+  end
+
+
+  describe "#error" do
+
+    class Get418Resource < Restfulness::Resource
+      def get
+        error!(418, {})
+      end
+    end
+
+    it "should raise a new exception" do
+      klass = Get418Resource
+      obj = klass.new(request, response)
+      expect {
+        obj.get
+      }.to raise_error(Restfulness::HTTPException, "I'm A Teapot")
+    end
+  end
+
+  describe "generic bang error events" do
+
+    let :klass do
+      Class.new(Restfulness::Resource)
+    end
+
+    let :obj do
+      klass.new(request, response)
+    end
+
+    it "should support bad_request!" do
+      expect {
+        obj.instance_eval do
+          bad_request!
+        end
+      }.to raise_error(Restfulness::HTTPException, "Bad Request")
+    end
+
+    it "should support bad_request! with paramters" do
+      obj.should_receive(:error!).with(400, {:pay => 'load'}, {})
+      obj.instance_eval do
+        bad_request!({:pay => 'load'}, {})
+      end
+    end
+
+
+  end
+
+  
+
+end

data/spec/unit/response_spec.rb

@@ -26,8 +26,9 @@ describe Restfulness::Response do
   describe "#initialize" do
     it "should assign request and headers" do
       obj.request.should eql(request)
-      obj.headers.should eql({'Content-Type' => 'application/json; charset=utf-8'})
-      obj.code.should be_nil
+      obj.headers.should eql({})
+      obj.status.should be_nil
+      obj.payload.should be_nil
     end
   end
 
@@ -36,8 +37,9 @@ describe Restfulness::Response do
       it "should not do anything" do
         request.stub(:route).and_return(nil)
         obj.run
-        obj.code.should eql(404)
+        obj.status.should eql(404)
         obj.payload.should be_empty
+        obj.headers['Content-Type'].should match(/text\/plain/)
         obj.headers['Content-Length'].should eql(0.to_s)
       end
     end
@@ -54,12 +56,76 @@ describe Restfulness::Response do
         resource.should_receive(:call).and_return({:foo => 'bar'})
         route.stub(:build_resource).and_return(resource)
         obj.run 
-        obj.code.should eql(200)
+        obj.status.should eql(200)
         str = "{\"foo\":\"bar\"}"
         obj.payload.should eql(str)
+        obj.headers['Content-Type'].should match(/application\/json/)
         obj.headers['Content-Length'].should eql(str.bytesize.to_s)
-      end      
+      end
+
+      it "should call resource and set 204 result if no content" do
+        request.stub(:route).and_return(route)
+        request.action = :get
+        resource = double(:Resource)
+        resource.should_receive(:check_callbacks)
+        resource.should_receive(:call).and_return(nil)
+        route.stub(:build_resource).and_return(resource)
+        obj.run
+        obj.status.should eql(204)
+        obj.headers['Content-Type'].should match(/text\/plain/)
+      end
+
+      it "should set string content type if payload is a string" do
+        request.stub(:route).and_return(route)
+        request.action = :get
+        resource = double(:Resource)
+        resource.should_receive(:check_callbacks)
+        resource.should_receive(:call).and_return("This is a text message")
+        route.stub(:build_resource).and_return(resource)
+        obj.run
+        obj.status.should eql(200)
+        obj.headers['Content-Type'].should match(/text\/plain/)
+      end
     end
+
+    context "with exceptions" do
+      let :route do
+        app.router.routes.first
+      end
+
+      it "should update the status and payload" do
+        request.stub(:route).and_return(route)
+        request.action = :get
+        resource = double(:Resource)
+        txt = "This is a text error"
+        resource.stub(:check_callbacks) do
+          raise Restfulness::HTTPException.new(418, txt)
+        end
+        route.stub(:build_resource).and_return(resource)
+        obj.run
+        obj.status.should eql(418)
+        obj.headers['Content-Type'].should match(/text\/plain/)
+        obj.payload.should eql(txt)
+      end
+
+      it "should update the status and provide JSON payload" do
+        request.stub(:route).and_return(route)
+        request.action = :get
+        resource = double(:Resource)
+        err = {:error => "This is a text error"}
+        resource.stub(:check_callbacks) do
+          raise Restfulness::HTTPException.new(418, err)
+        end
+        route.stub(:build_resource).and_return(resource)
+        obj.run
+        obj.status.should eql(418)
+        obj.headers['Content-Type'].should match(/application\/json/)
+        obj.payload.should eql(err.to_json)
+      end
+
+
+    end
+
   end
 
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: restfulness
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Sam Lown
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-16 00:00:00.000000000 Z
+date: 2013-10-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -134,6 +134,7 @@ files:
 - lib/restfulness/path.rb
 - lib/restfulness/request.rb
 - lib/restfulness/resource.rb
+- lib/restfulness/resources/events.rb
 - lib/restfulness/response.rb
 - lib/restfulness/route.rb
 - lib/restfulness/router.rb
@@ -148,6 +149,7 @@ files:
 - spec/unit/path_spec.rb
 - spec/unit/request_spec.rb
 - spec/unit/resource_spec.rb
+- spec/unit/resources/events_spec.rb
 - spec/unit/response_spec.rb
 - spec/unit/route_spec.rb
 - spec/unit/router_spec.rb
@@ -184,6 +186,7 @@ test_files:
 - spec/unit/path_spec.rb
 - spec/unit/request_spec.rb
 - spec/unit/resource_spec.rb
+- spec/unit/resources/events_spec.rb
 - spec/unit/response_spec.rb
 - spec/unit/route_spec.rb
 - spec/unit/router_spec.rb