Merge pull request #223 from madlep/rack_mapped

Support webmachine being mapped inside a parent rack app

Author: bethesque

documentation/adapters.md

@@ -10,14 +10,16 @@ run on any webserver that provides a Rack interface. It also lets it run on
 In order to be compatible with popular deployment stacks,
 Webmachine has a [Rack](https://github.com/rack/rack) adapter (thanks to Jamis Buck).
 
-Webmachine can be used with Rack middlware features such as Rack::Map and Rack::Cascade as long as:
-
-1. The Webmachine app is mounted at the root directory.
-2. Any requests/responses that are handled by the Webmachine app are not modified by the middleware. The behaviours that are encapsulated in Webmachine assume that no modifications
+Webmachine can be used with Rack middlware features such as Rack::Map and Rack::Cascade as long as any requests/responses that are handled by the Webmachine app are **not** modified by the middleware. The behaviours that are encapsulated in Webmachine assume that no modifications
 are done to requests or response outside of Webmachine.
 
 Keep in mind that Webmachine already supports many things that Rack middleware is used for with other HTTP frameworks (eg. etags, specifying supported/preferred Accept and Content-Types).
 
+The base `Webmachine::Adapters::Rack` class assumes the Webmachine application
+is mounted at the route path `/` (i.e. not using `Rack::Builder#map` or Rails
+`ActionDispatch::Routing::Mapper::Base#mount`). In order to
+map to a subpath, use the `Webmachine::Adapters::RackMapped` adapter instead.
+
 For an example of using Webmachine with Rack middleware, see the [Pact Broker][middleware-example].
 
 See the [Rack Adapter API docs][rack-adapter-api-docs] for more information.

lib/webmachine/adapters/rack.rb

@@ -12,9 +12,12 @@ module Adapters
     # A minimal "shim" adapter to allow Webmachine to interface with Rack. The
     # intention here is to allow Webmachine to run under Rack-compatible
     # web-servers, like unicorn and pow.
+    #
     # The adapter expects your Webmachine application to be mounted at the root path -
     # it will NOT allow you to nest your Webmachine application at an arbitrary path
     # eg. map "/api" { run MyWebmachineAPI }
+    # To use map your Webmachine application at an arbitrary path, use the
+    # `Webmachine::Adapters::RackMapped` subclass instead.
     #
     # To use this adapter, create a config.ru file and populate it like so:
     #
@@ -59,10 +62,7 @@ def call(env)
         headers = Webmachine::Headers.from_cgi(env)
 
         rack_req = ::Rack::Request.new env
-        request = Webmachine::Request.new(rack_req.request_method,
-                                          rack_req.url,
-                                          headers,
-                                          RequestBody.new(rack_req))
+        request = build_webmachine_request(rack_req, headers)
 
         response = Webmachine::Response.new
         application.dispatcher.dispatch(request, response)
@@ -95,6 +95,26 @@ def call(env)
         rack_res.finish
       end
 
+      protected
+      def routing_tokens(rack_req)
+        nil # no-op for default, un-mapped rack adapter
+      end
+
+      def base_uri(rack_req)
+        nil # no-op for default, un-mapped rack adapter
+      end
+
+      private
+      def build_webmachine_request(rack_req, headers)
+        Webmachine::Request.new(rack_req.request_method,
+                                rack_req.url,
+                                headers,
+                                RequestBody.new(rack_req),
+                                routing_tokens(rack_req),
+                                base_uri(rack_req)
+                               )
+      end
+
       class RackResponse
         ONE_FIVE = '1.5'.freeze
 
@@ -167,5 +187,40 @@ def each
       end # class RequestBody
     end # class Rack
 
+    # Provides the same functionality as the parent Webmachine::Adapters::Rack
+    # adapter, but allows the Webmachine application to be hosted at an
+    # arbitrary path in a parent Rack application (as in Rack `map` or Rails
+    # routing `mount`)
+    #
+    # This functionality is separated out from the parent class to preserve
+    # backward compatibility in the behaviour of the parent Rack adpater.
+    #
+    # To use the adapter in a parent Rack application, map the Webmachine
+    # application as follows in a rackup file or Rack::Builder:
+    #
+    #   map '/foo' do
+    #     run SomeotherRackApp
+    #
+    #     map '/bar' do
+    #       run MyWebmachineApp.adapter
+    #     end
+    #   end
+    class RackMapped < Rack
+      protected
+      def routing_tokens(rack_req)
+        routing_match = rack_req.path_info.match(Webmachine::Request::ROUTING_PATH_MATCH)
+        routing_path = routing_match ? routing_match[1] : ""
+        routing_path.split(SLASH)
+      end
+
+      def base_uri(rack_req)
+        # rack SCRIPT_NAME env var doesn't end with "/". This causes weird
+        # behavour when URI.join concatenates URI components in
+        # Webmachine::Decision::Flow#n11
+        script_name = rack_req.script_name + SLASH
+        URI.join(rack_req.base_url, script_name)
+      end
+    end
+
   end # module Adapters
 end # module Webmachine

lib/webmachine/dispatcher/route.rb

@@ -79,23 +79,21 @@ def initialize(path_spec, *args)
         raise ArgumentError, t('not_resource_class', :class => resource.name) unless resource < Resource
       end
 
-      PATH_MATCH = /^\/(.*)/.freeze
-
       # Determines whether the given request matches this route and
       # should be dispatched to the {#resource}.
       # @param [Reqeust] request the request object
       def match?(request)
-        tokens = request.uri.path.match(PATH_MATCH)[1].split(SLASH)
+        tokens = request.routing_tokens
         bind(tokens, {}) && guards.all? { |guard| guard.call(request) }
       end
 
       # Decorates the request with information about the dispatch
       # route, including path bindings.
       # @param [Request] request the request object
       def apply(request)
-        request.disp_path = request.uri.path.match(PATH_MATCH)[1]
+        request.disp_path = request.routing_tokens.join(SLASH)
         request.path_info = @bindings.dup
-        tokens = request.disp_path.split(SLASH)
+        tokens = request.routing_tokens
         depth, trailing = bind(tokens, request.path_info)
         request.path_tokens = trailing || []
       end

lib/webmachine/request.rb

@@ -8,10 +8,11 @@ module Webmachine
   # should be instantiated by {Adapters} when a request is received
   class Request
     HTTP_HEADERS_MATCH = /^(?:[a-z0-9])+(?:_[a-z0-9]+)*$/i.freeze
+    ROUTING_PATH_MATCH = /^\/(.*)/.freeze
 
     extend Forwardable
 
-    attr_reader :method, :uri, :headers, :body
+    attr_reader :method, :uri, :headers, :body, :routing_tokens, :base_uri
     attr_accessor :disp_path, :path_info, :path_tokens
 
     # @param [String] method the HTTP request method
@@ -20,9 +21,14 @@ class Request
     # @param [Headers] headers the HTTP request headers
     # @param [String,#to_s,#each,nil] body the entity included in the
     #   request, if present
-    def initialize(method, uri, headers, body)
+    def initialize(method, uri, headers, body, routing_tokens=nil, base_uri=nil)
       @method, @headers, @body = method, headers, body
       @uri = build_uri(uri, headers)
+      @routing_tokens = routing_tokens || @uri.path.match(ROUTING_PATH_MATCH)[1].split(SLASH)
+      @base_uri = base_uri || @uri.dup.tap do |u|
+        u.path = SLASH
+        u.query = nil
+      end
     end
 
     def_delegators :headers, :[]
@@ -53,16 +59,6 @@ def has_body?
       !(body.nil? || body.empty?)
     end
 
-    # The root URI for the request, ignoring path and query. This is
-    # useful for calculating relative paths to resources.
-    # @return [URI]
-    def base_uri
-      @base_uri ||= uri.dup.tap do |u|
-        u.path = SLASH
-        u.query = nil
-      end
-    end
-
     # Returns a hash of query parameters (they come after the ? in the
     # URI). Note that this does NOT work in the same way as Rails,
     # i.e. it does not support nested arrays and hashes.

spec/webmachine/adapters/rack_spec.rb

@@ -14,6 +14,16 @@
   end
 end
 
+describe Webmachine::Adapters::RackMapped do
+  it_should_behave_like :adapter_lint do
+    it "should set Server header" do
+      response = client.request(Net::HTTP::Get.new("/test"))
+      expect(response["Server"]).to match(/Webmachine/)
+      expect(response["Server"]).to match(/Rack/)
+    end
+  end
+end
+
 describe Webmachine::Adapters::Rack::RackResponse do
   context "on Rack < 1.5 release" do
     before { allow(Rack).to receive_messages(:release => "1.4") }
@@ -55,3 +65,59 @@
     end
   end
 end
+
+describe Webmachine::Adapters::RackMapped do
+  class CreateResource < Webmachine::Resource
+    def allowed_methods
+      ["POST"]
+    end
+
+    def content_types_accepted
+      [["application/json", :from_json]]
+    end
+
+    def content_types_provided
+      [["application/json", :to_json]]
+    end
+
+    def post_is_create?
+      true
+    end
+
+    def create_path
+      "created_path_here/123"
+    end
+
+    def from_json
+      response.body = %{ {"foo": "bar"} }
+    end
+  end
+
+  let(:app) do
+    Rack::Builder.new do
+      map '/some/route' do
+        run(Webmachine::Application.new do |app|
+          app.add_route(["test"], Test::Resource)
+          app.add_route(["create_test"], CreateResource)
+          app.configure do | config |
+            config.adapter = :RackMapped
+          end
+        end.adapter)
+      end
+    end
+  end
+
+  context "using Rack::Test" do
+    include Rack::Test::Methods
+
+    it "provides the full request URI" do
+      rack_response = get "some/route/test", nil, {"HTTP_ACCEPT" => "test/response.request_uri"}
+      expect(rack_response.body).to eq "http://example.org/some/route/test"
+    end
+
+    it "provides LOCATION header using custom base_uri when creating from POST request" do
+      rack_response = post "/some/route/create_test", %{{"foo": "bar"}}, {"HTTP_ACCEPT" => "application/json", "CONTENT_TYPE" => "application/json"}
+      expect(rack_response.headers["Location"]).to eq("http://example.org/some/route/created_path_here/123")
+    end
+  end
+end

spec/webmachine/dispatcher/route_spec.rb

@@ -7,7 +7,8 @@ def warn(*msgs); end # silence warnings for tests
 describe Webmachine::Dispatcher::Route do
   let(:method) { "GET" }
   let(:uri) { URI.parse("http://localhost:8080/") }
-  let(:request){ Webmachine::Request.new(method, uri, Webmachine::Headers.new, "") }
+  let(:routing_tokens) { nil }
+  let(:request){ Webmachine::Request.new(method, uri, Webmachine::Headers.new, "", routing_tokens) }
   let(:resource){ Class.new(Webmachine::Resource) }
 
   describe '#apply' do
@@ -16,9 +17,7 @@ def warn(*msgs); end # silence warnings for tests
     }
 
     describe 'a path_info fragment' do
-      before do
-        uri.path = '/hello/planet%20earth%20++'
-      end
+      let(:uri) { URI.parse("http://localhost:8080/hello/planet%20earth%20++") }
 
       it 'should decode the value' do
         route.apply(request)
@@ -30,8 +29,10 @@ def warn(*msgs); end # silence warnings for tests
   matcher :match_route do |*expected|
     route = Webmachine::Dispatcher::Route.new(expected[0], Class.new(Webmachine::Resource), expected[1] || {})
     match do |actual|
-      request.uri.path = actual if String === actual
-      route.match?(request)
+      uri = URI.parse("http://localhost:8080")
+      uri.path = actual
+      req = Webmachine::Request.new("GET", uri, Webmachine::Headers.new, "", routing_tokens)
+      route.match?(req)
     end
 
     failure_message do |_|
@@ -124,6 +125,18 @@ def call(request)
         end
       end
     end
+
+    context "with a request with explicitly specified routing tokens" do
+      subject { "/some/route/foo/bar" }
+      let(:routing_tokens) { ["foo", "bar"] }
+      it { is_expected.to match_route(["foo", "bar"]) }
+      it { is_expected.to match_route(["foo", :id]) }
+      it { is_expected.to match_route ['*'] }
+      it { is_expected.to match_route [:*] }
+      it { is_expected.not_to match_route(["some", "route", "foo", "bar"]) }
+      it { is_expected.not_to match_route %w{foo} }
+      it { is_expected.not_to match_route [:id] }
+    end
   end
 
   context "applying bindings" do
@@ -170,7 +183,8 @@ def call(request)
 
     context "on a deep path" do
       subject { described_class.new(%w{foo bar baz}, resource) }
-      before { request.uri.path = "/foo/bar/baz"; subject.apply(request) }
+      let(:uri) { URI.parse("http://localhost:8080/foo/bar/baz") }
+      before { subject.apply(request) }
 
       it "should assign the dispatched path as the path past the initial slash" do
         expect(request.disp_path).to eq("foo/bar/baz")

spec/webmachine/request_spec.rb

@@ -3,11 +3,13 @@
 describe Webmachine::Request do
   subject { request }
 
-  let(:uri)         { URI.parse("http://localhost:8080/some/resource") }
-  let(:http_method) { "GET" }
-  let(:headers)     { Webmachine::Headers.new }
-  let(:body)        { "" }
-  let(:request)     { Webmachine::Request.new(http_method, uri, headers, body) }
+  let(:uri)             { URI.parse("http://localhost:8080/some/resource") }
+  let(:http_method)     { "GET" }
+  let(:headers)         { Webmachine::Headers.new }
+  let(:body)            { "" }
+  let(:routing_tokens)  { nil }
+  let(:base_uri)        { nil }
+  let(:request)         { Webmachine::Request.new(http_method, uri, headers, body, routing_tokens, base_uri) }
 
   it "should provide access to the headers via brackets" do
     subject.headers['Accept'] = "*/*"
@@ -30,8 +32,17 @@
     expect(subject.content_md5).to be_nil
   end
 
-  it "should calculate a base URI" do
-    expect(subject.base_uri).to eq(URI.parse("http://localhost:8080/"))
+  context "base_uri" do
+    it "should calculate a base URI" do
+      expect(subject.base_uri).to eq(URI.parse("http://localhost:8080/"))
+    end
+
+    context "when base_uri has been explicitly set" do
+      let(:base_uri) { URI.parse("http://localhost:8080/some_base_uri/here") }
+      it "should use the provided base_uri" do
+        expect(subject.base_uri).to eq(URI.parse("http://localhost:8080/some_base_uri/here"))
+      end
+    end
   end
 
   it "should provide a hash of query parameters" do
@@ -239,4 +250,24 @@ def body; block_given? ? yield(@body) : @body; end
     end
   end
 
+  describe '#routing_tokens' do
+    subject { request.routing_tokens }
+
+    context "haven't been explicitly set" do
+      let(:routing_tokens) { nil }
+      it "extracts the routing tokens from the path portion of the uri" do
+        expect(subject).to eq(["some", "resource"])
+      end
+    end
+
+    context "have been explicitly set" do
+      let(:routing_tokens) { ["foo", "bar"] }
+
+      it "uses the specified routing_tokens" do
+        expect(subject).to eq(["foo", "bar"])
+      end
+    end
+
+  end
+
 end