http_range 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6f193e3a32d1e236790886073848643050da5d0b
-  data.tar.gz: 99b3dc5188a26fb91d4bf6565cb253bf735757eb
+  metadata.gz: d22f33d1f2262be5ab34420858513ef205e2c7f8
+  data.tar.gz: 15d172574a2cc0addaad0fa99c595c9c24a34b78
 SHA512:
-  metadata.gz: 06330411edb69fa887cb44cec4d9168951d0db998ad90e0db0887adb987f76d6bd45895870aa4219f4ea329b283a8e27061a4838d26af68cea7f3802ef1f5fc5
-  data.tar.gz: 3ad46bb2d5c68534374b87efdb6735ed57cc7de81ef1225adc6e2ae868e6f4e973bac19116f328f0e795b0ed8a8d985573b9aa12fbc7997fcd69bb4bd99504b1
+  metadata.gz: ea84d9b2e7b591e7f953f93be6762a48238e4bcde1f372a905ac55d9ad06838e63646b231c82dfdb2dc644fcb6367330535cdb02c28dcb4e704b9ec35c67acef
+  data.tar.gz: 45a7a78e40e059a99118869a3f9815bf91ea1167927daeb7a9a515ad5333d0402f5c33005569dd30d13ccee841a862f12553693e4cf80e26bdd957942f8b70e8

data/README.md

@@ -35,6 +35,37 @@ http_range.first_inclusive # => true
 http_range.last_inclusive  # => false
 ```
 
+Or, in a Rack app:
+
+```ruby
+# Range: id a..z[; max=100
+# found in env['HTTP_RANGE']
+app = Rack::Builder.app do
+  use HTTPRange::Middleware::AcceptRanges
+
+  run lambda do |env|
+
+    env['rack.range.attribute']       # => 'id'
+    env['rack.range.first']           # => 'a'
+    env['rack.range.last']            # => 'z'
+    env['rack.range.first_inclusive'] # => true
+    env['rack.range.last_inclusive']  # => false
+    env['rack.range.order']           # => nil
+    env['rack.range.max']             # => '100'
+
+    [200, {}, "Body"]
+  end
+end
+```
+
+## Inspiration
+
+Inspired by Heroku's [Interagent HTTP API Design][2] as well as brandur's
+[HTTPAccept][3] library.
+
+ [2]: https://github.com/interagent/http-api-design
+ [3]: https://github.com/brandur/http_accept
+
 ## Contributing
 
 1. Fork it ( https://github.com/[my-github-username]/http_range/fork )

data/SPEC.md

@@ -0,0 +1,25 @@
+# Range HTTP Header Spec for HTTP APIs
+
+Largely from [Heroku's Range header documentation][1].
+
+ [1]: https://devcenter.heroku.com/articles/platform-api-reference#ranges
+
+```
+Range: <attr> [<]>]<first>..<last>[<[>][; order=<asc|desc>][; max=<int>]
+```
+
+The `[` and `]` exclusion operators are [described thusly][2], assuming a range
+from `a` to `z`:
+
+ [2]: https://github.com/interagent/http-api-design/issues/36#issuecomment-48226357
+
+ * `a..z` to get everything
+ * `a..` to get the default size worth of results greater than or equal to a
+ * `..z` to get the default size worth of results less than or equal to z
+ * `]a..` results greater than a (not greater than or equal as above)
+ * `..z[` results less than z (not less than or equal as above)
+
+Intentional deviations from Heroku's design:
+
+ * Separate `order` and `max` into separate parameters delimited by `;` to avoid
+   two needless rounds of parsing (`;` and `,`)

data/http_range.gemspec

@@ -18,7 +18,9 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ['lib']
 
-  spec.add_development_dependency 'bundler', '~> 1.7'
-  spec.add_development_dependency 'rake',    '~> 10.0'
-  spec.add_development_dependency 'rspec',   '~> 3.1'
+
+  spec.add_development_dependency 'bundler',   '~> 1.7'
+  spec.add_development_dependency 'rack-test', '~> 0.6.2'
+  spec.add_development_dependency 'rake',      '~> 10.0'
+  spec.add_development_dependency 'rspec',     '~> 3.1'
 end

data/lib/http_range/middleware/accept_ranges.rb

@@ -0,0 +1,80 @@
+require 'json'
+
+class HTTPRange
+module Middleware
+
+  # Rack Middleware for parsing `Range` headers. See [SPEC][1] for
+  # more details.
+  #
+  #  [1]: https://github.com/h3h/http_range/blob/master/SPEC.md
+  #
+  # Request Header Format:
+  #
+  #   Range: <attr> <first>..<last>[; order=<asc|desc>][; max=<int>]
+  #
+  # Examples:
+  #
+  #   Range: id 29f99177-36e9-466c-baef-f855e1ab731e..6c714be1-d901-4c40-adb3-22c9a8cda950; max=100
+  #   Range: created_at 2014-09-18T16:30:38Z..2014-09-18T17:30:33Z; order=desc
+  #
+  # Output:
+  #
+  # `env` keys exposed from the parsed content of the requested Range header:
+  #
+  #   - env['rack.range.attribute']: attribute name
+  #   - env['rack.range.first']:           first value in the range
+  #   - env['rack.range.last']:            last value in the range
+  #   - env['rack.range.first_inclusive']: whether the first value is inclusive
+  #   - env['rack.range.last_inclusive']:  whether the last value is inclusive
+  #   - env['rack.range.order']:           order param
+  #   - env['rack.range.max']:             max param
+  #
+  # Usage:
+  #
+  #   use HTTPRange::Middleware::AcceptRanges
+  #
+  class AcceptRanges
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      range_header = env['HTTP_RANGE']
+      if range_header && range_header.length > 0
+        http_range = HTTPRange.parse(range_header)
+
+        set_env_fields(
+          env:             env,
+          attribute:       http_range.attribute,
+          first:           http_range.first,
+          last:            http_range.last,
+          first_inclusive: http_range.first_inclusive,
+          last_inclusive:  http_range.last_inclusive,
+          order:           http_range.order,
+          max:             http_range.max,
+        )
+      end
+
+      @app.call(env)
+    rescue HTTPRange::MalformedRangeHeaderError => ex
+      [400, {'Content-Type' => 'application/json'}, [{errors: [ex.message]}.to_json]]
+    end
+
+  private
+
+    # Expose fields in the given env hash for the rest of the application.
+    #
+    # @param env      [Hash]
+    # @param **fields [Hash]
+    #
+    # @return [nil]
+    #
+    def set_env_fields(env:, **fields)
+      fields.each do |field, value|
+        env["rack.range.#{field}"] = value
+      end
+    end
+  end
+
+end
+end

data/lib/http_range/parser.rb

@@ -3,6 +3,8 @@ class HTTPRange
     # Accepts the HTTP Range header string to parse.
     #
     def initialize(header_string)
+      raise MalformedRangeHeaderError, "Missing Range header value." if blank?(header_string)
+
       @header_string = header_string.dup
     end
 

data/lib/http_range/version.rb

@@ -1,3 +1,3 @@
 class HTTPRange
-  VERSION = "1.0.0"
+  VERSION = '1.1.0'
 end

data/lib/http_range.rb

@@ -22,3 +22,4 @@ class HTTPRange
 end
 
 require 'http_range/parser'
+require 'http_range/middleware/accept_ranges'

data/spec/http_range_spec.rb

@@ -6,7 +6,7 @@ RSpec.describe HTTPRange do
     subject { described_class.parse(header) }
 
     context "for a correctly formatted Range header" do
-      let(:header) { "Range: id 29f99177-36e9-466c-baef-f855e1ab731e..6c714be1-d901-4c40-adb3-22c9a8cda950[; max=100" }
+      let(:header) { 'Range: id 29f99177-36e9-466c-baef-f855e1ab731e..6c714be1-d901-4c40-adb3-22c9a8cda950[; max=100' }
 
       it "returns an instance of the class" do
         expect(subject).to be_an(HTTPRange)
@@ -62,5 +62,11 @@ RSpec.describe HTTPRange do
 
       it { expect { subject }.to raise_error(HTTPRange::MalformedRangeHeaderError) }
     end
+
+    context "for a nil Range header" do
+      let(:header) { nil }
+
+      it { expect { subject }.to raise_error(HTTPRange::MalformedRangeHeaderError) }
+    end
   end
 end

data/spec/middleware/accept_ranges_spec.rb

@@ -0,0 +1,41 @@
+require 'http_range'
+require 'spec_helper'
+
+RSpec.describe HTTPRange::Middleware::AcceptRanges do
+  let(:app)        { ->(env) { [200, env, 'body'] } }
+  let(:middleware) { HTTPRange::Middleware::AcceptRanges.new(app) }
+
+  context "without a Range header" do
+    let(:headers) { {} }
+
+    before { @response = call_with_headers(middleware, headers) }
+
+    it { expect(@response.status).to eq 200 }
+    it { expect(@response['rack.range.attribute']).to be_nil }
+    it { expect(@response['rack.range.first']).to be_nil }
+    it { expect(@response['rack.range.last']).to be_nil }
+    it { expect(@response['rack.range.first_inclusive']).to be_nil }
+    it { expect(@response['rack.range.last_inclusive']).to be_nil }
+    it { expect(@response['rack.range.order']).to be_nil }
+    it { expect(@response['rack.range.max']).to be_nil }
+  end
+
+  context "with a valid Range header" do
+    let(:headers) { {'HTTP_RANGE' => 'Range: id a..z[; max=100'} }
+
+    before { @response = call_with_headers(middleware, headers) }
+
+    it { expect(@response.status).to eq 200 }
+    it { expect(@response['rack.range.attribute']).to eq('id') }
+    it { expect(@response['rack.range.first']).to eq('a') }
+    it { expect(@response['rack.range.last']).to eq('z') }
+    it { expect(@response['rack.range.first_inclusive']).to eq(true) }
+    it { expect(@response['rack.range.last_inclusive']).to eq(false) }
+    it { expect(@response['rack.range.order']).to be_nil }
+    it { expect(@response['rack.range.max']).to eq('100') }
+  end
+
+  def call_with_headers(middleware, headers)
+    Rack::MockRequest.new(middleware).get('/', headers)
+  end
+end

data/spec/spec_helper.rb

@@ -1,3 +1,4 @@
+require 'rack/test'
 require 'rspec/core'
 
 RSpec.configure do |config|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: http_range
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Brad Fults
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-18 00:00:00.000000000 Z
+date: 2014-09-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.2
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -64,11 +78,14 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- SPEC.md
 - http_range.gemspec
 - lib/http_range.rb
+- lib/http_range/middleware/accept_ranges.rb
 - lib/http_range/parser.rb
 - lib/http_range/version.rb
 - spec/http_range_spec.rb
+- spec/middleware/accept_ranges_spec.rb
 - spec/spec_helper.rb
 homepage: ''
 licenses:
@@ -96,4 +113,5 @@ specification_version: 4
 summary: Assists in parsing HTTP Range headers.
 test_files:
 - spec/http_range_spec.rb
+- spec/middleware/accept_ranges_spec.rb
 - spec/spec_helper.rb