restless_router 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c6e52a3b8548ac48bdc13f601d9a83b1d61ecd4d
+  data.tar.gz: feaafcf86072c33421c0b69778e594be7c98cba4
+SHA512:
+  metadata.gz: 6499767d0da1d50c4224d3ac1908ab37750da49fa26c44c33a8085e6e2a24a32944490903e168040f02881163e9a415f6429720442f7ae1bfd12ef254cbbeee3
+  data.tar.gz: 595d490b7212e0d5ce5b774b6c790d2dcb2c278ab34c24faa980b4f9d24b01d4666d299c8897ed4dfd9a4eaa65167ae837fffdfa0f9ef802a725c529c57a837a

data/.gitignore

@@ -0,0 +1,19 @@
+/.ruby-gemset
+/.ruby-version
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in restless_router.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Nate Klaiber
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,100 @@
+# RestlessRouter
+
+This helps fill the gap where web services only provide their routing
+via external documentation. In order to prevent URL building scattered
+throughout your client, you can define the routes up-front via fully
+qualified URIs or [URI Templates](http://tools.ietf.org/html/rfc6570).
+
+You can then reference a URL by looking it up by it's _link
+relationship_.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'restless_router'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install restless_router
+
+## Usage
+
+The first step is to **define the possible routes that a service may
+utilize**. In most cases they can be found in their online documentation
+of the service.
+
+```ruby
+require 'restless_router'
+
+routes = RestlessRouter::Routes.new
+
+# Add a fully qualified URI
+routes.add_route(RestlessRouter::Route.new('directory', 'https://example.com/directory')
+
+# Add a URI Templated
+routes.add_route(RestlessRouter::Route.new('http://example.com/rels/user-detail', 'https://example.com/users/{id}', templated: true)
+```
+
+> You may also use the `<<` operator to add routes to the collection.
+
+Once the routes have been defined, you may **lookup the routes** by their
+[IANA Link
+Relationship](http://www.iana.org/assignments/link-relations/link-relations.xhtml)
+or _Custom Link Relationships_.
+
+```ruby
+
+# Look up the Directory route
+directory_route = routes.route_for('directory')
+directory_url   = directory_route.url_for
+# => 'https://example.com/directory'
+
+# Look up the User Detail route
+user_detail_route = routes.route_for('http://example.com/rels/user-detail')
+user_defail_url   = user_detail_route.url_for(id: '1234')
+# => 'https://example.com/users/1234'
+```
+
+This can then be utilized as you see fit with your `HTTP` adapter.
+
+```ruby
+require 'faraday'
+require 'restless_router'
+
+# Routes are defined in the core application
+class Application
+  def self.routes
+    # Include route definitions here
+  end
+end
+
+# We can then reference the routes
+directory_route = Application.routes.route_for('directory')
+directory_url   = directory_route.url_for
+
+# And make a request
+directory_request = Faraday.get(directory_url)
+```
+
+## Approach
+
+* There is a `Routes` collection that holds the route definitions.
+* There is a `Route` object that holds the details of the route definition.
+* There are mechanisms to _find_ the route, and _expand_ the route if necessary.
+
+Some APIs may provide hypermedia envelopes and you should use those where
+available. 
+
+## Contributing
+
+1. Fork it ( http://github.com/<my-github-username>/restless_router/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/restless_router/route.rb

@@ -0,0 +1,89 @@
+require 'addressable/template'
+
+module RestlessRouter
+  class Route
+    include Comparable
+
+    # Create a new Route that can be used
+    # to issue requests against.
+    #
+    # @example
+    #   # With a fully qualified URI
+    #   route = RestlessRouter::Route.new('home', 'http://example.com')
+    #
+    #   route.name
+    #   # => 'home'
+    #
+    #   route.url_for
+    #   # => 'http://example.com'
+    #
+    #   # With a templated route
+    #   route = RestlessRouter::Route.new('search', 'http://example.com/search{?q}', templated: true)
+    #   
+    #   route.name
+    #   # => 'search'
+    #
+    #   route.url_for(q: 'search-term')
+    #   # => 'http://example.com/search?q=search-term'
+    #
+    def initialize(name, path, options={})
+      @name = name
+      @path = path
+
+      @options = default_options.merge(options)
+    end
+
+    # Define the spaceship operator for use with Comparable
+    #
+    def <=>(other)
+      self.name <=> other.name
+    end
+
+    # Return the name of the Route. This is either
+    # the IANA or custom link relationship.
+    #
+    # @return [String] Name of the route
+    def name
+      @name
+    end
+
+    # Returns the URL for the route. If it's templated,
+    # then we utilize the provided options hash to expand
+    # the route. Otherwise we return the `path`
+    #
+    # @return [String] The templated or base URI
+    def url_for(options={})
+      if templated?
+        template = Addressable::Template.new(base_path)
+        template = template.expand(options)
+        template.to_s
+      else
+        base_path
+      end
+    end
+
+    private
+    # Provide a set of default options. Currently
+    # this is used to set `templated` to false.
+    def default_options
+      {
+        :templated => false
+      }
+    end
+
+    # Query method to see if the URI path provided
+    # is templated
+    #
+    # @return [Boolean] True if the path is templated
+    def templated?
+      @options.fetch(:templated)
+    end
+
+    # The base path provided for the route
+    #
+    # @return [String] The base path
+    def base_path
+      @path
+    end
+  end
+end

data/lib/restless_router/routes.rb

@@ -0,0 +1,103 @@
+require File.expand_path('../route', __FILE__)
+
+module RestlessRouter
+  class Routes
+    include Enumerable
+
+    # Error Definitions
+    InvalidRouteError  = Class.new(StandardError)
+    ExistingRouteError = Class.new(StandardError)
+    RouteNotFoundError = Class.new(StandardError)
+
+    # Creates a new instance of a Route collection. This allows
+    # us to keep all definitions in a single object and then
+    # later retrieve them by their link relationship name.
+    #
+    # @example
+    #   routes = RestlessRouter::Routers.new
+    #   routes.add_route(RestlessRouter::Route.new('home', 'https://example.com/home')
+    #
+    #   routes.route_for('home').url_for
+    #   # => 'https://example.com/home'
+    #
+    def initialize
+      @routes = []
+    end
+
+    # Define each for use with Enumerable
+    #
+    def each(&block)
+      @routes.each(&block)
+    end
+
+    # Add a new route to the Routes collection
+    #
+    # @return [Array] Routes collection
+    def add_route(route)
+      raise InvalidRouteError.new('Route must respond to #url_for') unless valid_route?(route)
+      @routes << route unless route_exists?(route)
+    end
+    alias :<< :add_route
+
+    # Raise an exception if the route is invalid or already exists
+    #
+    def add_route!(route)
+      # Raise exception if the route is existing, too
+      raise InvalidRouteError.new('Route must respond to #url_for') unless valid_route?(route)
+      raise ExistingRouteError.new(("Route already exists for %s" % [route.name])) if route_exists?(route)
+
+      @routes << route
+    end
+
+    # Retrieve a route by it's link relationship name
+    #
+    # @return [Route, nil] Instance of the route by name or nil
+    def route_for(name)
+      name = name.to_s
+      @routes.select { |entry| entry.name == name }.first
+    end
+
+    # Raise an exception of the route's not found
+    #
+    #
+    def route_for!(name)
+      route = route_for(name)
+      raise RouteNotFoundError.new(("Route not found for %s" % [name])) if route.nil?
+      route
+    end
+
+    # Returns the collection of Route definitions
+    #
+    # @return [Array] Routes
+    def routes
+      @routes
+    end
+
+    # Query method to check if any routes have been defined.
+    #
+    # @return [Boolean] True if there are definitions in the collection
+    def routes?
+      @routes.any?
+    end
+
+    private
+    # Query method to see if the specified route already exists.
+    #
+    # @return [Boolean] True if we already have an existing route
+    def route_exists?(route)
+      !!self.route_for(route.name)
+    end
+
+    # Query method to see if the route definition being added is valid.
+    #
+    # It must respond to:
+    #
+    # * `name`
+    # * `url_for`
+    #
+    # @return [Boolean] True if the route definition is valid
+    def valid_route?(route)
+      route.respond_to?(:url_for) && route.respond_to?(:name)
+    end
+  end
+end

data/lib/restless_router/version.rb

@@ -0,0 +1,3 @@
+module RestlessRouter
+  VERSION = "0.0.1"
+end

data/lib/restless_router.rb

@@ -0,0 +1,5 @@
+require "restless_router/version"
+require "restless_router/routes"
+
+module RestlessRouter
+end

data/restless_router.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'restless_router/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "restless_router"
+  spec.version       = RestlessRouter::VERSION
+  spec.authors       = ["Nate Klaiber"]
+  spec.email         = ["nate@theklaibers.com"]
+  spec.summary       = %q{Enable simple route definitions for external resources.}
+  spec.description   = %q{Many web services lack hypermedia or consistent routing. This gives a single place to house routes using URI Templates instead of building URLs throughout the client.}
+  spec.homepage      = "https://github.com/nateklaiber/restless_router"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency("bundler", "~> 1.5")
+  spec.add_development_dependency("rake")
+  spec.add_development_dependency("rspec")
+  spec.add_development_dependency("yard")
+
+  spec.add_dependency("addressable")
+end

data/spec/unit/route_spec.rb

@@ -0,0 +1,35 @@
+require File.expand_path('../../../lib/restless_router/route', __FILE__)
+
+describe RestlessRouter::Route do
+  let(:name) { 'home' }
+  let(:path) { 'http://www.example.com' }
+  let(:options) { {} }
+
+  subject { described_class.new(name, path, options) }
+
+  # TODO: Validations on empty `name` or `path`
+
+  context "with URI" do
+    it "returns the #name" do
+      expect(subject.name).to eq('home')
+    end
+
+    it "returns the #url_for" do
+      expect(subject.url_for).to eq('http://www.example.com')
+    end
+  end
+
+  context "with URI Template" do
+    let(:name) { 'search' }
+    let(:path) { 'http://www.example.com/search{?q}' }
+    let(:options) { { templated: true } }
+
+    it "returns the expanded #url_for" do
+      expect(subject.url_for(q: 'search-term')).to eq('http://www.example.com/search?q=search-term')
+    end
+    
+    it "returns the expanded #url_for with no expansions" do
+      expect(subject.url_for).to eq('http://www.example.com/search')
+    end
+  end
+end

data/spec/unit/routes_spec.rb

@@ -0,0 +1,116 @@
+require 'ostruct'
+require File.expand_path('../../../lib/restless_router/routes', __FILE__)
+
+describe RestlessRouter::Routes do
+  let(:home_route) { RestlessRouter::Route.new('home', 'https://example.com/home') }
+  let(:search_route) { RestlessRouter::Route.new('search', 'https://example.com/search{?q}', templated: true) }
+  let(:route_definitions) { [home_route, search_route] }
+
+  subject { described_class.new }
+
+  before(:each) do
+    route_definitions.each { |route| subject.add_route(route) }
+  end
+
+  context "without routes" do
+    let(:route_definitions) { [] }
+
+    it "returns false for #any?" do
+      expect(subject.any?).to be_false
+    end
+
+    it "returns 0 for the count" do
+      expect(subject.count).to eq(0)
+    end
+
+    context "retrieving a route definition" do
+      describe "#route_for" do
+        it "returns nil when searching for 'home'" do
+          expect(subject.route_for('home')).to be_nil
+        end
+      end
+
+      describe "#route_for!" do
+        it "raises an exception with searching for 'home'" do
+          lambda { subject.route_for!('home') }.should raise_error(RestlessRouter::Routes::RouteNotFoundError)
+        end
+      end
+    end
+  end
+
+  context "with routes" do
+    it "returns true for #any?" do
+      expect(subject.any?).to be_true
+    end
+
+    it "returns 2 for the count" do
+      expect(subject.count).to eq(2)
+    end
+
+
+    context "retrieving a route definition" do
+      describe "#route_for" do
+        it "returns the route specified for 'home'" do
+          expect(subject.route_for('home')).to eq(home_route)
+        end
+
+        it "returns the route specified for 'search'" do
+          expect(subject.route_for('search')).to eq(search_route)
+        end
+
+        it "returns nil when route specified for 'not-defined'" do
+          expect(subject.route_for('not-defined')).to be_nil
+        end
+      end
+
+      describe "#route_for!" do
+        it "raises an exception with searching for 'not-defined'" do
+          lambda { subject.route_for!('not-defined') }.should raise_error(RestlessRouter::Routes::RouteNotFoundError)
+        end
+      end
+    end
+  end
+
+  context "ensure uniqueness by link relationship name" do
+    let(:route_definitions) { [] }
+
+    describe "#add_route" do
+      it "does not add a route with the same name" do
+        subject.add_route(home_route)
+        subject.add_route(home_route)
+        expect(subject.count).to eq(1)
+      end
+    end
+
+    describe "#add_route!" do
+      it "raises an exception if route is specified with the same name" do
+        subject.add_route!(home_route)
+
+        lambda { subject.add_route!(home_route) }.should raise_error(RestlessRouter::Routes::ExistingRouteError)
+      end
+    end
+  end
+
+  context "adding a new route definition" do
+    it "raises an exception if nil is added" do
+      lambda { subject.add_route(nil) }.should raise_error(RestlessRouter::Routes::InvalidRouteError)
+    end
+
+    it "raises an error if route definition does not respond to #name" do
+      route_definition = OpenStruct.new(url_for: 'http://example.com')
+      lambda { subject.add_route(route_definition) }.should raise_error(RestlessRouter::Routes::InvalidRouteError)
+    end
+
+    it "raises an error if route definition does not respond to #url_for" do
+      route_definition = OpenStruct.new(name: 'home')
+      lambda { subject.add_route(route_definition) }.should raise_error(RestlessRouter::Routes::InvalidRouteError)
+    end
+
+    it "pushes the valid route onto the stack" do
+      route_definition = OpenStruct.new(name: 'custom-name', url_for: 'http://example.com')
+      subject.add_route(route_definition)
+
+      expect(subject).to include(route_definition)
+    end
+  end
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: restless_router
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Nate Klaiber
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-05-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  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'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  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'
+- !ruby/object:Gem::Dependency
+  name: yard
+  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'
+- !ruby/object:Gem::Dependency
+  name: addressable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Many web services lack hypermedia or consistent routing. This gives a
+  single place to house routes using URI Templates instead of building URLs throughout
+  the client.
+email:
+- nate@theklaibers.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/restless_router.rb
+- lib/restless_router/route.rb
+- lib/restless_router/routes.rb
+- lib/restless_router/version.rb
+- restless_router.gemspec
+- spec/unit/route_spec.rb
+- spec/unit/routes_spec.rb
+homepage: https://github.com/nateklaiber/restless_router
+licenses:
+- MIT
+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.2.0
+signing_key: 
+specification_version: 4
+summary: Enable simple route definitions for external resources.
+test_files:
+- spec/unit/route_spec.rb
+- spec/unit/routes_spec.rb
+has_rdoc: