sping 1.0.4 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f7679b3fb31d07d034182114e576f3e272ef8223954f592bb30a98378b98fd5
-  data.tar.gz: b8d21d6a58ffb3c57481cc421d61f8fc25da32646fb8d5ae160829017d01fb14
+  metadata.gz: 6dda8939b3290683a544ac5ba7192ca3ceab50489b3dbd62a0dd04696f6a7786
+  data.tar.gz: de774cc1260933cdcd386e39cfd040e0af8510ba9e73e30f615e2f8da27c074f
 SHA512:
-  metadata.gz: a6a2c6897ead8f7371b2f1a83719c1a8f2c07d44957a9c302bc548855d25671858435fe0d6e8162e14737e065f6bbcede37defd2ea21e23561d19e7f8d5ef63f
-  data.tar.gz: 2618e70abea52acc38364f7fb431dafa12a4d48ad8f07665f93ac76e316784e6a2f8f5d2b463a55053da88b10f46dc23adf16846abb1a4b1d4677eb9eef09e7f
+  metadata.gz: e100242edcfe0e85965c6520dc9e95bdcab2c1aea58e5df338eb1dba9efb2dca1b6de0c453a333aa83553b9187d62b731f6fbd4dd81510ee600572b7f0d8e3a5
+  data.tar.gz: 0d01578a50563b1e7f1de1219423e00f66ecffec49ccf25b74e0052df858dc317c71bea80dcec2e17762d66b4b7b97322d8a389484dc72ae158157de605098b0

data/README.md

@@ -1,3 +1,18 @@
 # 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.
+
+## Protocol
+
+The protocol consists of three phases:
+1. A TCP handshake
+2. A UDP handshake
+2. Sending the pings
+
+The TCP handshake is performed first. Here the peers negotiate a session ID. To do this, the client sends a request to the server and then invites it to a session. If the server accepts the invitation, it sends a session ID to the client. This is used to uniquely identify the connection between the peers. For example, a peer may change its port or IP address. The session ID is used so that the peers can continue to identify each other. The session is activated at the end of the TCP handshake.
+
+A UDP handshake is then performed. In this, the client sends a UDP packet, which is encoded with [MessagePack](https://msgpack.org/), to the server. The server sends the packet back to the client for confirmation. One of the purposes of this is to punch a hole in a firewall so that it allows UDP packets between the peers. After a successful UDP handshake, the session is double activated. Only then does the sending of ping packets begin.
+
+Finally, the peers send pings to each other (in this case UDP packets containing time messages). These time messages contain, among other things, the time at which the message was sent, but also the last 32 time messages received from the peer. This information can be used to determine both the asymmetric latency and the asymmetric packet loss.

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,122 @@
 # 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 0 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
+      @double_activated = nil
+
       @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
+      unless invite.chomp == 'INVITE'
+        socket.write "I_DONT_UNDERSTAND\r\n"
+        raise TCPHandshakeError, 'Peer didn\'t invite us.'
+      end
 
-      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 +130,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
 
-    def start_udp_handshake_sender(send_interval = 5)
+    # 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 = 1)
       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 +152,7 @@ module SPing
       end
     end
 
+    # Send a single UDP handshake
     def send_udp_handshake
       packet = {
         'Y' => 'h'.ord,
@@ -104,6 +165,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 +173,14 @@ 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
+      @double_activated = Time.now
     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 +192,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 +200,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 +217,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
@@ -211,11 +283,17 @@ module SPing
       rx_loss = 0
       exchanges = 0
 
-      if remote_last_acks.length == 32
+      last_local_acks = @last_acks.acks
+
+      # A calculation can only take place when enough data is available, i.e. when:
+      # - We have sent 32 time messages (this is the case after 32 seconds)
+      # - The peer has sent 32 time messages (this is the case after 32 seconds)
+      # - If there is a time message (this is the case when we are in this function)
+      if @double_activated && (Time.now - @double_activated).to_i > 32
         # We have enough data
         exchanges = 32
         remote_acks = remote_last_acks.map { |ack| ack['R'] }
-        local_acks = @last_acks.acks.map { |ack| ack['R'] }
+        local_acks = last_local_acks.map { |ack| ack['R'] }
 
         tip_id = (Time.now.to_i % 255) + 1
         starting = tip_id - 32

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.1
 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: []