wayfarer 0.4.7 → 0.4.9

data/lib/wayfarer/routing/matchers/url.rb

@@ -3,13 +3,21 @@
 module Wayfarer
   module Routing
     module Matchers
-      URL = Struct.new(:url) do
-        def match(url)
-          url == Addressable::URI.parse(self.url)
+      class URL
+        include EmptyParams
+
+        attr_reader :url
+
+        def initialize(url)
+          @url = Addressable::URI.parse(url)
+        end
+
+        def evaluate(path_finder)
+          path_finder.uri == url
         end
 
-        def params(_)
-          {}
+        def to_h
+          { url: url.to_s }
         end
       end
     end

data/lib/wayfarer/routing/path_consumer.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+module Wayfarer
+  module Routing
+    # Tracks path consumption during route matching.
+    #
+    # @api private
+    class PathConsumer
+      # The result of consuming part of a path.
+      #
+      # @!attribute offset
+      #   @return [Integer, nil] index into the path string
+      # @!attribute params
+      #   @return [Hash] collected path parameters
+      # @!attribute valid?
+      #   @return [Boolean] whether the current state is valid
+      ConsumptionState = Struct.new(:offset, :params, :valid?, keyword_init: true)
+
+      INITIAL_OFFSET = nil
+
+      # Initial valid state, before any path is consumed.
+      INITIAL_STATE = ConsumptionState.new(
+        offset: INITIAL_OFFSET,
+        params: Wayfarer::Routing::Route::EMPTY_PARAMS,
+        valid?: true
+      ).freeze
+
+      # @return [String] full path being consumed
+      attr_reader :path
+
+      def initialize(path)
+        @path = File.join(File::SEPARATOR, path)
+        @states = [INITIAL_STATE]
+      end
+
+      # Whether the path was fully consumed or not consumed at all.
+      #
+      # @return [Boolean]
+      def valid?
+        current_state.valid? && consumed?
+      end
+
+      # The most recent consumption state.
+      #
+      # @return [ConsumptionState]
+      def current_state
+        states.last
+      end
+
+      # Attempts to consume the path if the route has a {Matchers::Path}
+      # and pushes a new state as a result.
+      #
+      # @param route [Wayfarer::Routing::Route]
+      def push(route)
+        states.push(next_state(route))
+      end
+
+      # Reverts to the previous state.
+      #
+      # @return [ConsumptionState] the popped state
+      def pop
+        states.pop
+      end
+
+    private
+
+      attr_reader :states
+
+      def current_offset
+        current_state.offset || 0
+      end
+
+      def consumed?
+        nothing_consumed? || fully_consumed?
+      end
+
+      def nothing_consumed?
+        current_state.offset == INITIAL_OFFSET
+      end
+
+      def fully_consumed?
+        current_offset >= path.length || trailing_slash?
+      end
+
+      def trailing_slash?
+        current_offset + 1 == path.length && path[-1] == File::SEPARATOR
+      end
+
+      def sub_path
+        return File::SEPARATOR if (offset = current_offset) >= path.length
+
+        File.join(File::SEPARATOR, path[offset..])
+      end
+
+      def next_state(route)
+        return unchanged_state unless route.matcher.is_a?(Wayfarer::Routing::Matchers::Path)
+
+        consumed_state(route.matcher.pattern)
+      end
+
+      def consumed_state(pattern)
+        return unchanged_state unless current_state.valid?
+
+        match_data = pattern.peek_match(sub_path) or return invalid_state
+        matched_path = match_data.to_s
+
+        new_offset = current_offset + matched_path.length
+        new_params = current_state.params.merge(match_data.named_captures)
+
+        ConsumptionState.new(
+          offset: new_offset,
+          params: new_params,
+          valid?: true
+        )
+      end
+
+      def unchanged_state
+        current_state.dup
+      end
+
+      def invalid_state
+        ConsumptionState.new(
+          offset: current_offset,
+          params: current_state.params,
+          valid?: false
+        )
+      end
+    end
+  end
+end

data/lib/wayfarer/routing/path_finder.rb

@@ -2,44 +2,172 @@
 
 module Wayfarer
   module Routing
+    # Encapsulates all state needed to route a URL.
+    #
+    # @api private
     class PathFinder
-      def self.result(route, url)
-        finder = new(url)
+      include KV
+
+      # The result of traversing the route with a new {PathFinder} for `url`.
+      #
+      # @param route [Wayfarer::Routing::Route]
+      # @param task [Wayfarer::Task]
+      # @param callback [Proc]
+      # @return [Result::Match, Result::Mismatch]
+      def self.result(route, task, &)
+        accept_finder(route, new(task, &))
+      end
+
+      # The result of traversing the route with an existing {PathFinder}.
+      #
+      # @param route [Wayfarer::Routing::Route]
+      # @param path_finder [PathFinder]
+      # @return [Result::Match, Result::Mismatch]
+      def self.sub_result(route, path_finder)
+        accept_finder(route, path_finder)
+      end
+
+      # @param route [Wayfarer::Routing::Route]
+      # @param finder [PathFinder]
+      # @return [Result::Match, Result::Mismatch]
+      private_class_method def self.accept_finder(route, finder)
         route.accept(finder)
-        return Result::Mismatch.new if finder.path.none?
+        return Result::Mismatch.instance unless finder.found?
 
         Result::Match.new(finder.action, finder.params)
       end
 
-      attr_reader :url,
-                  :path,
-                  :action,
-                  :params
+      # @return [Wayfarer::Task]
+      attr_reader :task
+
+      # @return [Addressable::URI]
+      attr_reader :uri
+
+      # @return [String]
+      attr_reader :path
+
+      # @return [Wayfarer::Routing::PathConsumer]
+      attr_reader :path_consumer
+
+      # @return [Array<Wayfarer::Routing::Route>]
+      attr_reader :current_path, :found_path
+
+      # @return [Object, nil]
+      attr_reader :action
+
+      # @return [Hash]
+      attr_reader :params
+
+      # @return [Wayfarer::Routing::HashStack]
+      attr_reader :params_stack
+
+      # @param task [Wayfarer::Task]
+      # @param path_consumer [PathConsumer] internal use only
+      # @param params_stack [HashStack] internal use only
+      # @param stop_when_found [Boolean] whether traversal halts on match
+      def initialize(
+        task,
+        path_consumer: initial_path_consumer(task[:uri]),
+        params_stack: Wayfarer::Routing::HashStack.empty,
+        stop_when_found: true,
+        &callback
+      )
+        @task = task
+        @uri = task[:uri]
+        @current_path = []
+        @actions = []
+        @path_consumer = path_consumer
+        @params_stack = params_stack
+        @kv = kv
+        @callback = callback
+        @stop_when_found = stop_when_found
+        @match_history = []
+      end
+
+      # Whether a route has matched and consumed the URL.
+      #
+      # @return [Boolean]
+      def found?
+        !!found_path
+      end
+
+      # @return [Wayfarer::Routing::Route, nil]
+      def current_route
+        current_path.last
+      end
+
+      # Enters a route node, updating state.
+      #
+      # @param route [Wayfarer::Routing::Route]
+      # @return [void]
+      def enter(route)
+        return if stopped?
+
+        current_path.push(route)
+        path_consumer.push(route)
+        params_stack.push(route.params(self))
+        actions.prepend(route.action(self))
+        match_history.push(match(route))
+      end
+
+      # Leaves the current route, restoring previous state.
+      #
+      # @return [void]
+      def leave
+        return if found? && stop_when_found?
 
-      def initialize(url)
-        @url = url
-        @path = []
-        @action = nil
-        @params = {}
+        actions.pop
+        params_stack.pop
+        path_consumer.pop
+        current_path.pop
+        match_history.pop
       end
 
+      # Visits a {Route}.
+      #
+      # @param route [Wayfarer::Routing::Route]
+      # @return [Boolean] whether to continue traversal
       def visit(route)
-        return false if path.any?
-        return false unless route.match(url)
+        return false if stopped? || !match_history.last
+        return true unless route.leaf? && path_consumer.valid?
 
-        follow(route) if route.children.none?
-        true
+        found! if !found? && match_history.all?
+
+        !stop_when_found?
+      end
+
+      # Whether traversal should stop.
+      #
+      # @return [Boolean]
+      def stopped?
+        found? && stop_when_found?
       end
 
     private
 
-      # Follows the route back to the root. Collects parameters and action on
-      # the way.
-      def follow(route)
-        path.unshift(route)
-        @params.merge!(route.matcher.params(url))
-        @action = route.action unless action
-        follow(route.parent) if route.parent
+      attr_reader :actions, :callback, :match_history
+      attr_writer :found_path, :action, :params
+
+      def found!
+        self.params = params_stack.to_h
+        self.action = actions.find(&:present?)
+        self.found_path = current_path.clone.freeze
+      end
+
+      def stop_when_found?
+        !!@stop_when_found
+      end
+
+      def match(route)
+        route.match(self).tap { |result| callback&.call(route, result, self) }
+      end
+
+      def initial_path_consumer(uri)
+        Wayfarer::Routing::PathConsumer.new(url_path(uri))
+      end
+
+      def url_path(uri)
+        uri.host ? uri.path : ""
       end
     end
   end

data/lib/wayfarer/routing/result.rb

@@ -4,7 +4,7 @@ module Wayfarer
   module Routing
     module Result
       Match = Struct.new(:action, :params)
-      Mismatch = Class.new
+      Mismatch = Class.new.include(Singleton)
     end
   end
 end

data/lib/wayfarer/routing/root_route.rb

@@ -2,9 +2,21 @@
 
 module Wayfarer
   module Routing
+    # Routing tree root.
     class RootRoute < Route
-      def invoke(url)
-        PathFinder.result(self, url)
+      def initialize
+        super(parent: nil)
+      end
+
+      # @param [url] Addressable::URI
+      # @return [Result::Match, Result::Mismatch]
+      def invoke(task)
+        PathFinder.result(self, task)
+      end
+
+      # @return [true, false]
+      def evaluate(path_finder)
+        path_finder.uri.absolute? && !leaf? # Don't route URLs without routes declared
       end
     end
   end

data/lib/wayfarer/routing/route.rb

@@ -5,33 +5,90 @@ module Wayfarer
     class Route
       include DSL
       include Stringify
-      extend Forwardable
+      include Serializable
 
-      attr_reader :children
+      attr_reader :matcher,
+                  :parent,
+                  :children
 
-      attr_accessor :matcher,
-                    :parent,
-                    :action,
-                    :path_offset
+      stringify :matcher
 
-      stringify :matcher,
-                :action,
-                :path_offset
+      EMPTY_PARAMS = {}.freeze
 
-      def initialize(matcher = Matchers::Custom.new { children.any? }, path_offset = "/")
+      def initialize(
+        parent: nil,
+        matcher: nil,
+        action: nil,
+        **options,
+        &block
+      )
+        raise "missing parent" unless parent || is_a?(RootRoute)
+
+        @parent = parent
         @matcher = matcher
+        @action = action
+
         @children = []
-        @path_offset = path_offset
+
+        leaf = options.reduce(self) { |acc, (key, val)| acc.public_send(key, val) }
+        leaf.instance_eval(&block) if block
       end
 
-      # Accepts a visitor for in-order traversal.
+      # @return [true, false]
+      def root?
+        parent.nil?
+      end
+
+      # @return [true, false]
+      def leaf?
+        children.empty?
+      end
+
+      # @return [false]
+      def target?
+        false
+      end
+
+      # Accepts a visitor for pre-order traversal.
       def accept(visitor)
-        return unless visitor.visit(self)
+        visitor.enter(self)
+
+        return visitor.leave unless visitor.visit(self)
 
         children.each { |child| child.accept(visitor) }
+
+        visitor.leave
       end
 
-      delegate match: :matcher
+      # @param [path_finder] PathFinder
+      # @return [Hash]
+      def params(path_finder)
+        matcher&.params(path_finder) || EMPTY_PARAMS
+      end
+
+      # @param [_path_finder] PathFinder
+      # @return [nil, Symbol, Wayfarer::Handler]
+      def action(_path_finder)
+        @action
+      end
+
+      # @param [path_finder] PathFinder
+      # @return [Result::Match, Result::Mismatch, Object]
+      def match(path_finder)
+        evaluate(path_finder)
+      end
+
+      # @param [path_finder] PathFinder
+      # @return [true, false, Wayfarer::Routing::Route]
+      def evaluate(path_finder)
+        matcher.evaluate(path_finder)
+      end
+
+      def to_h
+        return {} unless matcher
+
+        { matcher.class.name.demodulize.underscore => matcher.to_h }
+      end
     end
   end
 end

data/lib/wayfarer/routing/serializable.rb

@@ -0,0 +1,28 @@
+# lib/wayfarer/routing/hash_serialisable.rb
+# frozen_string_literal: true
+
+module Wayfarer
+  module Routing
+    module Serializable
+      def to_h
+        as_hash(self)
+      end
+
+    private
+
+      def as_hash(route)
+        {
+          matcher: matcher_name(route),
+          action: route.action(nil),
+          children: route.children.map { |child| as_hash(child) }
+        }.tap(&:compact!)
+      end
+
+      def matcher_name(route)
+        return nil unless route.matcher
+
+        route.matcher.class.name.split("::").last
+      end
+    end
+  end
+end

data/lib/wayfarer/routing/sub_route.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Wayfarer
+  module Routing
+    class SubRoute < Route
+      def evaluate(path_finder)
+        handle(
+          path_finder,
+          match: ->(_result) { true },
+          mismatch: ->(_result) { false }
+        )
+      end
+
+      def params(path_finder)
+        handle(
+          path_finder,
+          match: lambda(&:params),
+          mismatch: ->(_result) { EMPTY_PARAMS }
+        )
+      end
+
+      def action(path_finder)
+        handle(
+          path_finder,
+          match: lambda(&:action),
+          mismatch: ->(_result) {}
+        )
+      end
+
+    private
+
+      def handle(path_finder, match:, mismatch:)
+        case root = evaluate_matcher(path_finder)
+        when Wayfarer::Routing::RootRoute
+          case result = sub_result(root, path_finder)
+          when Wayfarer::Routing::Result::Match then match.call(result)
+          when Wayfarer::Routing::Result::Mismatch then mismatch.call(result)
+          else raise "invalid result: #{result.inspect}"
+          end
+        else raise "#{route.inspect} is not a root route"
+        end
+      end
+
+      def evaluate_matcher(path_finder)
+        path_finder[matcher] ||= matcher.evaluate(path_finder)
+      end
+
+      def sub_result(route, path_finder)
+        path_finder[route] ||= Wayfarer::Routing::PathFinder.sub_result(route, path_finder)
+      end
+    end
+  end
+end

data/lib/wayfarer/routing/target_route.rb

@@ -2,6 +2,22 @@
 
 module Wayfarer
   module Routing
-    class TargetRoute < Route; end
+    class TargetRoute < Route
+      def evaluate(_path_finder)
+        true
+      end
+
+      def target?
+        true
+      end
+
+      def to_h
+        { action: case @action
+                  when Wayfarer::Handler then { class: @action.class.name }
+                  when Array then { handler: @action.first.class.name, action: @action.second }
+                  else @action
+                  end }
+      end
+    end
   end
 end

data/lib/wayfarer/stringify.rb

@@ -25,8 +25,7 @@ module Wayfarer
       if self.class.stringified_attributes.any?
         attrs = self.class
                     .stringified_attributes
-                    .map { |attr| [attr, public_send(attr)] }
-                    .to_h
+                    .to_h { |attr| [attr, public_send(attr)] }
                     .map { |k, v| "#{k}=#{v.inspect}" }
                     .join(", ")
 

data/lib/wayfarer/task.rb

@@ -6,20 +6,18 @@ module Wayfarer
   # @!attribute [r] batch
   #   @return [String] the batch the task belongs to
   class Task
-    extend Forwardable
+    include KV
     include Stringify
 
-    attr_reader :url, :batch
+    attr_reader :url,
+                :batch
 
     stringify :url, :batch
 
-    delegate %i([] []=) => :@ephemeral
-
     # @!visibility private
     def initialize(url, batch)
       @url = url
       @batch = batch
-      @ephemeral = {}
     end
 
     # @!visibility private