ldbws 1.0.0

data/lib/ldbws/service.rb

@@ -0,0 +1,218 @@
+require "faraday"
+require "nokogiri"
+require "uri"
+
+require "ldbws/request/get_departures_board"
+require "ldbws/request/get_service_details"
+require "ldbws/request/get_station_board"
+require "ldbws/utils"
+
+module Ldbws
+  # A wrapper around the National Rail Live Departure Boards Webservice (LDBWS) API.
+  #
+  # API methods are pretty much as-specified in {the documentation}[https://lite.realtime.nationalrail.co.uk/openldbws/],
+  # although methods on this class are specified using snake_case rather than the CamelCase used in the web service.
+  #
+  # === Usage example
+  #
+  # TL;DR:
+  #
+  #  service = new Ldbws::Service( "YOUR-API-TOKEN" )
+  #  departures = service.get_departure_board( crs: "CDF" )
+  #
+  # Will furnish you with a list of all departures from Cardiff Central. Other methods work pretty much as you’d expect
+  # if you’ve any familiarity with the service.
+  # Individual requests use Request[rdoc-ref:Request] objects to validate input parameters, and this is noted below. See
+  # the corresponding request object for each method for further information as to the parameters.
+  #
+  # === Side note
+  #
+  # The official documentation for this web service is… lacking. While an attempt has been made to elucidate on both the
+  # request parameters and response properties, it shouldn’t be taken as any kind of source of truth. Caveat emptor.
+  class Service
+    SERVICE_URI = URI("https://realtime.nationalrail.co.uk/OpenLDBWS/ldb12.asmx") # :nodoc:
+
+    # Creates a service object.
+    #
+    # === Parameters
+    # token:: the API token used to connect to the service
+    def initialize(token)
+      @token = token
+    end
+
+    # Retrieves a station departure board.
+    #
+    # Parameters are validated using GetStationBoard[rdoc-ref:Request::GetStationBoard], returns a
+    # StationBoard[rdoc-ref:ResponseTypes::StationBoard] object.
+    def get_departure_board(params)
+      request(
+        "http://thalesgroup.com/RTTI/2012-01-13/ldb/GetDepartureBoard",
+        Request::GetStationBoard.new(params)
+      )
+    end
+
+    # Retrieves a station arrival board.
+    #
+    # Parameters are validated using GetStationBoard[rdoc-ref:Request::GetStationBoard], returns a
+    # StationBoard[rdoc-ref:ResponseTypes::StationBoard] object.
+    def get_arrival_board(params)
+      request(
+        "http://thalesgroup.com/RTTI/2012-01-13/ldb/GetArrivalBoard",
+        Request::GetStationBoard.new(params)
+      )
+    end
+
+    # Retrieves a station arrival + departure board.
+    #
+    # Parameters are validated using GetStationBoard[rdoc-ref:Request::GetStationBoard], returns a
+    # StationBoard[rdoc-ref:ResponseTypes::StationBoard] object.
+    def get_arrival_departure_board(params)
+      request(
+        "http://thalesgroup.com/RTTI/2012-01-13/ldb/GetArrivalDepartureBoard",
+        Request::GetStationBoard.new(params)
+      )
+    end
+
+    # Retrieves a detailed station departure board.
+    #
+    # Parameters are validated using GetStationBoardWithDetails[rdoc-ref:Request:GetStationBoardWithDetails], returns a
+    # StationBoardWithDetails[rdoc-ref:ResponseTypes::StationBoardWithDetails] object.
+    def get_dep_board_with_details(params)
+      request(
+        "http://thalesgroup.com/RTTI/2015-05-14/ldb/GetDepBoardWithDetails",
+        Request::GetStationBoardWithDetails.new(params)
+      )
+    end
+
+    # Retrieves a detailed station arrival board.
+    #
+    # Parameters are validated using GetStationBoardWithDetails[rdoc-ref:Request:GetStationBoardWithDetails], returns a
+    # StationBoardWithDetails[rdoc-ref:ResponseTypes::StationBoardWithDetails] object.
+    def get_arr_board_with_details(params)
+      request(
+        "http://thalesgroup.com/RTTI/2015-05-14/ldb/GetArrBoardWithDetails",
+        Request::GetStationBoardWithDetails.new(params)
+      )
+    end
+
+    # Retrieves a detailed station arrival + departures board.
+    #
+    # Parameters are validated using GetStationBoardWithDetails[rdoc-ref:Request:GetStationBoardWithDetails], returns a
+    # StationBoardWithDetails[rdoc-ref:ResponseTypes::StationBoardWithDetails] object.
+    def get_arr_dep_board_with_details(params)
+      request(
+        "http://thalesgroup.com/RTTI/2015-05-14/ldb/GetArrDepBoardWithDetails",
+        Request::GetStationBoardWithDetails.new(params)
+      )
+    end
+
+    # Retrieves the next departures from one station to one or many others.
+    #
+    # Parameters are validated using GetDeparturesBoard[rdoc-ref:Request::GetDeparturesBoard], returns a
+    # DeparturesBoard[rdoc-ref:ResponseTypes::DeparturesBoard] object.
+    def get_next_departures(params)
+      request(
+        "http://thalesgroup.com/RTTI/2015-05-14/ldb/GetNextDepartures",
+        Request::GetDeparturesBoard.new(params)
+      )
+    end
+
+    # Retrieves the fastest departures from one station to one or many others.
+    #
+    # Parameters are validated using GetDeparturesBoard[rdoc-ref:Request::GetDeparturesBoard], returns a
+    # DeparturesBoard[rdoc-ref:ResponseTypes::DeparturesBoard] object.
+    def get_next_departures(params)
+      request(
+        "http://thalesgroup.com/RTTI/2015-05-14/ldb/GetFastestDepartures",
+        Request::GetDeparturesBoard.new(params)
+      )
+    end
+
+    # Retrieves detailed information about the next departures from one station to one or many others.
+    #
+    # Parameters are validated using GetDeparturesBoardWithDetails[rdoc-ref:Request::GetDeparturesBoardWithDetails],
+    # returns a DeparturesBoardWithDetails[rdoc-ref:ResponseTypes::DeparturesBoardWithDetails] object.
+    def get_next_departures_with_details(params)
+      request(
+        "http://thalesgroup.com/RTTI/2015-05-14/ldb/GetNextDeparturesWithDetails",
+        Request::GetDeparturesBoardWithDetails.new(params)
+      )
+    end
+
+    # Retrieves detailed information about the fastest departures from one station to one or many others.
+    #
+    # Parameters are validated using GetDeparturesBoardWithDetails[rdoc-ref:Request::GetDeparturesBoardWithDetails],
+    # returns a DeparturesBoardWithDetails[rdoc-ref:ResponseTypes::DeparturesBoardWithDetails] object.
+    def get_fastest_departures_with_details(params)
+      request(
+        "http://thalesgroup.com/RTTI/2015-05-14/ldb/GetFastestDeparturesWithDetails",
+        Request::GetDeparturesBoardWithDetails.new(params)
+      )
+    end
+
+    # Retrieves information about a specific service.
+    #
+    # Parameters are validated using GetServiceDetails[rdoc-ref:Request::GetServiceDetails], returns a
+    # ServiceDetails[rdoc-ref:ResponseTypes::ServiceDetails] object.
+    def get_service_details(params)
+      request(
+        "http://thalesgroup.com/RTTI/2012-01-13/ldb/GetServiceDetails",
+        Request::GetServiceDetails.new(params)
+      )
+    end
+
+    alias_method :get_departure_board_with_details, :get_dep_board_with_details
+    alias_method :get_arrival_board_with_details, :get_arr_board_with_details
+    alias_method :get_arrival_departure_board_with_details, :get_arr_dep_board_with_details
+
+    private
+
+    def request(soap_action, request)
+      root_node = soap_action.split("/").last
+      soap_in = create_soap_request(request, root_node)
+
+      # Fire it off
+      soap_response = perform_soap_request(soap_action, soap_in)
+
+      # Parse
+      xml = Nokogiri::XML(soap_response)
+      xml.remove_namespaces!
+
+      response_node = xml.xpath("//#{root_node}Response").first
+      raise "Oh no" unless response_node
+
+      request.from_soap(response_node)
+    end
+
+    def create_soap_request(request, root_node)
+      Nokogiri::XML::Builder.new do |xml|
+        xml.Envelope(xmlns: "http://schemas.xmlsoap.org/soap/envelope/") {
+          xml.Header {
+            xml.AccessToken(xmlns: "http://thalesgroup.com/RTTI/2013-11-28/Token/types") {
+              xml.TokenValue @token
+            }
+          }
+          xml.Body {
+            xml.send("#{root_node}Request", xmlns: "http://thalesgroup.com/RTTI/2021-11-01/ldb/") {
+              request.to_soap(xml)
+            }
+          }
+        }
+      end.to_xml
+    end
+
+    def perform_soap_request(action, body)
+      uri = URI(SERVICE_URI)
+
+      conn = Faraday.new(
+        url: "#{uri.scheme}://#{uri.host}",
+        headers: {
+          'Content-Type': "text/xml",
+          'SOAPAction': action,
+        },
+      )
+
+      conn.post(uri.path, body).body
+    end
+  end
+end

data/lib/ldbws/utils.rb

@@ -0,0 +1,60 @@
+# Utility functions for use within the library.
+module Ldbws
+  module Utils # :nodoc: all
+    # Upcases the first letter of the passed string.
+    #
+    # === Parameters
+    # str:: the input string
+    def self.ucfirst(str)
+      str[0].upcase + str[1..]
+    end
+
+    # Converts the passed string from CamelCase to snake_case
+    #
+    # === Parameters
+    # str:: the input string
+    # ucfirst:: [Boolean] whether or not to call [#ucfirst] as well
+    def self.to_snake_case(str, ucfirst = false)
+      output = str.to_s.gsub(/_([a-z])/) { $1.upcase }
+
+      ucfirst ? ucfirst(output) : output
+    end
+
+    # Deep converts a passed object as a hash.
+    #
+    # === Parameters
+    # value:: the value to convert
+    def self.deep_hashify_value(value)
+      if value.nil?
+        nil
+      elsif value.is_a?(Array)
+        value.map { |v| deep_hashify_value(v) }
+      elsif value.respond_to?(:to_h)
+        value.to_h
+      else
+        value
+      end
+    end
+
+    # Deep-serialises a hash to XML using Nokogiri
+    #
+    # === Parameters
+    # xml:: the instance of Nokogiri to build within
+    # hsh:: the hash to serialise
+    def self.deep_to_soap(xml, hsh)
+      hsh.each do |key, value|
+        key = to_snake_case(key)
+
+        if value.is_a?(Hash)
+          xml.send(key) { deep_to_soap(xml, value) }
+        elsif value.is_a?(Array)
+          xml.send(key) {
+            value.each { |v| deep_to_soap(xml, v) }
+          }
+        else
+          xml.send(key, value)
+        end
+      end
+    end
+  end
+end

data/lib/ldbws/version.rb

@@ -0,0 +1,4 @@
+module Ldbws
+  # The current gem version.
+  VERSION = "1.0.0"
+end

data/lib/ldbws.rb

@@ -0,0 +1,13 @@
+require "ldbws/service"
+
+# Provides a Ruby abstraction around the UK’s Network Rail live departure board webservice (LDBWS). See
+# Service[rdoc-ref:Ldbws::Service] for more information.
+module Ldbws
+  # Helper method that returns an instance of [rdoc-ref:Service].
+  #
+  # === Parameters
+  # token:: the API token used to connect to the service
+  def self.service(token)
+    Service.new(token)
+  end
+end

data/spec/response_types/parsing_spec.rb

@@ -0,0 +1,46 @@
+require "spec_helper"
+
+describe Ldbws::ResponseTypes::Base do
+  def parse_xml(xmlstr)
+    Nokogiri::XML::DocumentFragment.parse(xmlstr).children.first
+  end
+
+  context "simple parsing" do
+    class Test < Ldbws::ResponseTypes::Base
+      property :foo, String
+      collection :bar, "value", String
+    end
+
+    it "parses correctly when all values are present" do
+      xml = parse_xml("<test><foo>Content of foo</foo><bar><value>Bar 1</value><value>Bar 2</value></bar></test>")
+      example = Test.from_xml(xml)
+
+      expect(example.foo).to eq("Content of foo")
+      expect(example.bar.length).to eq(2)
+      expect(example.bar.join(",")).to eq("Bar 1,Bar 2")
+    end
+
+    it "correctly handles empty collections" do
+      xml = parse_xml("<test><foo>Content of foo</foo><bar/></test>")
+      example = Test.from_xml(xml)
+
+      expect(example.foo).to eq("Content of foo")
+      expect(example.bar.length).to eq(0)
+    end
+
+    it "correctly handles missing collections" do
+      xml = parse_xml("<test><foo>Content of foo</foo></test>")
+      example = Test.from_xml(xml)
+
+      expect(example.foo).to eq("Content of foo")
+      expect(example.bar.length).to eq(0)
+    end
+
+    it "correctly handles empty nodes" do
+      xml = parse_xml("<test><foo/></test>")
+      example = Test.from_xml(xml)
+
+      expect(example.foo).to be_nil
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+lib = File.expand_path("../lib", __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require "ldbws"

metadata

@@ -0,0 +1,224 @@
+--- !ruby/object:Gem::Specification
+name: ldbws
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jon Pearse
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-04-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.14'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.5.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 6.5.0
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.11'
+- !ruby/object:Gem::Dependency
+  name: rufo
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.0
+description:
+email: hello@jonpearse.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".editorconfig"
+- ".envrc"
+- ".gitignore"
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- Makefile
+- README.md
+- doc/LICENSE.html
+- doc/Ldbws.html
+- doc/Ldbws/Request.html
+- doc/Ldbws/Request/GetDeparturesBoard.html
+- doc/Ldbws/Request/GetDeparturesBoardWithDetails.html
+- doc/Ldbws/Request/GetServiceDetails.html
+- doc/Ldbws/Request/GetStationBoard.html
+- doc/Ldbws/Request/GetStationBoardWithDetails.html
+- doc/Ldbws/ResponseTypes.html
+- doc/Ldbws/ResponseTypes/BaseStationBoard.html
+- doc/Ldbws/ResponseTypes/CallingPoint.html
+- doc/Ldbws/ResponseTypes/Coach.html
+- doc/Ldbws/ResponseTypes/DepartureItem.html
+- doc/Ldbws/ResponseTypes/DepartureItemWithDetails.html
+- doc/Ldbws/ResponseTypes/DeparturesBoard.html
+- doc/Ldbws/ResponseTypes/DeparturesBoardWithDetails.html
+- doc/Ldbws/ResponseTypes/Formation.html
+- doc/Ldbws/ResponseTypes/LoadingCategory.html
+- doc/Ldbws/ResponseTypes/Location.html
+- doc/Ldbws/ResponseTypes/ServiceDetails.html
+- doc/Ldbws/ResponseTypes/ServiceItem.html
+- doc/Ldbws/ResponseTypes/ServiceItemWithCallingPoints.html
+- doc/Ldbws/ResponseTypes/StationBoard.html
+- doc/Ldbws/ResponseTypes/StationBoardWithDetails.html
+- doc/Ldbws/ResponseTypes/ToiletAvailability.html
+- doc/Ldbws/Service.html
+- doc/README_md.html
+- doc/created.rid
+- doc/css/fonts.css
+- doc/css/rdoc.css
+- doc/fonts/Lato-Light.ttf
+- doc/fonts/Lato-LightItalic.ttf
+- doc/fonts/Lato-Regular.ttf
+- doc/fonts/Lato-RegularItalic.ttf
+- doc/fonts/SourceCodePro-Bold.ttf
+- doc/fonts/SourceCodePro-Regular.ttf
+- doc/images/add.png
+- doc/images/arrow_up.png
+- doc/images/brick.png
+- doc/images/brick_link.png
+- doc/images/bug.png
+- doc/images/bullet_black.png
+- doc/images/bullet_toggle_minus.png
+- doc/images/bullet_toggle_plus.png
+- doc/images/date.png
+- doc/images/delete.png
+- doc/images/find.png
+- doc/images/loadingAnimation.gif
+- doc/images/macFFBgHack.png
+- doc/images/package.png
+- doc/images/page_green.png
+- doc/images/page_white_text.png
+- doc/images/page_white_width.png
+- doc/images/plugin.png
+- doc/images/ruby.png
+- doc/images/tag_blue.png
+- doc/images/tag_green.png
+- doc/images/transparent.png
+- doc/images/wrench.png
+- doc/images/wrench_orange.png
+- doc/images/zoom.png
+- doc/index.html
+- doc/js/darkfish.js
+- doc/js/navigation.js
+- doc/js/navigation.js.gz
+- doc/js/search.js
+- doc/js/search_index.js
+- doc/js/search_index.js.gz
+- doc/js/searcher.js
+- doc/js/searcher.js.gz
+- doc/table_of_contents.html
+- ldbws.gemspec
+- lib/ldbws.rb
+- lib/ldbws/request/base.rb
+- lib/ldbws/request/get_departures_board.rb
+- lib/ldbws/request/get_service_details.rb
+- lib/ldbws/request/get_station_board.rb
+- lib/ldbws/response_types/base.rb
+- lib/ldbws/response_types/calling_point.rb
+- lib/ldbws/response_types/departures_board.rb
+- lib/ldbws/response_types/formation.rb
+- lib/ldbws/response_types/parsing_functions.rb
+- lib/ldbws/response_types/service_details.rb
+- lib/ldbws/response_types/service_item.rb
+- lib/ldbws/response_types/station_board.rb
+- lib/ldbws/service.rb
+- lib/ldbws/utils.rb
+- lib/ldbws/version.rb
+- spec/response_types/parsing_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/jonpearse/ldbws-ruby
+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: []
+rubygems_version: 3.4.6
+signing_key:
+specification_version: 4
+summary: Interface to the Network Rail OpenLDBS web service
+test_files: []