sping 1.0.4 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f7679b3fb31d07d034182114e576f3e272ef8223954f592bb30a98378b98fd5
-  data.tar.gz: b8d21d6a58ffb3c57481cc421d61f8fc25da32646fb8d5ae160829017d01fb14
+  metadata.gz: 7dc97d43dd1c7805574269a6ebbe8113c49c431bdfa46783b8e43ebef14063a5
+  data.tar.gz: ffb03def610179c609ffd4046cd5a7da5659e73b83ae867a123a2fcf62309b72
 SHA512:
-  metadata.gz: a6a2c6897ead8f7371b2f1a83719c1a8f2c07d44957a9c302bc548855d25671858435fe0d6e8162e14737e065f6bbcede37defd2ea21e23561d19e7f8d5ef63f
-  data.tar.gz: 2618e70abea52acc38364f7fb431dafa12a4d48ad8f07665f93ac76e316784e6a2f8f5d2b463a55053da88b10f46dc23adf16846abb1a4b1d4677eb9eef09e7f
+  metadata.gz: 637dc51c01d6f89bb26a6175d3ac0f0a16921398db3244164efea4b1de457cd3ef1329f3b4ee6eed69a1a57961a6c0d64c31fab7f4fb1fed150183212d830b96
+  data.tar.gz: 5bc1661058eb425277ed0d37429b5b0e8376690a6665aeb85e8bda35b96b85fd3a4025f0b4cc2020aef7b9e1f847b24845b6db9e841705749a7db3a20e4e9ee3

data/README.md

@@ -1,3 +1,5 @@
 # sping
 
-This is a reimplementation of [sping](https://github.com/benjojo/sping/) in Ruby.
+Program for measuring asymmetric latencies.
+
+This is a reimplementation in Ruby of the reference implementation of the sping protocol in Go. The program provides both the client and server part to measure asymmetric latencies between two peers.

data/lib/errors.rb

@@ -1,20 +1,44 @@
 # frozen_string_literal: true
 # sharable_constant_value: literal
 
+# SPing / Splitted Ping is a protocol for measuring asymmetric latencies.
 module SPing
+  # Generic SPing error.
   class SPingError < StandardError; end
 
+  # Error that occurred while managing the sessions.
   class SessionManagerError < SPingError; end
+
+  # Error that is thrown when there are not enough session IDs available to establish a
+  # connection to a peer or to accept new ones.
+  # This indicates either a programmer error or an overload of the server.
   class OutOfSessions < SessionManagerError; end
 
+  # Error that occurs in connection with a session.
   class SessionError < SPingError; end
+
+  # Error during the TCP handshake
   class TCPHandshakeError < SessionError; end
 
+  # Error due to the peer (i.e. not self-inflicted).
   class PeerError < SPingError; end
+
+  # Package was not coded correctly.
   class InvalidPacketError < PeerError; end
+
+  # The package was coded correctly, but the content is invalid.
   class InvalidMessageError < InvalidPacketError; end
+
+  # A packet has been received which cannot be clearly assigned to SPing
+  # and therefore cannot be processed further.
   class UnknownPacketError < InvalidPacketError; end
+
+  # The peer has signaled an error.
   class SignalizedError < PeerError; end
-  class UnknownVersionError < PeerError; end
+
+  # The peer uses a version of sping that is not supported.
+  class UnsupportedVersionError < PeerError; end
+
+  # The package could not be assigned to a current session.
   class UnknownSessionError < PeerError; end
 end

data/lib/last_acks.rb

@@ -1,16 +1,20 @@
 # frozen_string_literal: true
 # sharable_constant_value: literal
 
+# SPing / Splitted Ping is a protocol for measuring asymmetric latencies.
 module SPing
+  # A kind of circular buffer, which consists of 32 acks at any given time. If no acks are available,
+  # empty ones are created. If a new ack is added (which would result in 33 acks), one is removed.
   class LastAcks
-    attr_reader :size
-
-    def initialize(size = 32)
-      @size = size
+    # Creates a new circular buffer for acks
+    def initialize
+      # Array in which the acks are stored.
       @acks = []
+      # Mutex, which ensures that the array is not accessed simultaneously.
       @acks_mutex = Mutex.new
 
-      @size.times do |index|
+      # Initiallize the circular buffer with 32 empty acks.
+      32.times do |index|
         @acks[index] = {
           'R' => 0,
           'U' => Time.at(0),
@@ -19,17 +23,20 @@ module SPing
       end
     end
 
+    # Returns a copy of the last 32 acks.
+    # @return [Array] Last 32 Acks
     def acks
       @acks_mutex.synchronize do
         return @acks.dup
       end
     end
 
+    # Adds a new ack and deletes the oldest one
+    # @param ack [Hash] New ack to be added
     def add_ack(ack)
       @acks_mutex.synchronize do
         @acks << ack
-
-        @acks.shift if @acks.length > @size
+        @acks.shift
       end
     end
   end

data/lib/session.rb

@@ -1,68 +1,118 @@
 # frozen_string_literal: true
 # sharable_constant_value: literal
 
+# SPing / Splitted Ping is a protocol for measuring asymmetric latencies.
 module SPing
+  # Inclusion of all possible SPing-specific errors.
   require_relative 'errors'
 
+  # Models or represents a session with a peer.
   class Session
-    attr_reader :created, :last_rx, :madebyme
-    attr_accessor :session_id, :tcp_handshake_complete, :udp_handshake_complete
+    # Time when the session was created. This is necessary so that the session GC knows when a
+    # non-initialized session can be deleted.
+    # @return [Time]
+    attr_reader :created
+    # Time when the last ping packet was received by the peer. This is important so that the session
+    # GC knows when a session is considered inactive and can be deleted.
+    # @return [Time]
+    attr_reader :last_rx
+    # Indicates whether the session has been initialized. true if we have initiated it.
+    # false if the peer has initiated it.
+    # @return [TrueClass, FalseClass]
+    attr_reader :madebyme
+    # Indicates whether a TCP handshake has been carried out (successfully).
+    # @return [TrueClass, FalseClass]
+    attr_reader :tcp_handshake_complete
+    # Indicates whether a UDP handshake has been carried out (successfully).
+    # @return [TrueClass, FalseClass]
+    attr_reader :udp_handshake_complete
+    # The session ID in the range from 1 to 2**32 - 1.
+    # @return [Integer]
+    attr_reader :session_id
 
     require 'socket'
     require 'timeout'
     require 'msgpack'
     require_relative 'last_acks'
 
+    # Creates a new session
+    # @param host [#to_s] Host of the peer
+    # @param port [#to_i] Port of the peer
+    # @param socket [UDPSocket] UDP socket via which the pings and the UDP handshake are to be sent.
+    # @param madebyme [TrueClass, FalseClass] Indicates whether we have initiated the session.
     def initialize(host, port, socket, madebyme)
-      @host = host
-      @port = port
+      # Assign the passed parameters to instance variables.
+      @host = host.to_s
+      @port = port.to_i
       @socket = socket
-      @created = Time.now
       @madebyme = madebyme
 
+      # Initialize assignment of other instance variables
+      @created = Time.now
+
       @tcp_handshake_complete = false
       @udp_handshake_complete = false
 
       @last_acks = SPing::LastAcks.new
     end
 
+    # Initiates a TCP handshake.
+    # @param socket [TCPSocket] Socket via which the handshake is to be sent
+    #   (and responses are to be expected).
+    # @param session_id [Integer] Session ID which is to be sent to the peer
+    #   and which is to be used for the current session.
     def do_tcp_handshake1(socket, session_id)
+      # Send the banner
       socket.write "sping-0.3-https://codeberg.org/mark22k/sping\r\n"
+      # and make sure that it is no longer in the send buffer.
       socket.flush
 
+      # See if the peer invites us to create a session with them.
       invite = socket.readpartial 6
-
       raise TCPHandshakeError, 'Peer didn\'t invite us.' unless invite.chomp == 'INVITE'
 
+      # Send the session ID
       @session_id = session_id
-
       socket.write "#{session_id}\r\n"
+      # and make sure that it is no longer in the send buffer.
       socket.flush
 
+      # This means that the TCP handshake is successful. The socket can be closed
+      # and the corresponding instance variable can be set.
       socket.close
 
       @tcp_handshake_complete = true
     end
 
+    # Receives a TCP handshake from a peer.
+    # The peer specified when the session is created is consulted for this purpose.
     def do_tcp_handshake2
+      # Establish a connection and receive the banner.
       socket = TCPSocket.new @host, @port
+
+      # If the banner is too large, close the socket and throw an error.
+      # The handshake was not successful.
       banner = socket.readpartial 9001
       if banner.length > 9000
         socket.close
         raise TCPHandshakeError, 'Host banner too big'
       end
 
+      # If the banner does not match the SPing service, close the socket and
+      # throw an error. The handshake was not successful.
       unless banner.start_with? 'sping-0.3-'
         socket.close
-        raise TCPHandshakeError, 'Host banner not sping'
+        raise TCPHandshakeError, 'Host banner not sping or unsupported version of sping.'
       end
 
       @remote_version = banner.chomp
       $logger.info "Peer uses the following program version: #{@remote_version.dump}"
 
+      # Invite the peer to start a session with us.
       socket.write "INVITE\r\n"
       socket.flush
 
+      # If the session ID is too long or none was received, close the socket and throw an error.
       invite_buf = socket.readpartial 32
       if invite_buf.length > 31 || invite_buf.empty?
         socket.close
@@ -76,15 +126,21 @@ module SPing
       @tcp_handshake_complete = true
     end
 
+    # Sets the endpoint consisting of the host and port of the remote end. This is done
+    # each time a new packet is received and ensures that the current endpoint is always available.
+    # @param host [#to_s]
+    # @param port [#to_i]
     def set_endpoint(host, port)
-      @host = host
-      @port = port
+      @host = host.to_s
+      @port = port.to_i
     end
 
+    # Starts a thread which sends the UDP handshake at regular intervals.
+    # @param send_interval [#to_i] The interval at which the UDP handshakes are to be sent.
     def start_udp_handshake_sender(send_interval = 5)
       raise 'UDP handshake sender is already running.' if @udp_handshake_sender
 
-      @udp_handshake_sender = Thread.new(send_interval) do |th_send_interval|
+      @udp_handshake_sender = Thread.new(send_interval.to_i) do |th_send_interval|
         loop do
           send_udp_handshake
           sleep th_send_interval
@@ -92,6 +148,7 @@ module SPing
       end
     end
 
+    # Send a single UDP handshake
     def send_udp_handshake
       packet = {
         'Y' => 'h'.ord,
@@ -104,6 +161,7 @@ module SPing
       @socket.send packet, 0, @host, @port
     end
 
+    # Stop the UDP handshake sender. UDP handshakes are then no longer sent at any interval.
     def stop_udp_handshake_sender
       raise 'UDP handshake sender is not running and therefore cannot be terminated.' unless @udp_handshake_sender
 
@@ -111,11 +169,13 @@ module SPing
       @udp_handshake_sender = nil
     end
 
+    # Informs the session that a UDP handshake has been received.
     def udp_handshake_recived
       stop_udp_handshake_sender if @madebyme
       @udp_handshake_complete = true
     end
 
+    # Starts a thread which sends ping or time messages to the peer at one-second intervals.
     def start_pinger
       raise 'Pinger is already running.' if @pinger
 
@@ -127,6 +187,7 @@ module SPing
       end
     end
 
+    # Stops the thread, which sends ping or time messages to the peer at regular intervals.
     def stop_pinger
       raise 'Pinger sender is not running and therefore cannot be terminated.' unless @pinger
 
@@ -134,6 +195,7 @@ module SPing
       @pinger = nil
     end
 
+    # Sends a ping message to the peer.
     def ping
       current_id = (Time.now.to_i % 255) + 1
       data = {
@@ -150,11 +212,16 @@ module SPing
       @socket.send data, 0, @host, @port
     end
 
+    # Stops all threads associated with the session. This means that the session to the peer is as good as dead.
     def stop
       @pinger&.kill
       @udp_handshake_sender&.kill
     end
 
+    # Handler that receives and processes a receiving ping packet or time message. The current statistics are output.
+    # @param packet [Hash]
+    # @param rxtime [Time]
+    # @param peeraddr [#to_s]
     def handle_ping(packet, rxtime, peeraddr)
       if !(packet.keys - %w[M Y E I T A S]).empty? ||
          # M, Y are already checked in handle_packet from session manager

data/lib/session_manager.rb

@@ -1,17 +1,23 @@
 # frozen_string_literal: true
 # sharable_constant_value: literal
 
+# SPing / Splitted Ping is a protocol for measuring asymmetric latencies.
 module SPing
+  # Inclusion of all possible SPing-specific errors.
   require_relative 'errors'
 
+  # Container, which contains a collection of sessions and manages them.
   class SessionManager
     require 'socket'
     require 'timeout'
     require_relative 'session'
 
+    # Creates a new Session Manager, which can (and will) manage a number of sessions.
+    # @param host [#to_s] Host to which messages are to be bound and from which messages are sent accordingly.
+    # @param port [#to_i] Port
     def initialize(host = '::', port = 6924)
-      @host = host
-      @port = port
+      @host = host.to_s
+      @port = port.to_i
 
       @sessions = {}
       @sessions_mutex = Mutex.new
@@ -20,9 +26,12 @@ module SPing
       @socket.bind @host, @port
     end
 
+    # Initiates a new session with a peer.
+    # @param host [#to_s]
+    # @param port [#to_s, #to_i]
     def new_session(host, port = 6924)
       $logger.info "Add new session for host #{host} port #{port}."
-      session = SPing::Session.new host, port, @socket, true
+      session = SPing::Session.new host.to_s, port.to_i, @socket, true
 
       counter = 0
       loop do
@@ -48,6 +57,8 @@ module SPing
       $logger.error "Out of session: #{e.message}"
     end
 
+    # Stops all threads connected to a session ID and removes the session from the Session Manager administration.
+    # @param session_id [Integer] Session ID of the session to be removed.
     def del_session(session_id)
       $logger.debug "Delete session with session id #{session_id}"
 
@@ -57,18 +68,21 @@ module SPing
       end
     end
 
+    # Stops all sessions or the threads that are connected to them.
     def stop_sessions
       @sessions.each do |_session_id, session|
         session.stop
       end
     end
 
+    # Waits and blocks until the Session Manager is no longer running.
     def join
       @runner&.join
       @gc_thread&.join
       @server_thread&.join
     end
 
+    # Starts the Session Manager.
     def run
       raise 'Client is already running.' if @runner
       raise 'GC is already running.' if @gc
@@ -88,6 +102,7 @@ module SPing
       end
     end
 
+    # Starts the server functionality of the Session Manager.
     def run_server
       raise 'Server is already running.' if @server_thread
       raise 'Server already exist.' if @server
@@ -105,6 +120,7 @@ module SPing
       return @server_thread
     end
 
+    # Stops the server functionality of the Session Manager.
     def stop_server
       raise 'Server thread is not running.' unless @server_thread
 
@@ -117,6 +133,7 @@ module SPing
       @server = nil
     end
 
+    # Stops the Session Manager. The server functionality must be stopped separately.
     def stop
       raise 'Session manager is not running.' unless @runner
 
@@ -129,6 +146,12 @@ module SPing
       @gc_thread = nil
     end
 
+    private
+
+    # Generates a new session ID that was not yet in use at the time of the check.
+    # If none could be generated within half a minute - for example because all
+    # session IDs have already been assigned - an error is thrown.
+    # @return [Integer]
     def generate_session_id
       Timeout.timeout(30, OutOfSessions, 'No session ID could be generated which has not yet been used.') do
         loop do
@@ -138,19 +161,23 @@ module SPing
       end
     end
 
-    private
-
+    # Removes obsolete sessions. This includes sessions that are older than one minute but
+    # have not been activated a double time. And sessions that have not
+    # received any packets for half a minute.
     def do_gc
       $logger.debug 'Remove outdated sessions.'
       # rubocop:disable Style/HashEachMethods
-      # You cannot run through a map and edit it at the same time. Since this is necessary due to the threading,
+      # You cannot run through a map and edit it at the same time. Since this is
+      # necessary due to the threading,
       # a snapshot of the key variable is run through.
       @sessions.keys.each do |session_id|
         # rubocop:enable Style/HashEachMethods
 
         session = @sessions[session_id]
-        # It is possible that sessions no longer exist here, as we may have session IDs that have already been deleted.
-        # However, we can ignore this aspect here, as we are the only function that deletes sessions.
+        # It is possible that sessions no longer exist here, as we may have
+        # session IDs that have already been deleted.
+        # However, we can ignore this aspect here, as we are the only
+        # function that deletes sessions.
         if !(session.tcp_handshake_complete && session.udp_handshake_complete)
           # Handshake incomplete
           if (Time.now.to_i - session.created.to_i) > 60
@@ -159,13 +186,16 @@ module SPing
             del_session session_id
           end
         elsif (Time.now.to_i - session.last_rx.to_i) > 30
-          # 30 seconds have elapsed since the last ping from the peer was received. The peer is probably dead.
+          # 30 seconds have elapsed since the last ping from the peer was received.
+          # The peer is probably dead.
           $logger.debug "Session id #{session_id} without activity for over thirty seconds."
           del_session session_id
         end
       end
     end
 
+    # Receives a TCP handshake for a session and then has it
+    # managed by the Session Manager.
     def request_session(session)
       session.do_tcp_handshake2
 
@@ -179,6 +209,9 @@ module SPing
       return nil
     end
 
+    # Handler for a received packet. The function catches errors and outputs them.
+    # It also forwards the packet to the corresponding handler according to the
+    # session ID and type of packet.
     def handle_packet(buf)
       rxtime = Time.now
 
@@ -217,6 +250,7 @@ module SPing
       $logger.error "Perr error: #{e.message}"
     end
 
+    # Handler for a receiving UDP handshake.
     def handle_udp_handshake(packet, peeraddr, peerport)
       if !(packet.keys - %w[M Y V S]).empty? ||
          # M, Y are already checked in handle_packet from session manager
@@ -227,7 +261,7 @@ module SPing
       session_id = packet['S']
       session = @sessions[session_id]
       raise UnknownSessionError, 'UDP handshake received for uninitiated session.' unless session
-      raise UnknownVersionError, "UDP handshake uses an unsupported version: #{packet['V']}" if packet['V'] != 3
+      raise UnsupportedVersionError, "UDP handshake uses an unsupported version: #{packet['V']}" if packet['V'] != 3
 
       session.set_endpoint peeraddr, peerport
 
@@ -249,6 +283,7 @@ module SPing
       session.start_pinger
     end
 
+    # Handler for a receiving ping or a receiving time message.
     def handle_ping(packet, rxtime, peeraddr, peerport)
       session_id = packet['S']
       session = @sessions[session_id]
@@ -260,6 +295,7 @@ module SPing
       session.handle_ping packet, rxtime, peeraddr
     end
 
+    # Handler to establish a session for the request of a peer.
     def handle_client(client)
       host = client.peeraddr[3]
       port = client.peeraddr[1]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sping
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 1.1.0
 platform: ruby
 authors:
 - Marek Küthe
@@ -30,8 +30,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.7.2
-description: This is a reimplementation of [sping](https://github.com/benjojo/sping/)
-  in Ruby.
+description: This is a reimplementation in Ruby of the reference implementation of
+  the sping protocol in Go. The program provides both the client and server part to
+  measure asymmetric latencies between two peers.
 email: m.k@mk16.de
 executables:
 - sping
@@ -72,5 +73,5 @@ requirements: []
 rubygems_version: 3.4.22
 signing_key:
 specification_version: 4
-summary: Reimplementation of sping in Ruby.
+summary: Program for measuring asymmetric latencies.
 test_files: []