network_rail 0.0.1.alpha

data/.gitignore

@@ -0,0 +1,17 @@
+*.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/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Steve Lorek
+
+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,88 @@
+# Network Rail Data Feeds Ruby Gem
+
+Provides a convenient Ruby wrapper for the [Network Rail Data Feeds](https://datafeeds.networkrail.co.uk) - a live 'firehose' of real-time data about train timings and movements on the national UK rail network.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'network_rail'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install network_rail
+
+## Pre-Requisites
+
+### Register an account
+
+You must first register an account on the [Network Rail Data Feeds](https://datafeeds.networkrail.co.uk) web site. The user name and password you choose will be used for authenticating with the service via the gem.
+
+The service supports only a limited number of users, so you will need to wait for your account status to change to 'Active' before you can use the gem. You will be e-mailed by Network Rail when this happens.
+
+If you do no access the data feeds for for 30 days, your account may switch to an 'Inactive' state, which will prevent you accessing the feeds.
+
+### Subscribe to feeds
+
+Once you're in, you need to subscribe to feeds on the [Network Rail Data Feeds](https://datafeeds.networkrail.co.uk) web site in order to be able to receive them.
+
+## Quick Start
+
+First set your Network Rail user name and password:
+    
+    NetworkRail.configure do |config|
+      config.user_name = YOUR_EMAIL_ADDRESS
+      config.password  = YOUR_PASSWORD
+    end
+
+You don't need to supply your security token because this isn't yet used (according to the documentation in the [Developer Pack](http://www.networkrail.co.uk/WorkArea/DownloadAsset.aspx?id=30064782140)).
+
+The gem implements a [STOMP](http://stomp.github.com/) client to allow you to consume the data feeds, and parses each messages into a convenient Ruby object. Once the client is loaded, it will continue listening for new messages until you tell it to stop.
+
+### Starting the client
+
+You need to load the client to establish the connection between yourself and the feed provider. Create a new instance of the client as below.
+
+    client = NetworkRail::Client.new
+    
+### Subscribing to feeds
+
+Each client can listen to one or more data feeds. You need to specify a feed to begin receiving data. For example:
+
+    client.train_movements(operator: :all) do |movement|
+      # Do something
+    end
+
+Refer to [NetworkRail::Operators#business_codes](https://github.com/slorek/network_rail/blob/master/lib/network_rail/operators.rb) for a list of all supported operator arguments.
+
+Messages will begin to arrive from Network Rail in batches every few seconds. In the above example, `movement` will be an instance of a subclass of `NetworkRail::Message::TrainMovement::Base` (e.g. `NetworkRail::Message::TrainMovement::Arrival`). Some of the cool things you can do with this object are:
+
+- Check if the train arrived on time with `movement.on_time?`
+- Get the delay (if any) with `movement.delay`
+- Determine the next station the train is due to stop at with `movement.next_station`
+
+You can set the threshold at which a train is considered 'late' in the gem configuration.
+
+## Threading
+
+The client runs on a separate thread, so once you've subscribed to all your feeds you need to ensure execution of your script doesn't end immediately. This can be most easily accomplished with something like this:
+
+    while true
+      # Continue forever
+    end
+
+Add your own control logic if you need to do anything more complicated.
+
+## Contributing
+
+1. Fork it
+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
+
+This gem is created by Steven Lorek and is under the MIT License.

data/Rakefile

@@ -0,0 +1,5 @@
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+task default: :spec

data/lib/network_rail/client.rb

@@ -0,0 +1,64 @@
+require "stomp"
+require "json"
+require "network_rail/operators"
+require "network_rail/exception/authentication_error"
+require "network_rail/exception/block_required"
+require "network_rail/exception/connection_error"
+require "network_rail/exception/no_login_credentials"
+
+module NetworkRail
+  class Client
+    
+    HOST_NAME = 'datafeeds.networkrail.co.uk'
+    HOST_PORT = 61618
+    
+    def initialize
+      raise Exception::NoLoginCredentials if NetworkRail.user_name.nil? or NetworkRail.password.nil?
+      
+      self.client = Stomp::Client.new(connection_parameters)
+      
+      raise Exception::ConnectionError unless client.open?
+      
+      if client.connection_frame().command == Stomp::CMD_ERROR
+        raise Exception::AuthenticationError if client.connection_frame().body.match /SecurityException/
+        raise Exception::ConnectionError
+      end
+    end
+    
+    def train_movements(args = {operator: :all}, &block)
+      raise Exception::BlockRequired if !block
+      
+      operator_code = NetworkRail::Operators.business_codes[args[:operator]]
+      
+      client.subscribe("/topic/TRAIN_MVT_#{operator_code}_TOC") do |message|
+        movements = JSON.parse message
+        movements.each {|movement| yield NetworkRail::Message::TrainMovement.factory(movement) }
+      end
+    end
+    
+    private
+    
+      attr_accessor :client
+    
+      def connection_headers
+        {
+          "accept-version" => "1.1",
+          "host"           => HOST_NAME
+        }
+      end
+      
+      def connection_parameters
+        {
+          hosts: [
+            {
+              login:    NetworkRail.user_name,
+              passcode: NetworkRail.password,
+              host:     HOST_NAME,
+              port:     HOST_PORT
+            }
+          ],
+          connect_headers: connection_headers
+        }
+      end
+    end
+end

data/lib/network_rail/configuration.rb

@@ -0,0 +1,25 @@
+module NetworkRail
+  module Configuration
+    VALID_OPTIONS_KEYS = [:user_name, :password, :late_threshold].freeze
+    
+    DEFAULT_USERNAME = nil
+    DEFAULT_PASSWORD = nil
+    
+    attr_accessor *VALID_OPTIONS_KEYS
+    
+    def self.extended(base)
+      base.reset
+    end
+    
+    def configure
+      yield self
+    end
+    
+    def reset
+      self.user_name = DEFAULT_USERNAME
+      self.password = DEFAULT_PASSWORD
+      self.late_threshold = 60
+      self
+    end
+  end
+end

data/lib/network_rail/exception/authentication_error.rb

@@ -0,0 +1,6 @@
+module NetworkRail
+  module Exception
+    class AuthenticationError < ::Exception
+    end
+  end
+end

data/lib/network_rail/exception/block_required.rb

@@ -0,0 +1,6 @@
+module NetworkRail
+  module Exception
+    class BlockRequired < ::Exception
+    end
+  end
+end

data/lib/network_rail/exception/connection_error.rb

@@ -0,0 +1,6 @@
+module NetworkRail
+  module Exception
+    class ConnectionError < ::Exception
+    end
+  end
+end

data/lib/network_rail/exception/no_login_credentials.rb

@@ -0,0 +1,6 @@
+module NetworkRail
+  module Exception
+    class NoLoginCredentials < ::Exception
+    end
+  end
+end

data/lib/network_rail/message/train_movement/activation.rb

@@ -0,0 +1,10 @@
+require "network_rail/message/train_movement/base"
+
+module NetworkRail
+  module Message
+    module TrainMovement
+      class Activation < Base
+      end
+    end
+  end
+end

data/lib/network_rail/message/train_movement/arrival.rb

@@ -0,0 +1,10 @@
+require "network_rail/message/train_movement/movement"
+
+module NetworkRail
+  module Message
+    module TrainMovement
+      class Arrival < Movement
+      end
+    end
+  end
+end

data/lib/network_rail/message/train_movement/base.rb

@@ -0,0 +1,18 @@
+module NetworkRail
+  module Message
+    module TrainMovement
+      class Base
+        
+        attr_accessor :original_message
+        
+        def initialize(json_message)
+          self.original_message = json_message
+        end
+
+        def self.factory(json_message)
+          self.new(json_message)
+        end
+      end
+    end
+  end
+end

data/lib/network_rail/message/train_movement/cancellation.rb

@@ -0,0 +1,10 @@
+require "network_rail/message/train_movement/base"
+
+module NetworkRail
+  module Message
+    module TrainMovement
+      class Cancellation < Base
+      end
+    end
+  end
+end

data/lib/network_rail/message/train_movement/change_of_identity.rb

@@ -0,0 +1,10 @@
+require "network_rail/message/train_movement/base"
+
+module NetworkRail
+  module Message
+    module TrainMovement
+      class ChangeOfIdentity < Base
+      end
+    end
+  end
+end

data/lib/network_rail/message/train_movement/change_of_origin.rb

@@ -0,0 +1,10 @@
+require "network_rail/message/train_movement/base"
+
+module NetworkRail
+  module Message
+    module TrainMovement
+      class ChangeOfOrigin < Base
+      end
+    end
+  end
+end

data/lib/network_rail/message/train_movement/departure.rb

@@ -0,0 +1,10 @@
+require "network_rail/message/train_movement/movement"
+
+module NetworkRail
+  module Message
+    module TrainMovement
+      class Departure < Movement
+      end
+    end
+  end
+end

data/lib/network_rail/message/train_movement/movement.rb

@@ -0,0 +1,37 @@
+require "network_rail/operators"
+require "network_rail/message/train_movement/base"
+
+module NetworkRail
+  module Message
+    module TrainMovement
+      class Movement < Base
+        
+        require "network_rail/message/train_movement/arrival"
+        require "network_rail/message/train_movement/departure"
+        
+        attr_accessor :time, :planned_time, :operator
+        
+        def self.factory(json_message)
+          event_type = json_message['body']['event_type']
+          target_class = event_type == 'ARRIVAL' ? Arrival : Departure
+          target_class.new(json_message)
+        end
+        
+        def initialize(json_message)
+          super
+          self.time = Time.at (json_message['body']['actual_timestamp'].to_i / 1000).to_i
+          self.planned_time = Time.at (json_message['body']['planned_timestamp'].to_i / 1000).to_i
+          self.operator = NetworkRail::Operators.numeric_codes.find {|key, value| value == json_message['body']['toc_id'].to_i }.first
+        end
+        
+        def on_time?
+          delay <= NetworkRail.late_threshold
+        end
+        
+        def delay
+          (time - planned_time).round
+        end
+      end
+    end
+  end
+end

data/lib/network_rail/message/train_movement/reinstatement.rb

@@ -0,0 +1,10 @@
+require "network_rail/message/train_movement/base"
+
+module NetworkRail
+  module Message
+    module TrainMovement
+      class Reinstatement < Base
+      end
+    end
+  end
+end

data/lib/network_rail/message/train_movement.rb

@@ -0,0 +1,31 @@
+require "date"
+require "network_rail/message/train_movement/movement"
+require "network_rail/message/train_movement/activation"
+require "network_rail/message/train_movement/cancellation"
+require "network_rail/message/train_movement/change_of_identity"
+require "network_rail/message/train_movement/change_of_origin"
+require "network_rail/message/train_movement/reinstatement"
+
+module NetworkRail
+  module Message
+    module TrainMovement
+      def self.factory(json_message)
+        target_class = message_type_to_class_mapping[json_message['header']['msg_type']]
+        target_class.factory(json_message)
+      end
+    
+      private
+      
+        def self.message_type_to_class_mapping
+          {
+            '0001' => Activation,
+            '0002' => Cancellation,
+            '0003' => Movement,
+            '0005' => Reinstatement,
+            '0006' => ChangeOfOrigin,
+            '0007' => ChangeOfIdentity
+          }
+        end
+    end
+  end
+end

data/lib/network_rail/operators.rb

@@ -0,0 +1,82 @@
+module NetworkRail
+  module Operators
+    def self.business_codes
+      {
+        all: 'ALL',
+        all_passenger: 'PASSENGER',
+        freight: 'GENERAL',
+        arriva_trains_wales: 'HL',
+        c2c: 'HT',
+        chiltern_railway: 'HO',
+        cross_country: 'EH',
+        devon_and_cornwall_railway: 'EN',
+        east_midlands_trains: 'EM',
+        east_coast: 'HB',
+        eurostar: 'GA',
+        first_capital_connect: 'EG',
+        first_great_western: 'EF',
+        first_hull_trains: 'PF',
+        first_scotrail: 'HA',
+        first_transpennine_xpress: 'EA',
+        gatwick_express: 'HV',
+        grand_central: 'EC',
+        heathrow_connect: 'EE',
+        heathrow_express: 'HM',
+        island_lines: 'HZ',
+        london_midland: 'EJ',
+        london_overground: 'EK',
+        london_underground_bakerloo_line: 'XC',
+        london_underground_district_line_wimbledon: 'XB',
+        london_underground_district_line_richmond: 'XE',
+        merseyrail: 'HE',
+        greater_anglia: 'EB',
+        nexus: 'PG',
+        north_yorkshire_moors_railway: 'PR',
+        northern_rail: 'ED',
+        south_west_trains: 'HY',
+        south_eastern: 'HU',
+        southern: 'HW',
+        virgin_trains: 'HF',
+        west_coast_railway: 'PA'
+      }
+    end
+
+    def self.numeric_codes
+      {
+        arriva_trains_wales: 71,
+        c2c: 79,
+        chiltern_railway: 74,
+        cross_country: 27,
+        devon_and_cornwall_railway: 34,
+        east_midlands_trains: 28,
+        east_coast: 61,
+        eurostar: 6,
+        first_capital_connect: 26,
+        first_great_western: 25,
+        first_hull_trains: 55,
+        first_scotrail: 60,
+        first_transpennine_xpress: 20,
+        gatwick_express: 81,
+        grand_central: 22,
+        heathrow_connect: 24,
+        heathrow_express: 86,
+        island_lines: 85,
+        london_midland: 29,
+        london_overground: 30,
+        london_underground_bakerloo_line: 91,
+        london_underground_district_line_wimbledon: 90,
+        london_underground_district_line_richmond: 93,
+        merseyrail: 64,
+        greater_anglia: 21,
+        nexus: 56,
+        north_yorkshire_moors_railway: 51,
+        northern_rail: 23,
+        south_west_trains: 84,
+        south_eastern: 80,
+        southern: 82,
+        virgin_trains: 65,
+        west_coast_railway: 50
+      }
+    end
+  end
+end

data/lib/network_rail/version.rb

@@ -0,0 +1,3 @@
+module NetworkRail
+  VERSION = "0.0.1.alpha"
+end

data/lib/network_rail.rb

@@ -0,0 +1,9 @@
+require "network_rail/operators"
+require "network_rail/client"
+require "network_rail/configuration"
+require "network_rail/version"
+require "network_rail/message/train_movement"
+
+module NetworkRail
+  extend Configuration
+end

data/network_rail.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'network_rail/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "network_rail"
+  spec.version       = NetworkRail::VERSION
+  spec.authors       = ["Steve Lorek"]
+  spec.email         = ["steve@stevelorek.com"]
+  spec.description   = %q{Provides a Ruby wrapper for consuming Network Rail Data Feeds}
+  spec.summary       = %q{Ruby wrapper for consuming Network Rail Data Feeds}
+  spec.homepage      = "http://github.com/slorek/network_rail"
+  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.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "i18n"
+  spec.add_development_dependency "active_support"
+  spec.add_runtime_dependency "stomp"
+  spec.add_runtime_dependency "json"
+end