connected 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3207847fee29e8a23ed1a8456571a8e88ab3e73c3d2df63d8cadad3b34b6382f
+  data.tar.gz: 6c9944da0f906bb91ad8add7ae63dfed303452ac8f4f6b228b8e769cdb69de96
+SHA512:
+  metadata.gz: 12ba3ef422355e9b9cc608a29c90579af5e4adee228e94bc4348de44e595c8e673c9ec12cc319143a28b6e39d26807ede22232edfe12756feed08a21a4768f4c
+  data.tar.gz: 4ab7b7e541f3171dbd841980f0d63d0ad83a0cf18504d6d11b2a8e499ba70f4738f0ad093737b10e38af485f055f10268f9152c32a2ba111c23abbc2adacdb84

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,44 @@
+AllCops:
+  TargetRubyVersion: 2.6
+
+Metrics/MethodLength:
+  Max: 30
+
+Layout/LineLength:
+  Max: 100
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/ModuleLength:
+  Max: 150
+
+Metrics/CyclomaticComplexity:
+  Max: 7
+
+Metrics/AbcSize:
+  Max: 25
+
+Metrics/PerceivedComplexity:
+  Max: 8
+  Exclude:
+    - 'spec/**/*_spec.rb'
+
+Metrics/BlockLength:
+  Max: 35
+  Exclude:
+    - '*.gemspec'
+    - Rakefile
+    - 'spec/**/*_spec.rb'
+    - 'spec/spec_helper.rb'
+
+Metrics/ParameterLists:
+  Max: 6
+
+Naming/MethodParameterName:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Security/Eval:
+  Exclude:
+    - Gemfile

data/.travis.yml

@@ -0,0 +1,14 @@
+language: ruby
+cache: bundler
+rvm:
+- 2.6.6
+before_install: gem install bundler -v 2.1.4
+deploy:
+  provider: rubygems
+  api_key:
+    secure: nCpiK6ht0RMKBZa5nX3o1YXKbgL6+DdXQYjszMUrt1+i7edVLqg9Y6XOXfsY8r3zI9CiX0dbrq9w9uF7ELLBkPiV7bhzvshmkGMQuc5MvC/FvHTzizkeJj7L85Z8impkF+cQXFKyKOptlUOlud9SJQZXk86DEHYI3Rg1GJklZ6AAVZQ5ixz/TBUhrMJPGXZEaN+tErio17CVZ38xgp/CwkIsV3MhRMaruGOidIXPQXJCOtElD+BUOIZ9pU0yJxJlbTucCtcWyO1wa7B9HbxodEv7O/kDRj8+rWESSHg18T8otS7vVyDZYUeVbSNVULQM3epCDvwVQZiMyBphpNaNOf9p9SCH2i11L+HWomOEdcZNy+8BwRbIiU/vWgbm2QI3XQxnQxwg48eIR3xjwWcsGwZFIP9DGykuF7fP+IgrBJ3pPb1tORW8FwTB6adMaSdIYKRvt5D+mm3DUzrMDHHN6Nc3hGGQkNc9Tya2PvwBx/bdjPK/L9nYBhsTEao3DyfFLXDU1zGwuWcmQHjd6qStgD21AgbL8qvhLbAP5tVeYx6gKeONcHtoCLf6XP/UN5RyabBCVNBYymHQLobgAw/Ozthj+b0n5ke2CkIOyRB4pgk/nee4UChMikRscG5CHvj3pBrhFGWRHxUOMvHSGtOswuclDqs8v20Vm/BGrcJEsaU=
+  gem: connected
+  on:
+    tags: true
+    repo: jgnagy/connected
+  skip_cleanup: 'true'

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in spf.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,67 @@
+PATH
+  remote: .
+  specs:
+    connected (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.0)
+    diff-lcs (1.3)
+    docile (1.3.2)
+    parallel (1.19.1)
+    parser (2.7.1.3)
+      ast (~> 2.4.0)
+    rainbow (3.0.0)
+    rake (13.0.1)
+    regexp_parser (1.7.0)
+    rexml (3.2.4)
+    rspec (3.9.0)
+      rspec-core (~> 3.9.0)
+      rspec-expectations (~> 3.9.0)
+      rspec-mocks (~> 3.9.0)
+    rspec-core (3.9.2)
+      rspec-support (~> 3.9.3)
+    rspec-expectations (3.9.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-mocks (3.9.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-support (3.9.3)
+    rubocop (0.85.0)
+      parallel (~> 1.10)
+      parser (>= 2.7.0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.7)
+      rexml
+      rubocop-ast (>= 0.0.3)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    rubocop-ast (0.0.3)
+      parser (>= 2.7.0.1)
+    ruby-progressbar (1.10.1)
+    simplecov (0.18.5)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+    simplecov-cobertura (1.3.1)
+      simplecov (~> 0.8)
+    simplecov-html (0.12.2)
+    unicode-display_width (1.7.0)
+    yard (0.9.25)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 2)
+  connected!
+  rake (~> 13)
+  rspec (~> 3.0)
+  rubocop (~> 0.50)
+  simplecov (~> 0.15)
+  simplecov-cobertura (~> 1.3)
+  yard (~> 0.9)
+
+BUNDLED WITH
+   2.1.4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Jonathan Gnagy
+
+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,338 @@
+<img src=".images/logo.png" alt="Connected logo" title="Connected" align="right" height="40" />
+
+# Connected
+
+_Connected_ aims to be useful for overlaying and solving both directed and undirected graphs. The goal is to provide generic mixins to add a solver to real code, rather than an academic demonstration of how Dijkstra's algorithm works.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'connected'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install connected
+
+## Usage
+
+### Simple Uses
+
+For a simpler use-cases, the classes `Connected::GenericNode`, `Connected::GenericConnection`, and `Connected::Path` will suffice. These can either be subclassed or extended to wrap any real work. First, I'll just demonstrate how they work with an undirected graph (meaning a set of bidirectional connections):
+
+```ruby
+require 'connected'
+
+include Connected
+
+# First, let's make some nodes
+node_a = GenericNode.new('a')
+node_b = GenericNode.new('b')
+node_c = GenericNode.new('c')
+node_d = GenericNode.new('d')
+
+# Now we can create connections between some of them
+node_a.connects_to node_b, metric: 1
+node_a.connects_to node_c, metric: 10
+node_b.connects_to node_c, metric: 3
+node_b.connects_to node_d, metric: 2, state: :closed
+node_c.connects_to node_d, metric: 3
+```
+
+The above represents a graph like this in code:
+
+```text
+(a)_(b) _ _ _ _ (d)
+ \____\___(c)___/
+```
+
+Based on this, the fastest (lowest cost) route from node "a" to node "d" should be "a" to "b" to "c" to "d" with a total cost of `7`. Let's find that in code:
+
+```ruby
+path = Path.find(from: node_a, to: node_d)
+path.to_s
+# => "a -> b -> c -> d"
+path.cost
+# => 7
+```
+
+We can also find paths based on least hops rather than lowest metric cost by first getting all "reasonable" routes (meaning as it finds candidates, it rejects those that have too many hops or too high of a metric):
+
+```ruby
+candidate_paths = Path.all(from: node_a, to: node_d)
+candidate_paths.size
+# => 2
+candidate_paths.min_by(&:hops).to_s
+# => "a -> c -> d"
+```
+
+We can simulate or ignore when paths are closed as well:
+
+```ruby
+path = Path.find(from: node_a, to: node_d, include_closed: true)
+path.to_s
+# => "a -> b -> d"
+path.cost
+# => 3
+```
+
+This behavior of excluding suboptimal routes from `Path.all()` might be confusing if you're really looking for **every** possible route. In this case, you can add `suboptimal: true` and it'll really give you every possible route, sorted from lowest to highest cost.
+
+```ruby
+every_path = Path.all(from: node_a, to: node_d, suboptimal: true)
+every_path.size
+# => 2
+every_path_even_closed = Path.all(
+    from: node_a,
+    to: node_d,
+    suboptimal: true,
+    include_closed: true
+)
+every_path_even_closed.size
+# => 4
+every_path_even_closed.map(&:to_s)
+# => ["a -> b -> d", "a -> b -> c -> d", "a -> c -> d", "a -> c -> b -> d"]
+```
+
+It is possible to manipulate connections after they've been defined. To retrieve the `GenericConnection` object, use `#connection_to` on the source node:
+
+```ruby
+connection = node_b.connection_to(node_d)
+connection.state
+# => :closed
+connection.metric
+# => 2
+connection.state = :open
+
+# Now we can see that our previous simulation is right
+Path.find(from: node_a, to: node_d).to_s
+# => "a -> b -> d"
+```
+
+All the above examples are based on connections created using `node.connects_to other_node`, which creates a bi-directional connection. For representing _directed_ graph, you can add `directed: true` to the method which causes it to only create the connection you explicitly described (meaning it won't create the connection back for you).
+
+### Overlaying on Other Objects
+
+Nearly all the above capabilities are available via modules that can be mixed into your own objects. Just like adding `include Comparable` to your own code requires the `<=>` method be defined on your Object, mixing in the Connected modules require a few methods be available on instances.
+
+Mixing in `Connected::Vertex` into your node-like classes requires the `#connections` method be implemented (either directly or as a readable attribute). This method is used to find all connections/`Edge` objects associated with (i.e., with the `from` set to) the object in question. No sorting is necessary; it just needs to provide an Array (or Array-like collection) of instances with `Connected::Edge` mixed in. These connections don't even need to exist outside of the `#connections` method call; they can be constructed and yielded on demand.
+
+Connections between Vertices (called _edges_) mix in the `Connected::Edge` module and require `#from` and `#to` be implemented. In most cases, you'll also want to implement `#metric` (otherwise it'll always be `1`) and either `#state` (otherwise it'll always be `:open`) or both `#open?` and `#closed?`. The default implementations of `#open?` and `#closed?` check if `#state` is `:open` or `:closed`, respectively.
+
+Let's build a simple example network and implement a lightweight version of [OSPF](https://en.wikipedia.org/wiki/Open_Shortest_Path_First) (we won't actually implement the _protocol_, just the concept of finding the shortest open path). This is going to be a decent chunk of code, but it is worth reading over. First, let's build our classes:
+
+```ruby
+require 'connected'
+
+class Subnet
+  attr_reader :links
+
+  def initialize(block:)
+    @block = block # needs to be in CIDR notation <= /24
+    @links = [] # Here we'll store all the links to this subnet
+  end
+
+  def size
+    bits = 32 - @block.split('/').last.to_i
+    2**bits
+  end
+
+  def first_three
+    @block.split('.').first(3).join('.')
+  end
+
+  def assign_ip(link, ip: nil)
+    all_ips = (1..(size - 2)).to_a.map { |ip| [first_three, ip].join('.') }
+    used_ips = @links.map(&:ip)
+
+    new_ip = if ip
+              raise 'Invalid IP' unless all_ips.include?(ip)
+
+              raise 'Duplicate IP' if used_ips.include?(ip)
+
+              ip
+            else
+              (all_ips - used_ips).sample # picks a random available IP
+            end
+
+    @links << link unless @links.include?(link)
+
+    new_ip
+  end
+end
+
+class Link
+  attr_reader :device, :subnet
+  attr_accessor :speed, :state
+
+  def initialize(device:, subnet:, speed: 1000, state: :up)
+    @device = device
+    @subnet = subnet
+    @speed = speed
+    @state = state
+    @ip = nil
+  end
+
+  def ip
+    @ip ||= subnet.assign_ip(self)
+  end
+
+  def ip=(value)
+    return true if @ip == value
+
+    subnet.assign_ip(self, ip: value) # will raise an error if duplicate
+    @ip = value
+  end
+end
+
+class Router
+  include Connected::Vertex
+
+  attr_reader :name, :links
+
+  def initialize(name:)
+    @name = name
+    @links = []
+  end
+
+  def add_link(subnet, ip: nil, speed: 1000, state: :up)
+    return false if subnets.include?(subnet) # only one connection per subnet
+
+    link = Link.new(device: self, subnet: subnet, speed: speed, state: state)
+    if ip
+      link.ip = ip
+    else
+      link.ip # let the link request its own IP
+    end
+
+    @links << link
+    link
+  end
+
+  def subnets
+    links.map(&:subnet)
+  end
+
+  def ips
+    links.map(&:ip)
+  end
+
+  # Here's the method required by Connected
+  def connections
+    # Dynamically build a collection of Adjacencies
+    links.map do |link|
+      link.subnet.links.reject { |l| l == link }.map do |other_link|
+        Adjacency.new(from: self, to: other_link.device, links: [link, other_link])
+      end
+    end.flatten
+  end
+end
+
+class Adjacency
+  include Connected::Edge
+
+  attr_reader :from, :to
+
+  def initialize(from:, to:, links:)
+    @from = from
+    @to = to
+    @links = links
+  end
+
+  def state
+    # either both up or the adjacency is "closed"
+    @links.map(&:state).uniq == [:up] ? :open : :closed
+  end
+
+  # Lower metrics are better, so take the lowest speed connection and
+  #   use the inverse
+  def metric
+    1.0 / @links.map(&:speed).min
+  end
+end
+
+class Route < Connected::Path
+end
+```
+
+Now we can setup some routers and attach them to some subnets (and let our fake DHCP assign them IPs):
+
+```ruby
+sub1 = Subnet.new(block: '192.168.1.0/24')
+sub2 = Subnet.new(block: '192.168.2.0/24')
+sub3 = Subnet.new(block: '192.168.3.0/27')
+
+bob = Router.new(name: 'Bob')
+alice = Router.new(name: 'Alice')
+joe = Router.new(name: 'Joe')
+jim = Router.new(name: 'Jim')
+lonely = Router.new(name: 'Lonely')
+
+bob.add_link(sub1)
+bob.add_link(sub3, speed: 100)
+alice.add_link(sub1)
+alice.add_link(sub2)
+joe.add_link(sub2)
+joe.add_link(sub3)
+jim.add_link(sub1, speed: 10_000)
+jim.add_link(sub3, speed: 10_000)
+lonely.add_link(sub3, speed: 5_000)
+
+bob.ips
+# => ["192.168.1.25", "192.168.3.8"]
+alice.ips
+# => ["192.168.1.155", "192.168.2.11"]
+joe.ips
+# => ["192.168.2.123", "192.168.3.17"]
+jim.ips
+# => ["192.168.1.174", "192.168.3.6"]
+lonely.ips
+# => ["192.168.3.2"]
+
+# Bob has a direct connection to everyone
+bob.neighbors.map(&:name)
+# => ["Alice", "Jim", "Joe", "Lonely"]
+
+# Alice can't _directly_ connect to Lonely
+alice.neighbors.map(&:name)
+# => ["Bob", "Jim", "Joe"]
+```
+
+Now let's take a look at how routing looks:
+
+```ruby
+# Even though Bob is directly connected to subnet 3 (where Lonely is),
+# it is faster to get there through Jim
+Route.find(from: bob, to: lonely).to_s
+# => "Bob -> Jim -> Lonely"
+
+# Bob uses his direct connection to talk to Alice
+Route.find(from: bob, to: alice).to_s
+# => "Bob -> Alice"
+
+# Alice also goes through Jim to get to Lonely
+Route.find(from: alice, to: lonely).to_s
+# => "Alice -> Jim -> Lonely"
+```
+
+That all works! Links themselves (and their states) were memoized but the adjacencies were constructed and used dynamically. Notice that while there was a fair amout of setup/code there, very little was associated with comparing connections and the `Route` class is entirely empty!
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jgnagy/connected.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+require 'yard'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new(:rubocop)
+YARD::Rake::YardocTask.new do |y|
+  y.options = [
+    '--markup', 'markdown'
+  ]
+end
+
+task default: %i[spec rubocop yard]

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'connected'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/connected.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative 'lib/connected/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'connected'
+  spec.version       = Connected::VERSION
+  spec.authors       = ['Jonathan Gnagy']
+  spec.email         = ['jonathan.gnagy@gmail.com']
+
+  spec.summary       = 'A shortest path first gem'
+  spec.description   = 'A Ruby object-oriented solver for directed and undirected ' \
+                       'graphs based loosely on Dijkstra\'s algorithm'
+  spec.homepage      = 'https://github.com/jgnagy/connected'
+
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.6.0')
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 2'
+  spec.add_development_dependency 'rake', '~> 13'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '~> 0.50'
+  spec.add_development_dependency 'simplecov', '~> 0.15'
+  spec.add_development_dependency 'simplecov-cobertura', '~> 1.3'
+  spec.add_development_dependency 'yard', '~> 0.9'
+end

data/lib/connected.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'connected/version'
+require 'connected/edge'
+require 'connected/vertex'
+require 'connected/generic_node'
+require 'connected/generic_connection'
+require 'connected/path'

data/lib/connected/edge.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Connected
+  # Used to mixin a direct connection between two Vertices (an Edge) on a graph
+  module Edge
+    include Comparable
+
+    def from
+      # Expect classes to describe the "from" Vertex
+      raise "#from() MUST be implemented on #{self.class.name}"
+    end
+
+    def to
+      # Expect classes to describe the "to" Vertex
+      raise "#to() MUST be implemented on #{self.class.name}"
+    end
+
+    # This should almost certainly be overridden
+    def metric
+      1
+    end
+
+    def closed?
+      unless respond_to?(:state)
+        # Expect classes to describe how to determine if they're closed
+        raise "#state() or #closed? MUST be implemented on #{self.class.name}"
+      end
+
+      state.to_s == :closed.to_s
+    end
+
+    def open?
+      unless respond_to?(:state)
+        # Expect classes to describe how to determine if they're open
+        raise "#state() or #open? MUST be implemented on #{self.class.name}"
+      end
+
+      state.to_s == :open.to_s
+    end
+
+    def <=>(other)
+      if (open? && other.open?) || (closed? && other.closed?)
+        metric <=> other.metric
+      elsif open?
+        -1
+      elsif other.open?
+        1
+      end
+    end
+  end
+end

data/lib/connected/generic_connection.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Connected
+  # A generic implementation of an Edge
+  class GenericConnection
+    include Edge
+
+    attr_reader :from, :to, :metric, :state
+
+    def initialize(from:, to:, metric: 1, state: :open)
+      validate_from(from)
+      validate_to(to)
+      validate_metric(metric)
+      validate_state(state)
+
+      raise 'Invalid Connection from and to same Vertex' if from == to
+
+      @from = from
+      @to = to
+      @metric = metric
+      @state = state
+    end
+
+    def metric=(value)
+      validate_metric(value)
+      @metric = value
+    end
+
+    def state=(setting)
+      validate_state(setting)
+      @state = setting
+    end
+
+    private
+
+    def validate_from(node)
+      raise 'Invalid from Node' unless node.is_a?(Vertex)
+    end
+
+    def validate_to(node)
+      raise 'Invalid to Node' unless node.is_a?(Vertex)
+    end
+
+    def validate_metric(num)
+      raise 'Invalid metric' unless num.is_a?(Numeric) && num.positive?
+    end
+
+    def validate_state(value)
+      raise 'Invalid state' unless %i[open closed].include?(value)
+    end
+  end
+end

data/lib/connected/generic_node.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Connected
+  # Generic example node
+  class GenericNode
+    include Vertex
+
+    attr_reader :name
+    attr_accessor :connections
+
+    def initialize(name)
+      @name = name
+      @connections = []
+    end
+
+    def connects_to(other, metric: 1, state: :open, directed: false)
+      # Only one connection between nodes
+      return true if neighbors.include?(other)
+
+      connections << GenericConnection.new(
+        from: self, to: other, metric: metric, state: state.to_sym
+      )
+
+      other.connects_to(self, metric: metric, state: state) unless directed
+    end
+
+    def disconnect_from(other, directed: false)
+      connections.delete_if { |c| c.to == other }
+      other.disconnect_from(self) if other.neighbors.include?(self) && !directed
+    end
+  end
+end

data/lib/connected/path.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Connected
+  # Represents an indirect connection (combined edges) between two Vertices on a graph
+  class Path
+    def initialize(nodes, validate: true)
+      validate_nodes(nodes) if validate
+
+      @nodes = nodes
+    end
+
+    def connections
+      links = nodes.dup
+      links.size.downto(2).map do |i|
+        links[-1 * i].connection_to(links[-1 * (i - 1)])
+      end
+    end
+
+    def cost
+      connections.map(&:metric).reduce(&:+)
+    end
+
+    def hops
+      nodes.size - 1
+    end
+
+    def branch(node)
+      return unless nodes.last.neighbors.include?(node) && !nodes.include?(node)
+
+      self.class.new(nodes + [node], validate: false)
+    end
+
+    def nodes
+      @nodes.dup
+    end
+
+    def open?
+      connections.select(&:closed?).empty?
+    end
+
+    def from
+      nodes.first
+    end
+
+    def to
+      nodes.last
+    end
+
+    def to_s(separator = ' -> ')
+      nodes.map(&:name).join(separator)
+    end
+
+    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/PerceivedComplexity
+    def self.all(from:, to:, include_closed: false, debug: false, suboptimal: false)
+      paths = []
+
+      path_queue = from.neighbors.map { |n| new([from, n]) }
+
+      until path_queue.empty?
+        this_path = path_queue.pop
+        next unless this_path.open? || include_closed
+
+        puts "Walking from #{this_path.nodes.map(&:name).join(' to ')}" if debug
+
+        if this_path.to == to
+          puts "Found destination with #{this_path.nodes.map(&:name).join(' to ')}" if debug
+          paths << this_path
+        else
+          highmetric = paths.max_by(&:cost)&.cost
+          highops = paths.max_by(&:hops)&.hops
+
+          this_path.to.neighbors.each do |n|
+            new_path = this_path.branch(n)
+            next unless new_path
+
+            if paths.empty? || new_path.cost <= highmetric || new_path.hops <= highops || suboptimal
+              path_queue.unshift(new_path)
+            elsif debug
+              puts "Skipping #{new_path.nodes.map(&:name).join(' to ')}"
+            end
+          end
+        end
+      end
+
+      # Return the list of paths, sorted first by cost then by hops
+      paths.sort_by { |p| [p.cost, p.hops] }
+    end
+    # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics/PerceivedComplexity
+
+    def self.find(from:, to:, include_closed: false)
+      all(from: from, to: to, include_closed: include_closed).first
+    end
+
+    private
+
+    def validate_nodes(list)
+      # Want to throw an exception if there are loops
+      raise 'Invalid Nodes list, duplicates found' unless list.size == list.uniq.size
+
+      list.each_with_index do |item, index|
+        break if index == list.size - 1
+
+        # Each node should connect to the next (no leaves except the end of the list)
+        raise 'Invalid Nodes list, broken chain' unless item.neighbors.include?(list[index + 1])
+      end
+
+      true
+    end
+  end
+end

data/lib/connected/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Connected
+  VERSION = '0.1.0'
+end

data/lib/connected/vertex.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Connected
+  # Vertices are based on a mixin
+  module Vertex
+    def connections
+      # Expect classes to describe how to find connections
+      raise "#connections() MUST be implemented on #{self.class.name}"
+    end
+
+    # A shortcut for retrieving this node's neighbors
+    def neighbors
+      connections.map(&:to).uniq
+    end
+
+    # Retrieves the Connection object responsible for connecting to a Node
+    def connection_to(other)
+      connections.select { |c| c.to == other }.min_by(&:metric)
+    end
+  end
+end

metadata

@@ -0,0 +1,162 @@
+--- !ruby/object:Gem::Specification
+name: connected
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jonathan Gnagy
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2020-06-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.50'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.15'
+- !ruby/object:Gem::Dependency
+  name: simplecov-cobertura
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: A Ruby object-oriented solver for directed and undirected graphs based
+  loosely on Dijkstra's algorithm
+email:
+- jonathan.gnagy@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".images/logo.png"
+- ".rspec"
+- ".rubocop.yml"
+- ".travis.yml"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- connected.gemspec
+- lib/connected.rb
+- lib/connected/edge.rb
+- lib/connected/generic_connection.rb
+- lib/connected/generic_node.rb
+- lib/connected/path.rb
+- lib/connected/version.rb
+- lib/connected/vertex.rb
+homepage: https://github.com/jgnagy/connected
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.8
+signing_key:
+specification_version: 4
+summary: A shortest path first gem
+test_files: []