combinaut_director 1.2.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 558b04f0ba15457cf86c1b03adfd5a33250f0b8683870b53414936d900a07539
+  data.tar.gz: 505c7e703bc500c2abe5ef51f88c38131a3fac34d4972084036b3fc0910a8fcb
+SHA512:
+  metadata.gz: ccb12a09877d0f43f8ef8644efa8e30dca67344f41624905b4f6f3812ac65a8aa8490ee0f823881743a540e7b3f3e85c1b688d6bb4296fdade4313231b8afd56
+  data.tar.gz: c4b9a652ce4a4bdba5963361f427e7550171244bfd57566f6815831aa7827d7bf9a6f7b8b231d039f444105c1ff3c8bdf7a7b40f39d7275c6c8d75ddf0170cbd

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 YOURNAME
+
+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,139 @@
+# Director
+
+Director is a Rack Middleware gem that directs incoming requests to their aliased target paths based on a customizable
+alias list stored in the database. It has two basic handlers, but can be extended with your own.
+
+## Usage
+
+### Proxy
+If you want to create a vanity path, where the contents of one page appears at a new path, use a `proxy` handler. The user agent will show the vanity path in the url bar, but the contents of the target path will appear on the page.
+```ruby
+Director::Alias.create(source_path: '/vanity/path', target_path: 'real/path', handler: :proxy)
+```
+
+### Redirect
+If you want to redirect a deprecated or non-canonical path to the canonical path, use a `redirect` handler. The user agent will show the target path in the url bar and the contents of the target path will appear on the page.
+```ruby
+Director::Alias.create(source_path: '/deprecated/path', target_path: 'new/path', handler: :redirect)
+```
+
+### Custom Alias Handlers
+You can create handlers for your own custom aliases. Handlers must be namespaced under `Director::Handler` and need only
+implement a single `response` method. For those who have played with Rack, you will find the `response` method is very
+similar to Rack's `MiddleWare#call` method in that it must return a Rack-compatible response. See https://rack.github.io/
+for more information on valid return values, and the `lib/direct/handlers` folder basic for handler examples.
+
+```ruby
+class Director::Handler::MyCustomHandler < Base
+  def response(app, env)
+    # do some amazing stuff, then...
+    # return a valid Rack response
+  end
+end
+```
+
+### Source/Target Record
+An alias can also be linked to a record at both the source and target end of the alias. Linked records allow for automatic updating of the corresponding path. When the record is saved, it runs a method that updates all incoming and outgoing aliases.
+
+```ruby
+class MyModel < ActiveRecord::Base
+  has_aliased_paths canonical_path: :path # Accepts a symbol, proc, or object that responds to `#canonical_path`
+
+  private
+
+  def path
+    # Return the path that routes to this record
+  end
+end
+```
+
+### Url params
+Url "params" or "query" from the request will be passed on and merged with target path. Any url params in the target path
+will be preserved.
+
+### Chaining
+Alias lookups will chain if an alias `target_path` points to `source_path` of another. A `Director::AliasChainLoop`
+exception is raised if a cycle is detected in the alias chain in order to avoid infinite lookups.
+A chain ends when there is no alias with a `source_path` matching the `target_path` of the last
+alias found, or if the last alias found is has a `redirect` handler. A redirect alias ends the chain in order to force the browser to update its url, thus continuing the alias chain lookup in a second request.
+
+## Constraints
+There are several constraints that can be applied to limit which requests are handled. Each constraint consists of a
+whitelist and a blacklist that can be independently configured.
+
+### Format
+The format constraint looks at the request extension. This can be used to ignore asset requests or only apply aliasing
+to HTML requests.
+```ruby
+Director::Configuration.constraints.format.only = [:html, :xml]
+# or
+Director::Configuration.constraints.format.except = :jpg
+```
+
+### Source Path
+The source constraint limits what can be entered as a source path in an `Alias`. This can be useful if you want to
+prevent aliasing of certain routes, like an admin namespace for example. `only` and `except` are passed to `validates_format_of`
+validations on the Alias model, and accept any patterns the `:with` and `:without` options of that validator.
+```ruby
+Director::Configuration.constraints.source_path.only = %r{\A/pages/}
+# or
+Director::Configuration.constraints.source_path.except = %r{\A/admin/}
+```
+NOTE: This constraint will also limit what requests perform an alias lookup. If a constraint is added, it will effectively
+disable existing aliases that do not match the new constraint.
+
+### Target Path
+The target constraint limits what can be entered as a target path in an `Alias`. This can be useful if you want to
+prevent aliasing of certain routes, like an admin namespace for example. `only` and `except` are passed to `validates_format_of`
+validations on the Alias model, and accept any patterns the `:with` and `:without` options of that validator.
+```ruby
+Director::Configuration.constraints.target_path.only = %r{\A/pages/}
+# or
+Director::Configuration.constraints.target_path.except = %r{\A/admin/}
+```
+
+### Request
+The request constraint yields the request itself to a given proc. This can be used to ignore asset requests or only
+apply aliasing based on any aspect of the request, for example, params, host name, etc.<sup id="footnote_ref_1">[1](#footnote_1)</sup>
+
+```ruby
+Director::Configuration.constraints.request.only = ->(request) { request.params['my_param'] == 'false' }
+# or
+Director::Configuration.constraints.request.except = ->(request) { request.env['HTTP_HOST'] == 'testing.test' }
+```
+
+### Lookup Scope
+The lookup scope constraint is applied using the `ActiveRecord::Base.merge` method to inject the scope into alias the
+lookup query. The constraint should be a callable object, and is passed a `Rack::Request` object for the current request.
+This can be used to scope alias lookups based on the request subdomain, or other request criteria.
+
+
+```ruby
+# Assuming you have added a `domain` column to the aliases table...
+Director::Configuration.constraints.lookup_scope = lambda do |request|
+  Director::Alias.where(domain: Domain.id_from_host(request.host))
+end
+
+# or returning a callable object for merging
+Director::Configuration.constraints.lookup_scope = proc do
+  -> { where(client: Client.current) }
+end
+```
+
+## Request Information
+Sometimes it may be useful to know what the request url was before Director modified it, or know if Director handled the
+request or ignored it due to constraints.
+
+```ruby
+Director::Middleware.original_request_url(request) # => Original request url before Director handled it
+Director::Middleware.handled_request?(request) # => Boolean indicating whether or not Director handled the request
+```
+
+## Upgrading from an older version
+
+### 1.1.x to 1.2.0
+
+Alias resolution is now case insensitive. All incoming paths are downcased before saving or resolving. If you have existing aliases, you should call `#save` on each one to trigger the path sanitizer which will downcase the saved paths so the the downcased paths coming in to the `#resolve` method.
+
+## Footnotes
+<span id="footnote_1">1.</span> By default, Director only handles GET and HEAD requests because the `redirect` handler cannot tell the browser to redirect a POST. The `proxy` handler could internally redirect a POST to an aliased target path, but this dichotomy adds too much complexity for it to be enabled out of the box. The constraints configuration gives you full control over which requests are handled by Director in your application. [↩](#footnote_ref_1)

data/app/models/director/alias.rb

@@ -0,0 +1,137 @@
+module Director
+  class Alias < ActiveRecord::Base
+    belongs_to :source, polymorphic: true
+    belongs_to :target, polymorphic: true
+
+    before_validation :sanitize_path
+    validates_presence_of :source_path, unless: :source
+    validates_presence_of :target_path, unless: :target
+    validates_format_of :source_path, with: Configuration.constraints.source_path.only
+    validates_format_of :target_path, with: Configuration.constraints.target_path.only
+    validates_format_of :source_path, without: Configuration.constraints.source_path.except
+    validates_format_of :target_path, without: Configuration.constraints.target_path.except
+    validates_format_of :source_path, with: %r{\A/}, if: :source_path_relative?, message: 'is a relative path so it must start with a slash'
+    validates_format_of :target_path, with: %r{\A/}, if: :target_path_relative?, message: 'is a relative path so it must start with a slash'
+    validate :valid_paths
+    validate :valid_handler
+
+    scope :with_source_path, -> { where.not(source_path: nil) }
+    scope :with_target_path, -> { where.not(target_path: nil) }
+
+    before_save :set_source_path, if: :source_changed?
+    before_save :set_target_path, if: :target_changed?
+
+    def self.resolve_with_constraint(source_path, request)
+      merge(Configuration.constraints.lookup_scope.call(request)).resolve(source_path)
+    end
+
+    # Returns the alias matching the source_path, traversing any chained aliases and returning the last one
+    def self.resolve(source_path)
+      source_path = sanitize_path(source_path)
+      found = {}
+
+      # Traverse a chain of aliases
+      while alias_entry = find_by_source_path(source_path) do
+        raise AliasChainLoop, [*found.keys, source_path].join(' -> ') if found.key?(alias_entry.target_path)
+        break if alias_entry.passthrough? # Stop if we reach a passthrough since the app will handle this
+        found[source_path] = alias_entry
+        break if alias_entry.redirect? # Stop if we reach a redirect since the browser will need to change url at that point
+        source_path = alias_entry.target_path
+      end
+
+      return found.values.last
+    end
+
+    def self.valid_uri?(url)
+      !!URI(url)
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def self.relative?(url)
+      URI(url).relative?
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def self.sanitize_path(path = nil, &block)
+      path = block.call if block_given?
+      path = path.to_s
+      path = path.strip
+      path = path.downcase
+      path = path.remove(%r{/$}) if path.length > 1
+      return path
+    end
+
+    def redirect?
+      handler_class <= Handler::Redirect
+    end
+
+    def passthrough?
+      handler_class <= Handler::Passthrough
+    end
+
+    def handler_class
+      handler_name = "Director::Handler::#{handler.classify}"
+      handler_name.constantize
+    rescue NameError
+      raise MissingAliasHandler, "Handler not found '#{handler_name}'"
+    end
+
+    def blank?
+      !(source_path? || target_path? || source || target)
+    end
+
+    private
+
+    def valid_paths
+      source_path = source_changed? && source ? source.generate_canonical_path : self.source_path
+      target_path = target_changed? && target ? target.generate_canonical_path : self.target_path
+
+      errors.add(:source_path, 'is not a valid') unless self.class.valid_uri?(source_path)
+      errors.add(:target_path, 'is not a valid') unless self.class.valid_uri?(target_path)
+      errors.add(:target_path, 'cannot be the same as the source path') if source_path == target_path
+    end
+
+    def sanitize_path
+      self.source_path = self.class.sanitize_path(source_path)
+      self.target_path = self.class.sanitize_path(target_path)
+    end
+
+    def set_source_path
+      self.source_path = source.generate_canonical_path if source
+    end
+
+    def set_target_path
+      self.target_path = target.generate_canonical_path if target
+    end
+
+    def source_changed?
+      source_path_changed? || source_id_changed? || source_type_changed?
+    end
+
+    def target_changed?
+      target_path_changed? || target_id_changed? || target_type_changed?
+    end
+
+    def source_path_relative?
+      self.class.relative?(source_path) if source_path?
+    end
+
+    def target_path_relative?
+      self.class.relative?(target_path) if target_path?
+    end
+
+    def valid_handler
+      handler_class
+    rescue MissingAliasHandler
+      errors.add(:handler, 'not defined')
+    end
+  end
+
+  # EXCEPTIONS
+
+  class DirectorException < StandardError; end
+  class MissingAliasHandler < DirectorException; end
+  class AliasChainLoop < DirectorException; end
+end

data/lib/combinaut_director.rb

@@ -0,0 +1 @@
+require "director"

data/lib/director.rb

@@ -0,0 +1,6 @@
+require 'rails'
+require 'director/helpers'
+require 'director/handler'
+require 'director/configuration'
+require 'director/railtie'
+require 'director/engine'

data/lib/director/configuration.rb

@@ -0,0 +1,18 @@
+require 'ostruct'
+
+module Director
+  module Configuration
+    mattr_reader :constraints
+
+    Constraint = Struct.new(:only, :except)
+
+    # Defaults
+    @@constraints = OpenStruct.new({
+      source_path: Constraint.new,
+      target_path: Constraint.new,
+      request: Constraint.new(->(request) { request.get? || request.head? }),
+      format: Constraint.new,
+      lookup_scope: ->(request) { {} }
+    })
+  end
+end

data/lib/director/engine.rb

@@ -0,0 +1,15 @@
+require 'director/handler/base'
+require 'director/handler/passthrough'
+require 'director/handler/proxy'
+require 'director/handler/redirect'
+require 'director/model_extensions'
+
+module Director
+  class Engine < Rails::Engine
+    initializer 'director.load_model_extensions' do |app|
+      ActiveSupport.on_load(:active_record) do
+        ActiveRecord::Base.extend Director::ModelExtensions::ActMethod
+      end
+    end
+  end
+end

data/lib/director/handler.rb

@@ -0,0 +1,8 @@
+module Director
+  module Handler
+    def self.for(alias_entry)
+      return Passthrough unless alias_entry
+      alias_entry.handler_class
+    end
+  end
+end

data/lib/director/handler/base.rb

@@ -0,0 +1,34 @@
+# TEST: individual handlers work when a target_path is present
+# TEST: individual handlers work when only a target is present
+# TEST: individual handlers can redirect to "" without looping indefinitely
+require 'uri'
+
+module Director
+  module Handler
+    class Base
+      attr_reader :alias_entry
+
+      def initialize(alias_entry)
+        @alias_entry = alias_entry
+      end
+
+      def response(app, env)
+        raise NotImplementedError
+      end
+
+      private
+
+      def request_uri(env)
+        URI(Rack::Request.new(env).url).freeze
+      end
+
+      def target_uri
+        URI(alias_entry.target_path).freeze
+      end
+
+      def merge_query(query1, query2)
+        [query1, query2].select(&:present?).join('&').presence
+      end
+    end
+  end
+end

data/lib/director/handler/passthrough.rb

@@ -0,0 +1,9 @@
+module Director
+  module Handler
+    class Passthrough < Base
+      def response(app, env)
+        app.call(env)
+      end
+    end
+  end
+end

data/lib/director/handler/proxy.rb

@@ -0,0 +1,12 @@
+module Director
+  module Handler
+    class Proxy < Base
+      def response(app, env)
+        env['QUERY_STRING'] = merge_query(target_uri.query, request_uri(env).query)
+        env['PATH_INFO'] = target_uri.path
+
+        app.call(env)
+      end
+    end
+  end
+end

data/lib/director/handler/redirect.rb

@@ -0,0 +1,14 @@
+module Director
+  module Handler
+    class Redirect < Base
+      def response(app, env)
+        res = Rack::Response.new
+        redirect_uri = target_uri.dup
+        redirect_uri.query = merge_query(target_uri.query, request_uri(env).query)
+
+        res.redirect(redirect_uri.to_s || '/')
+        res.finish
+      end
+    end
+  end
+end

data/lib/director/helpers.rb

@@ -0,0 +1,39 @@
+module Director
+  module Helpers
+    extend self
+
+    def matches_constraint?(constraint, value, coerce: :itself)
+      value = value.send(coerce)
+      only = Array(constraint.only).map(&coerce)
+      except = Array(constraint.except).map(&coerce)
+
+      return false if only.present? && only.none? {|matcher| matches?(matcher, value) }
+      return false if except.present? && except.any? {|matcher| matches?(matcher, value) }
+      return true
+    end
+
+    def matches?(matcher, value)
+      case matcher
+      when Regexp
+        matches_regexp?(matcher, value)
+      when Proc
+        matches_proc?(matcher, value)
+      else
+        matcher == value
+      end
+    end
+
+    def matches_regexp?(matcher, value)
+      case value
+      when matcher
+        true
+      else
+        false
+      end
+    end
+
+    def matches_proc?(matcher, value)
+      matcher.call(value)
+    end
+  end
+end

data/lib/director/middleware.rb

@@ -0,0 +1,56 @@
+module Director
+  class Middleware
+    def self.handled_request?(request)
+      request.env['director.original_url'].present?
+    end
+
+    def self.original_request_url(request)
+      request.env['director.original_url'] || request.url
+    end
+
+    def initialize(app)
+      @app = app
+    end
+
+    def call(env)
+      @request = Rack::Request.new(env)
+
+      unless ignored?
+        env['director.original_url'] = @request.url
+        alias_entry = Director::Alias.resolve_with_constraint(request_path, @request)
+      end
+
+      return handle_alias(alias_entry, env)
+    end
+
+    private
+
+    def handle_alias(alias_entry, env)
+      return Handler.for(alias_entry).new(alias_entry).response(@app, env)
+    end
+
+    def ignored?
+      ignored_format?(format) || ignored_path?(request_path) || ignored_request?(@request)
+    end
+
+    def ignored_format?(format)
+      !Helpers.matches_constraint?(Configuration.constraints.format, format, coerce: :to_s)
+    end
+
+    def ignored_path?(path)
+      !Helpers.matches_constraint?(Configuration.constraints.source_path, path)
+    end
+
+    def ignored_request?(request)
+      !Helpers.matches_constraint?(Configuration.constraints.request, request)
+    end
+
+    def format
+      request_path[/\.([^.]+)$/, 1] || 'html'
+    end
+
+    def request_path
+      @request.path_info
+    end
+  end
+end

data/lib/director/model_extensions.rb

@@ -0,0 +1,71 @@
+module Director
+  module ModelExtensions
+    module ActMethod
+      def has_aliased_paths(canonical_path: )
+        extend ClassMethods
+        include Associations
+        include Callbacks
+        include InstanceMethods
+
+        self.aliased_paths_options = { canonical_path: canonical_path }
+      end
+    end
+
+    module ClassMethods
+    end
+
+    module InstanceMethods
+    end
+
+    module Associations
+      BLANK_ALIAS = ->(attributes) { Director::Alias.new(attributes).blank? }
+
+      def self.included(base)
+        base.has_many :incoming_aliases, class_name: 'Director::Alias', as: :target, dependent: :delete_all, inverse_of: :target
+        base.has_one :outgoing_alias, class_name: 'Director::Alias', as: :source, dependent: :delete, inverse_of: :source
+
+        base.class_attribute :aliased_paths_options
+        base.accepts_nested_attributes_for :incoming_aliases, reject_if: BLANK_ALIAS, allow_destroy: true
+        base.accepts_nested_attributes_for :outgoing_alias, reject_if: BLANK_ALIAS, allow_destroy: true
+      end
+    end
+
+    module Callbacks
+      def self.included(base)
+        base.after_save :update_aliased_paths
+      end
+
+      def generate_canonical_path
+        generator = aliased_paths_options[:canonical_path]
+        Alias.sanitize_path do
+          case generator
+          when Symbol
+            send(generator)
+          when Proc
+            generator.call(self)
+          when String
+            generator
+          else # Assume it's an object that responds to canonical_path
+            generator.send(:canonical_path)
+          end
+        end
+      end
+
+      private
+
+      def update_aliased_paths
+        path = generate_canonical_path
+        update_incoming_alias_paths(path)
+        update_outgoing_alias_paths(path)
+      end
+
+      def update_incoming_alias_paths(path)
+        Alias.where(target: self).update_all(target_path: path)
+      end
+
+      def update_outgoing_alias_paths(path)
+        Alias.where(source: self).update_all(source_path: path)
+      end
+    end
+  end
+end

data/lib/director/railtie.rb

@@ -0,0 +1,9 @@
+require 'director/middleware'
+
+module Director
+  class Railtie < Rails::Railtie
+    initializer "director.init" do |app|
+      app.config.middleware.use Director::Middleware
+    end
+  end
+end

data/lib/director/version.rb

@@ -0,0 +1,3 @@
+module Director
+  VERSION = "1.2.2"
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: combinaut_director
+version: !ruby/object:Gem::Version
+  version: 1.2.2
+platform: ruby
+authors:
+- Ryan Wallace
+- Nicholas Jakobsen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-10-26 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.2'
+- !ruby/object:Gem::Dependency
+  name: combustion
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.7.0
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.6'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  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: Rack Middleware that handles directs incoming requests to their aliased
+  path targets
+email:
+- hello@combinaut.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- app/models/director/alias.rb
+- lib/combinaut_director.rb
+- lib/director.rb
+- lib/director/configuration.rb
+- lib/director/engine.rb
+- lib/director/handler.rb
+- lib/director/handler/base.rb
+- lib/director/handler/passthrough.rb
+- lib/director/handler/proxy.rb
+- lib/director/handler/redirect.rb
+- lib/director/helpers.rb
+- lib/director/middleware.rb
+- lib/director/model_extensions.rb
+- lib/director/railtie.rb
+- lib/director/version.rb
+homepage: http://github.com/combinaut/director
+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.7.9
+signing_key: 
+specification_version: 4
+summary: Rack Middleware that handles directs incoming requests to their aliased path
+  targets
+test_files: []