rsmp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 250eabe3e6427dd2032d46756055c93175383c5a32c5ca13d56a9b237bd9d033
+  data.tar.gz: 34d1ce845bbb2029b1bb00165d66c4e1181c8479ab99953b4d1687d51180d50c
+SHA512:
+  metadata.gz: a12e73c1c5a98c557cb733ce2ed1251ece7ade05763fb3f657846d12120413b020aa3a716b48d3c76aa4a913898732b0f87add636a790052390777d54308ed14
+  data.tar.gz: 449d24617bc74cafab1f314fba2297fcb17fcfba74743c69a2720ba9ca9297e3d61798be49d4303c0294b5215262382b8eb570d91f04e1318e570094739b7455

data/.gitignore

@@ -0,0 +1,15 @@
+ignore
+.DS_Store
+.rspec_status
+
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/lib/rsmp_schema/
+
+

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "rsmp_schema"]
+	path = lib/rsmp_schema
+	url = git@github.com:rsmp-nordic/rsmp_schema.git

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Changelog
+
+## 0.1.0
+Initial release.

data/Gemfile

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

data/Gemfile.lock

@@ -0,0 +1,101 @@
+PATH
+  remote: .
+  specs:
+    rsmp (0.1.0)
+      async (~> 1.23.0)
+      async-io (~> 1.27.0)
+      colorize (~> 0.8.1)
+      json_schemer (~> 0.2.8)
+      thor (~> 0.20.3)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    aruba (0.14.11)
+      childprocess (>= 0.6.3, < 3.0.0)
+      contracts (~> 0.9)
+      cucumber (>= 1.3.19)
+      ffi (~> 1.9)
+      rspec-expectations (>= 2.99)
+      thor (~> 0.19)
+    async (1.23.0)
+      console (~> 1.0)
+      nio4r (~> 2.3)
+      timers (~> 4.1)
+    async-io (1.27.0)
+      async (~> 1.14)
+    backports (3.15.0)
+    builder (3.2.3)
+    childprocess (2.0.0)
+      rake (< 13.0)
+    colorize (0.8.1)
+    console (1.5.0)
+    contracts (0.16.0)
+    cucumber (3.1.2)
+      builder (>= 2.1.2)
+      cucumber-core (~> 3.2.0)
+      cucumber-expressions (~> 6.0.1)
+      cucumber-wire (~> 0.0.1)
+      diff-lcs (~> 1.3)
+      gherkin (~> 5.1.0)
+      multi_json (>= 1.7.5, < 2.0)
+      multi_test (>= 0.1.2)
+    cucumber-core (3.2.1)
+      backports (>= 3.8.0)
+      cucumber-tag_expressions (~> 1.1.0)
+      gherkin (~> 5.0)
+    cucumber-expressions (6.0.1)
+    cucumber-tag_expressions (1.1.1)
+    cucumber-wire (0.0.1)
+    diff-lcs (1.3)
+    ecma-re-validator (0.2.0)
+      regexp_parser (~> 1.2)
+    ffi (1.11.1)
+    gherkin (5.1.0)
+    hana (1.3.5)
+    json_schemer (0.2.8)
+      ecma-re-validator (~> 0.2)
+      hana (~> 1.3)
+      regexp_parser (~> 1.5)
+      uri_template (~> 0.7)
+    multi_json (1.13.1)
+    multi_test (0.1.2)
+    nio4r (2.5.2)
+    rake (10.5.0)
+    regexp_parser (1.6.0)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.2)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.4)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.2)
+    rspec-with_params (0.2.0)
+      rspec (~> 3.0)
+    thor (0.20.3)
+    timecop (0.9.1)
+    timers (4.3.0)
+    uri_template (0.7.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  aruba (~> 0.14.11)
+  bundler (~> 2.0)
+  cucumber (~> 3.1.2)
+  rake (~> 10.0)
+  rsmp!
+  rspec (~> 3.0)
+  rspec-expectations (~> 3.8.3)
+  rspec-with_params (~> 0.2.0)
+  timecop (~> 0.9.1)
+
+BUNDLED WITH
+   2.1.0.pre.2

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2019 The City Copenhagen
+
+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,204 @@
+# rsmp
+This is a Ruby implementation of the RSMP protocol, including:
+ - RSMP classes that can be used to build tests or other RSMP tools
+ - Command-line tools for quickly running RSMP supervisors or sites and view messages exchanged
+
+## Installation
+You need a recent version of Ruby intalled. 2.6.3 or later is recommended.
+
+Install required gems:
+
+```console
+$ gem install bundler
+$ bundle
+```
+
+Install git submodules:
+The JSON Schema is is included as a git submodule. To install it:
+
+```console
+$ git submodule init     # initialize local submodule config
+$ git submodule update   # fetch submodules
+```
+
+Alternatively, you can pass --recurse-submodules to the git clone command, and it will automatically initialize and update each submodule in the repository.
+
+## Usage 
+### Site and Supervisor
+The RSMP::Site and RSMP::Supervisor classes can be used to run a RSMP site.
+
+```ruby
+require 'rsmp'
+RSMP::Site.new.start 		# run site until Ctlr-C is pressed
+```
+
+```ruby
+require 'rsmp'
+RSMP::Supervisor.new.start  		# run supervisor until Ctlr-C is pressed
+```
+
+Be default, a site will try to connect to a single supervisor on localhost 127.0.0.1, port 12111. By default, a supervisor will listen for sites on port 12111 and accept any site.
+
+You can pass options to control ip adresseses, ports, logging and other behaviour:
+
+```ruby
+require 'rsmp'
+settings = {
+  'site_id' => 'RN+SI0001',			# site id
+  'supervisors' => [						# list of supervisor to connect to
+    { 'ip' => '127.0.0.1', 'port' => 12111 }		# ip and port
+  ],
+  'log' => {
+    'json' => true,		# show raw json messages in log
+  }
+}
+RSMP::Site.new(site_settings:settings)
+```
+
+See lib/rsmp/site.rb and lib/rsmp/supervisor.rb for a list of settings and their default values.
+
+### Concurrency
+The [async](https://github.com/socketry/async) and [async-io](https://github.com/socketry/async-io) gems are used to handle concurrency. Everything happens in a single thread, but fibers are used to switch between tasks whenever an IO operation blocks.
+
+If you start a site or a supervisor inside an Async block, it will run concurrently:
+
+```ruby
+require 'rsmp'
+settings = {
+  'log' => { 'active' => false }    # disable log output
+}
+Async do |task|
+  site = RSMP::Site.new(site_settings:settings)
+  site.start 					# run concurrently since we're inside an Async block
+  loop do
+    task.sleep 1			# use task.sleep() instead of sleep() to avoid blocking
+    puts "Latest archive item: #{site.archive.items.last}"
+  end
+end
+```
+
+Use task.show_hierarchy to see what task are created, task.stop() to stop all sites and supervisors running inside it:
+
+```ruby
+require 'rsmp'
+Async do |task|
+  RSMP::Site.new.start
+  task.sleep 1
+  task.print_hierarchy
+  task.stop     # stop everything inside this Async block
+end
+puts "Bye!"
+```
+
+RSMP::Site and RSMP::Supervisor is not Async task themselves, but each contain a ```task``` attribute containing an async task used to run network and timers. A supervisor contains a single task listening for connections from sites. A site contain a task for each supervisor that it connects to.
+
+See the async documentation for more information about working with task and concurrency.
+
+### Archive and Logging
+Sites and supervisor can log message and events, and will store them in an archive.
+
+RSMP::Archive stores messages. RSMP::Logger filters and formats messages according to log settings.
+
+By default, sites and supervisor will create a new archive when initialized, but you can pass in an exsiting archive, which is useful in case you want several sites/supervisors to use the same archive:
+
+```ruby
+require 'rsmp'
+
+# create common archive and logger
+logger = RSMP::Logger.new('timestamp'=>false,'author'=>true)
+archive = RSMP::Archive.new
+
+# run supervisor and site for 0.1 second, then stop them
+Async do |task|
+  RSMP::Supervisor.new(archive:archive,logger:logger).start
+  RSMP::Site.new(archive:archive,logger:logger).start
+  task.sleep 0.1
+  task.stop
+end
+
+# show archiuve content
+logger.dump archive, force:true
+```
+
+This will output messages form both the site and the supervisor, ordered chronologically:
+
+```console
+RN+SU0001                              Starting supervisor RN+SU0001 on port 12111
+RN+SI0001                              Starting site RN+SI0001
+RN+SI0001                              Connecting to superviser at 127.0.0.1:12111
+RN+SI0001                   <--  f8c7  Sent Version
+RN+SU0001                              Site connected from 127.0.0.1:53500
+RN+SU0001     RN+SI0001     -->  f8c7  Received Version message for sites [RN+SI0001] using RSMP 3.1.4
+...
+```
+
+### JSON Schema validation
+All messages sent and received will be validated against the core [RSMP JSON Schema](https://github.com/rsmp-nordic/rsmp_schema).
+
+## Command-line tool
+Tools for easily running RSMP supervisors and sites. The binary is called ```rsmp```.
+
+The ```supervisor``` command will start an RSMP supervisor, which sites can connect to:
+
+```console
+% rsmp supervisor
+2019-11-11 12:21:55 UTC                            Starting supervisor RN+SU0001 on port 12111
+2019-11-11 12:22:00 UTC                            Site connected from 127.0.0.1:50098
+2019-11-11 12:22:00 UTC  RN+SI0001      -->  792f  Received Version message for sites [RN+SI0001] using RSMP 3.1.4
+2019-11-11 12:22:00 UTC  RN+SI0001      <--  e70e  Sent Version
+2019-11-11 12:22:00 UTC  RN+SI0001                 Connection to site RN+SI0001 established
+2019-11-11 12:22:00 UTC  RN+SI0001                 Adding component C1 to site RN+SI0001
+2019-11-11 12:22:00 UTC  RN+SI0001  C1  -->  8280  Received AggregatedStatus status for component C1 []
+```
+
+The ```site``` command will start an RSMP site, which will try to connect to one or more supervisor. Here's an example of the site connecting to a Ruby supervisor:
+
+```console
+% rsmp site
+2019-11-11 12:22:00 UTC                            Starting site RN+SI0001
+2019-11-11 12:22:00 UTC                            Connecting to superviser at 127.0.0.1:12111
+2019-11-11 12:22:00 UTC                 <--  792f  Sent Version
+2019-11-11 12:22:00 UTC  RN+SU0001      -->  e70e  Received Version message, using RSMP 3.1.4
+2019-11-11 12:22:00 UTC  RN+SU0001                 Connection to supervisor established
+2019-11-11 12:22:00 UTC  RN+SU0001  C1  <--  8280  Sent AggregatedStatus
+```
+
+### CLI help and options.
+Use ```--help <command>``` to get a list of available options.
+
+Use ```--config <path>``` to point to a .yaml config file, controlling things like IP adresses, ports, and log output. Examples of config files can be found the folder ```config/```. 
+
+## Tests
+### RSpec
+RSpec tests are located in spec/. The tests will start supervisor and sites to test communication, but will do so on port 13111, rather than the usual port 12111, to avoid inferference with other RMSP processes running locally.
+
+Note that these tests are NOT intented for testing external equipment or systems. The tests are for validating the code in this repository. To test external equipment or systems.
+
+```console
+$ rspec
+.........................
+
+Finished in 0.12746 seconds (files took 0.6571 seconds to load)
+25 examples, 0 failures
+
+```
+
+# Cucumber
+Cucumber is used to test the CLI binaries.
+
+```console
+$ cucumber
+Feature: Help
+
+  Scenario: Displaying help              # features/help.feature:3
+    When I run `rsmp help`               # aruba-0.14.11/lib/aruba/cucumber/command.rb:6
+    Then it should pass with "Commands:" # aruba-0.14.11/lib/aruba/cucumber/command.rb:271
+
+Feature: Run site
+...
+
+7 scenarios (7 passed)
+28 steps (28 passed)
+0m7.036s
+```
+

data/Rakefile

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

data/bin/console

@@ -0,0 +1,51 @@
+#!/usr/bin/env ruby
+
+# Make IRB run inside Async, so async task
+# will run the the background. 
+
+require 'bundler/setup'
+require 'irb'
+require 'rsmp'
+#require 'async/io/protocol/line'
+
+module IRB
+
+  # custom input class which reads from an async stream
+  class MyInputMethod < StdioInputMethod
+    def initialize
+      super
+      @input = Async::IO::Protocol::Line.new(
+        Async::IO::Stream.new(
+          Async::IO::Generic.new($stdin)
+        )
+      )
+    end
+
+    def gets
+      # since this is an async stream, the call to read_line()
+      # will give the Async reactor a chance to schedule other task
+      print @prompt
+      line = @input.read_line
+      @line[@line_no += 1] = "#{line}\n"
+    end
+  end
+
+  def self.start(ap_path = nil)
+    STDOUT.sync = true
+    $0 = File::basename(ap_path, ".rb") if ap_path
+
+    IRB.setup(ap_path)
+
+    if @CONF[:SCRIPT]
+      irb = Irb.new(nil, @CONF[:SCRIPT])
+    else
+      irb = Irb.new(nil,MyInputMethod.new)
+    end
+
+    irb.run(@CONF)
+  end
+end
+
+Async do
+  IRB.start(__FILE__)
+end

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/config/site.yaml

@@ -0,0 +1,41 @@
+site_id: RN+SI0001
+supervisors:
+  - ip: 127.0.0.1
+    port: 12111
+
+sxl: traffic_light_controller
+
+rsmp_versions:
+  - 3.1.1
+  - 3.1.2
+  - 3.1.3
+  - 3.1.4
+
+components:
+  A1:
+    type: main
+
+watchdog_interval: 1
+watchdog_timeout: 2
+acknowledgement_timeout: 2
+store_messages: false
+command_response_timeout: 1
+status_response_timeout: 1
+status_update_timeout: 1
+reconnect_interval: 0.1
+
+log:
+  active: true
+  color: true
+  timestamp: true
+  id: true
+  component: true
+  ip: false
+  site_id: true
+  level: false
+  text: true
+  direction: true
+  json: true
+  acknowledgements: false
+  watchdogs: false
+

data/config/supervisor.yaml

@@ -0,0 +1,33 @@
+site_id: RN+SU0001
+port: 12111
+rsmp_versions:
+  - 3.1.4
+
+watchdog_interval: 1
+watchdog_timeout: 2
+acknowledgement_timeout: 2
+store_messages: false
+command_response_timeout: 1
+status_response_timeout: 1
+status_update_timeout: 1
+
+sites:
+  AA+BBCCC=DDD:    # rsmp simulator
+    sxl: core
+  RN+SI0001:       # ruby rsmp site
+
+log:
+  active: true
+  color: true
+  timestamp: true
+  id: true
+  component: true
+  ip: false
+  site_id: true
+  text: true
+  direction: true
+  level: false
+  json: true
+  acknowledgements: true
+  watchdogs: true
+

data/exe/rsmp

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require 'bundler/setup'
+require 'rsmp/cli'
+RSMP::CLI.start

data/lib/rsmp/alarm.rb

@@ -0,0 +1,15 @@
+# RSMP Alarm. Manages the various states an alarm can be in.
+
+module RSMP
+  class Alarm
+
+    def initialize code: code, blocked: blocked=false, suspended: suspended=false, acknowledged: acknowledged=false
+      @code = code
+      @code = code
+      @blocked = blocked
+      @suspended = suspended
+      @acknowledged = acknowledged
+    end
+
+  end
+end

data/lib/rsmp/archive.rb

@@ -0,0 +1,75 @@
+# Archive of log items, which can be messages or info items.
+# All items are timestamped, and stored chronologically.
+
+module RSMP
+  class Archive
+    attr_reader :items
+    attr_accessor :probes
+
+    def initialize
+      @items = []
+      @probes = ProbeCollection.new
+    end
+
+    def self.prepare_item item
+      raise ArgumentError unless item.is_a? Hash
+    
+      now_obj = RSMP.now_object
+      now_str = RSMP.now_string(now_obj)
+
+      cleaned = item.select { |k,v| [:author,:level,:ip,:port,:site_id,:component_id,:str,:message,:exception].include? k }
+      cleaned[:timestamp] = now_obj
+      if item[:message]
+        cleaned[:direction] = item[:message].direction 
+        cleaned[:component_id] = item[:message].attributes['cId'] 
+      end
+
+      cleaned
+    end
+
+    def by_level levels
+      items.select { |item| levels.include? item[:level] }
+    end
+
+    def strings
+      items.map { |item| item[:str] }
+    end
+
+    def current_index
+      @items.size
+    end
+
+    def add item
+      item[:index] = @items.size
+      @items << item
+      probe item
+    end
+
+    def capture task, options, &block
+      probe = RSMP::Probe.new self
+      probe.capture task, options, &block
+    end
+    
+    private
+
+    def probe item
+      @probes.process item
+    end
+
+    def find options, &block
+      # search backwards from newest to older, stopping once messages
+      # are older that options[:earliest]
+      out = []
+      @items.reverse_each do |item|
+        break if options[:earliest] && item[:timestamp] < options[:earliest]
+        next if options[:level] && item[:level] != options[:level]
+        next if options[:type] && (item[:message] == nil || (item[:message].type != options[:type]))
+        next if options[:with_message] && !(item[:direction] && item[:message])
+        next if block_given? && block.call != true
+        out.unshift item
+      end
+      out
+    end
+  end
+
+end

data/lib/rsmp/base.rb

@@ -0,0 +1,26 @@
+#
+# RSMP base class
+#
+
+module RSMP
+  class Base
+    attr_reader :archive, :logger
+
+    def initialize options
+      @archive = options[:archive] || RSMP::Archive.new
+      @logger = options[:logger] || RSMP::Logger.new(options[:log_settings]) 
+    end
+
+    def author
+    end
+
+    def log str, options={}
+      default = { level: :log, author: author }
+      prepared = RSMP::Archive.prepare_item default.merge(options.merge str: str)
+      @archive.add prepared
+      @logger.log prepared
+      prepared
+    end
+
+  end
+end

data/lib/rsmp/cli.rb

@@ -0,0 +1,52 @@
+require 'thor'
+require 'rsmp'
+
+module RSMP
+	class CLI < Thor
+
+		desc "site", "Run RSMP site"
+		method_option :config, :type => :string, :aliases => "-c", banner: 'Path to .yaml config file'
+		method_option :id, :type => :string, :aliases => "-i", banner: 'RSMP site id'
+		method_option :supervisors, :type => :string, :aliases => "-s", banner: 'ip:port,... list of supervisor to connect to'			
+		def site
+			converted = {
+					site_settings_path: options[:config],
+					site_settings: {
+						site_id: options[:id],
+					}
+			}
+			
+  		if options[:supervisors]
+	  		options[:supervisors].split(',').each do |supervisor|
+	  			converted[:site_settings][:supervisors] ||= []
+					ip, port = supervisor.split ':'
+					ip = '127.0.0.1' if ip.empty?
+					port = '12111' if port.empty?
+					converted[:site_settings][:supervisors] << {"ip"=>ip, "port"=>port}
+				end
+			end
+
+			converted[:site_settings].compact!
+			RSMP::Site.new(converted).start
+		end
+
+		desc "supervisor", "Run RSMP supervisor"
+		method_option :config, :type => :string, :aliases => "-c", banner: 'Path to .yaml config file'
+		method_option :id, :type => :string, :aliases => "-i", banner: 'RSMP site id'
+		method_option :ip, :type => :numeric, banner: 'IP address to listen on'			
+		method_option :port, :type => :string, :aliases => "-p", banner: 'Port to listen on'
+		def supervisor
+			converted = {
+					supervisor_settings_path: options[:config],
+					supervisor_settings: {
+						site_id: options[:id],
+						ip: options[:ip],
+						port: options[:port]
+					}
+			}
+			converted[:supervisor_settings].compact!
+			RSMP::Supervisor.new(converted).start
+		end
+
+	end
+end