rack-jsonr 0.1.1

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MDA2OThmZDYxODcxMjA3ZjQzMjc0YzJjMzhjMDdkYmNmM2NhZjk1OQ==
+  data.tar.gz: !binary |-
+    ODE2M2M2ZTgzM2I0MjNjMjRlOTgxZGI0Mjk4MTc0MDUzNTUxOWRkZg==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    ODk0ZmU3YWFiZmViMDI2YTVhYTM4NjNkMDNlNjk5MjhiOGRhY2NiNWMzNDdj
+    OTg4MmNiOTc0NDliYWEyOWM0YjE2ZDJjNDMxMDVmNzg2Y2JkZDMzMmI5ZmNl
+    NGM5MWFlYjdmNGMyNGM2MDUxYjYwYmViNmU1MDZmOGVhODY5NGE=
+  data.tar.gz: !binary |-
+    ZTJjYTFkNjNkMzFiNjYwZGQ4YWUxMTc3NDZlYjBjZDRjOTlmMjIyMjA3YTBj
+    ZjZkN2U1MTJkYmM5NDBkYjljNDJiYzFlNzU4NzZkYmE2MTA1Y2JiYmZkMDcy
+    MGJkYjMxZDNmODZhM2FhNGZiMzg5NWM4NzVlMDdkZjk5MDJkNDM=

data/.gitignore

@@ -0,0 +1,21 @@
+*.gem
+*.rbc
+.bundle
+.config
+coverage
+InstalledFiles
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+# YARD artifacts
+.yardoc
+_yardoc
+doc/
+.DS_Store
+.idea/
+Gemfile.lock

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/README.md

@@ -0,0 +1,97 @@
+rack-jsonr
+===========
+
+A Rack middleware for delivering JSONR (JSON as a Resource). With JSONR you can use get, post, put, and delete verbs, as
+ well as access the http status, response headers, and the json body, even if there are errors.
+
+## Setting Up JSONR
+
+Install the gem:
+
+  gem install rack-jsonr
+
+In your Gemfile:
+
+  gem 'rack-jsonr', :require => 'rack/jsonr'
+
+You activate JSONR by including it your config.ru file:
+
+ ```
+ use Rack::JSONR
+ run Sinatra::Application
+ ```
+
+## Benefits of JSONR
+
+There are several benefits to using JSONR over JSONP...
+
+### Ability to Use POST, PUT and DELETE Verbs
+
+You can now make POST, PUT and DELETE requests through JSONR calls by including request_method=VERB in your query:
+
+```
+http://example.com/request?first_name=Caleb&request_method=PUT&callback=_jqjsp
+```
+
+That's it. Rails and Sinatra routes will now recognize it as a PUT request.
+
+### Access to HTTP Status and Headers
+
+With JSONR, the returned "http status" is always forced at 200 to ensure the browser always processes the
+response. The real http status is included along with response headers as additional arguments in the
+callback. This removes much of the limitations of JSONP.
+
+### Access to Rich Error Data from the Client
+
+One big frustration of standard JSONP is that when there is an error (http status greater than 200) there is no way to
+access the returned JSON. This makes it difficult to handle form errors, for example.
+
+With JSONR errors, the "http status" is forced at 200, which means you still have access to the response body,
+http status, and headers.
+
+## Using JSONR Responses through Existing Libraries
+
+You can use jQuery or any other libraries that support JSONP with two caveats:
+
+1. All callbacks will be returns as "success", even if there are errors, since the http status is always returned as 200.
+ Therefore, you'll will need to parse the body of the response to determine if there are errors.
+
+2. By default you won't have access to the http status and headers returned by JSONR since libraries like jQuery and
+ jQuery-JSONP only read the first arg in the server callback.
+
+However, there is hope...
+
+## Using JSONR with jQuery-JSONP
+
+I'm experimenting with a forked version of jQuery-JSONP, which extends the library to read JSONR while still being
+backwards compatible with JSONP. It only changes two public methods:
+
+#### 1. Two optional arguments were appended to the success callback:
+
+##### success - `function` (`undefined`)
+
+A function to be called if the request succeeds. The function gets passed three arguments: The JSON object returned from the server, a string describing the status (always `"success"`) and, *_as of version 2.4.0_* the `xOptions` object.
+
+```js
+function (json, textStatus, xOptions, httpStatus, httpHeaders) {
+  this; // the xOptions object or xOptions.context if provided
+}
+```
+
+#### 2. Three optional arguments were appended to the error callback:
+
+##### error - `function` (`undefined`)
+
+A function to be called if the request fails. The function is passed two arguments: The `xOptions` object and a string describing the type of error that occurred. Possible values for the second argument are `"error"` (the request finished but the JSONR callback was not called) or `"timeout"`.
+
+```js
+function (xOptions, textStatus, json, httpStatus, httpHeaders) {
+  this; // the xOptions object or xOptions.context if provided
+}
+```
+
+## What's Next?
+
+We need to add tests.
+
+

data/Rakefile

@@ -0,0 +1,16 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+require 'fileutils'
+include FileUtils
+
+# Default Rake task is compile
+#task :default => :compile
+
+########################################################################
+
+Rake::TestTask.new do |t|
+  t.libs.push "lib"
+  t.libs.push "test"
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end

data/lib/rack/jsonr.rb

@@ -0,0 +1,2 @@
+require_relative 'jsonr/jsonr'
+require_relative 'jsonr/version'

data/lib/rack/jsonr/jsonr.rb

@@ -0,0 +1,68 @@
+require 'rack'
+
+module Rack
+  # A Rack middleware for providing JSONP in a usable way - accepts GET/POST/PUT/DELETE verbs and http status and
+  # headers are readable from the body.
+  #
+  # Based on Rack-JSONP by Flinn Mueller (http://actsasflinn.com/)
+  #
+  class JSONR
+    include Rack::Utils
+
+    def initialize(app)
+      @app = app
+    end
+
+    # Proxies the request to the application, stripping out the JSONP callback
+    # method and padding the response with the appropriate callback format if
+    # the returned body is application/json
+    #
+    # Changes nothing if no <tt>callback</tt> param is specified.
+    #
+    def call(env)
+      status, headers, response = @app.call(env)
+
+      headers = HeaderHash.new(headers)
+      request = Rack::Request.new(env)
+      params = request.params
+
+      if is_jsonp_request?(request) and params['request_method'].present?
+        env['REQUEST_METHOD'] = params['request_method'].upcase if ['POST','PUT','DELETE'].include?(params['request_method'].upcase)
+      end
+
+      if is_jsonp_request?(request) and is_json_response?(headers)
+        response = format_jsonp(request.params.delete('callback'), status, headers, response)
+        status = 200
+
+        # No longer json, its javascript!
+        headers['Content-Type'] = headers['Content-Type'].gsub('json', 'javascript')
+
+        # Set new Content-Length, if it was set before we mutated the response body
+        if headers['Content-Length']
+          length = response.to_ary.inject(0) { |len, part| len + bytesize(part) }
+          headers['Content-Length'] = length.to_s
+        end
+      end
+      [status, headers, response]
+    end
+
+    private
+
+    def is_json_response?(headers)
+      headers.key?('Content-Type') && headers['Content-Type'].include?('application/json')
+    end
+
+    def is_jsonp_request?(request)
+      @is_jsonp_request ||= (request.params.include?('callback') and request.get?)
+    end
+
+    # Formats the JSONP padding to include body, headers and http status
+    #
+    def format_jsonp(callback, status, headers, response, x_headers={}, body='')
+      headers.each {|k,v| x_headers[k] = v if (k =~ /^X-.+/i) }
+      response.each {|v| body << v.to_s }
+      ["#{callback}(#{body}, #{status}, #{x_headers})"]
+    end
+
+  end
+end

data/lib/rack/jsonr/version.rb

@@ -0,0 +1,3 @@
+class Rack::JSONR
+  VERSION = '0.1.1'
+end

data/rack-jsonr.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'rack/jsonr'
+
+Gem::Specification.new do |gem|
+  gem.name        = 'rack-jsonr'
+  gem.version     = Rack::JSONR::VERSION
+  gem.date        = '2013-03-17'
+  gem.summary     = %q{A Rack middleware for providing enhanced JSONP-type access, but with get, post, put, and delete
+                       verbs as well as http status, headers, and a json body that can be read when there are errors.}
+  gem.authors     = ['Caleb Clark']
+  gem.email       = ['cclark@fanforce.com']
+  gem.homepage    = 'http://github.com/calebclark/rack-jsonr'
+
+  gem.files         = `git ls-files`.split($/)
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ['lib']
+
+  gem.add_development_dependency 'rack'
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: rack-jsonr
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Caleb Clark
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-03-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- cclark@fanforce.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- README.md
+- Rakefile
+- lib/rack/jsonr.rb
+- lib/rack/jsonr/jsonr.rb
+- lib/rack/jsonr/version.rb
+- rack-jsonr.gemspec
+homepage: http://github.com/calebclark/rack-jsonr
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: A Rack middleware for providing enhanced JSONP-type access, but with get,
+  post, put, and delete verbs as well as http status, headers, and a json body that
+  can be read when there are errors.
+test_files: []