backport 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2aedfc84d845aedeb6d7146cb21a74c4d1d74d90844407982ce454e8aa2d16b3
-  data.tar.gz: e222830378478e7990601880b42e60dd4e34ba1791e63345a2a5fa0a2898bbf8
+  metadata.gz: 9693d9fb93dc1efb03c85d3abe258cd54e2fa4bca03e8bc2f64a45a56783269a
+  data.tar.gz: a7abdaa602ccbfda748cdace2af071af73651ecff42663ac237def501260f457
 SHA512:
-  metadata.gz: 5cd8632b158f0e5dda4e5377b5fc74a9e7ae416a738941dcf276cd48d8040c671eb9e337a089215e092ec499fecbadfaf6c015f49f09b72bc4cee556780afa4f
-  data.tar.gz: e52ea4e36b3bfbd397dabc9410d07af6106d1c7bc1e9dbac98d18a2def432300e64696ee3e277ad1e19639d61027ccb46d3a3f665603031ffab26c81d4f7ba83
+  metadata.gz: bbc92f9838a571f7cb9ea71334961cf34013a41e1010147ec4f54d4c5efde68c37b4f7cb9f0d9d52ad8ebe23ac9fa83e24568d690044ed200d838a1cb2c50358
+  data.tar.gz: a5cdf05eb09d40bc352fd07ed2d23b85107875551c9718e0145e7abdf92f670ff784e99b50b8daf5879c7a0cbe92dca1d8ca4b3a42ed73a482610085fd56e986

data/.gitignore

@@ -6,6 +6,9 @@
 /pkg/
 /spec/reports/
 /tmp/
+/.vscode/
 
 # rspec failure tracking
 .rspec_status
+
+Gemfile.lock

data/.rubocop.yml

@@ -0,0 +1,4 @@
+Style/MethodDefParentheses:
+  Enabled: false
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false

data/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 0.3.0 - January 10, 2019
+- Basic logging
+- Differentiate between "expected" and "unexpected" exceptions in Tcpip
+- Prefer #start to #run for non-blocking client/server methods
+- Interval servers can stop themselves
+
 ## 0.2.0 - December 21, 2018
 - Minor bug fixes in STDIO server
 - More efficient client reads

data/README.md

@@ -20,6 +20,8 @@ gem 'backport'
 
 ## Usage
 
+### Examples
+
 A simple echo server:
 
 ```ruby
@@ -27,11 +29,11 @@ require 'backport'
 
 module MyAdapter
   def opening
-    write "Opening the connection"
+    puts "Opening a connection"
   end
 
   def closing
-    write "Closing the connection"
+    puts "Closing a connection"
   end
 
   def sending data
@@ -55,3 +57,24 @@ Backport.run do
   end
 end
 ```
+
+### Using Adapters
+
+Backport servers that handle client connections, such as TCP servers, use an
+adapter to provide an application interface to the client. Developers can
+provide their own adapter implementations in two ways: a Ruby module that will
+be used to extend a Backport::Adapter object, or a class that extends
+Backport::Adapter. In either case, the adapter should provide the following
+methods:
+
+* `opening`: A callback triggered when the client connection is accepted
+* `closing`: A callback triggered when the client connection is closed
+* `sending(data)`: A callback triggered when the server receives data from the client
+
+Backport::Adapter also provides the following methods:
+
+* `write(data)`: Send raw data to the client
+* `write_line(data)`: Send a line of data to the client
+* `close`: Disconnect the client from the server
+* `closed?`: True if the connection is closed
+* `remote`: A hash of data about the client, e.g., the remote IP address

data/lib/backport.rb

@@ -1,66 +1,72 @@
-require "backport/version"
-require 'socket'
-
-module Backport
-  autoload :Adapter, 'backport/adapter'
-  autoload :Machine, 'backport/machine'
-  autoload :Server,  'backport/server'
-  autoload :Client,  'backport/client'
-
-  class << self
-    # Prepare a STDIO server to run in Backport.
-    #
-    # @param adapter [Adapter]
-    # @return [void]
-    def prepare_stdio_server adapter: Adapter
-      machine.prepare Backport::Server::Stdio.new(adapter: adapter)
-    end
-
-    # Prepare a TCP server to run in Backport.
-    #
-    # @param host [String]
-    # @param port [Integer]
-    # @param adapter [Adapter]
-    # @return [void]
-    def prepare_tcp_server host: 'localhost', port: 1117, adapter: Adapter
-      machine.prepare Backport::Server::Tcpip.new(host: host, port: port, adapter: adapter)
-    end
-
-    # Prepare an interval server to run in Backport.
-    #
-    # @param period [Float] Seconds between intervals
-    # @return [void]
-    def prepare_interval period, &block
-      machine.prepare Backport::Server::Interval.new(period, &block)
-    end
-
-    # Run the Backport machine. The provided block will be executed before the
-    # machine starts. Program execution is halted until the machine stops.
-    #
-    # @example Print "tick" once per second
-    #   Backport.run do
-    #     Backport.prepare_interval 1 do
-    #       puts "tick"
-    #     end
-    #   end
-    #
-    # @return [void]
-    def run &block
-      machine.run &block
-    end
-
-    # Stop the Backport machine.
-    #
-    # @return [void]
-    def stop
-      machine.stop
-    end
-
-    private
-
-    # @return [Machine]
-    def machine
-      @machine ||= Machine.new
-    end
-  end
-end
+require "backport/version"
+require 'logger'
+
+# An event-driven IO library.
+#
+module Backport
+  autoload :Adapter, 'backport/adapter'
+  autoload :Machine, 'backport/machine'
+  autoload :Server,  'backport/server'
+  autoload :Client,  'backport/client'
+
+  class << self
+    # Prepare a STDIO server to run in Backport.
+    #
+    # @param adapter [Adapter]
+    # @return [void]
+    def prepare_stdio_server adapter: Adapter
+      machine.prepare Backport::Server::Stdio.new(adapter: adapter)
+    end
+
+    # Prepare a TCP server to run in Backport.
+    #
+    # @param host [String]
+    # @param port [Integer]
+    # @param adapter [Adapter]
+    # @return [void]
+    def prepare_tcp_server host: 'localhost', port: 1117, adapter: Adapter
+      machine.prepare Backport::Server::Tcpip.new(host: host, port: port, adapter: adapter)
+    end
+
+    # Prepare an interval server to run in Backport.
+    #
+    # @param period [Float] Seconds between intervals
+    # @return [void]
+    def prepare_interval period, &block
+      machine.prepare Backport::Server::Interval.new(period, &block)
+    end
+
+    # Run the Backport machine. The provided block will be executed before the
+    # machine starts. Program execution is blocked until the machine stops.
+    #
+    # @example Print "tick" once per second
+    #   Backport.run do
+    #     Backport.prepare_interval 1 do
+    #       puts "tick"
+    #     end
+    #   end
+    #
+    # @return [void]
+    def run &block
+      machine.run &block
+    end
+
+    # Stop the Backport machine.
+    #
+    # @return [void]
+    def stop
+      machine.stop
+    end
+
+    def logger
+      @logger ||= Logger.new(STDERR, level: Logger::WARN, progname: 'Backport')
+    end
+
+    private
+
+    # @return [Machine]
+    def machine
+      @machine ||= Machine.new
+    end
+  end
+end

data/lib/backport/adapter.rb

@@ -1,17 +1,29 @@
 module Backport
+  # The application interface between Backport servers and clients.
+  #
   class Adapter
+    # @param output [IO]
+    # @param remote [Hash{Symbol => String, Integer}]
+    def initialize output, remote = {}
+      # Store internal data in a singleton method to avoid instance variable
+      # collisions in custom adapters
+      data = {
+        out: output,
+        remote: remote,
+        closed: false
+      }
+      define_singleton_method :_data do
+        data
+      end
+    end
+
     # A hash of information about the client connection. The data can vary
     # based on the transport, e.g., :hostname and :address for TCP connections
     # or :filename for file streams.
     #
     # @return [Hash{Symbol => String, Integer}]
-    attr_reader :remote
-
-    # @param output [IO]
-    # @param remote [Hash{Symbol => String, Integer}]
-    def initialize output, remote = {}
-      @out = output
-      @remote = remote
+    def remote
+      _data[:remote]
     end
 
     # A callback triggered when a client connection is opening. Subclasses
@@ -28,9 +40,9 @@ module Backport
     # @return [void]
     def closing; end
 
-    # A callback triggered when the client is sending data to the server.
-    # Subclasses and/or modules should override this method to provide their
-    # own functionality.
+    # A callback triggered when the client sends data to the server. Subclasses
+    # and/or modules should override this method to provide their own
+    # functionality.
     #
     # @param data [String]
     # @return [void]
@@ -41,8 +53,8 @@ module Backport
     # @param data [String]
     # @return [void]
     def write data
-      @out.write data
-      @out.flush
+      _data[:out].write data
+      _data[:out].flush
     end
 
     # Send a line of data to the client.
@@ -50,17 +62,23 @@ module Backport
     # @param data [String]
     # @return [void]
     def write_line data
-      @out.puts data
-      @out.flush
+      _data[:out].puts data
+      _data[:out].flush
     end
 
     def closed?
-      @closed ||= false
+      _data[:closed] ||= false
     end
 
+    # Close the client connection.
+    #
+    # @note The adapter sets #closed? to true and runs the #closing callback.
+    #   The server is responsible for implementation details like closing the
+    #   client's socket.
+    #
     def close
       return if closed?
-      @closed = true
+      _data[:closed] = true
       closing
     end
   end

data/lib/backport/client.rb

@@ -1,4 +1,6 @@
 module Backport
+  # A client connected to a connectable Backport server.
+  #
   class Client
     # @return [Adapter]
     attr_reader :adapter
@@ -15,23 +17,40 @@ module Backport
       @stopped ||= false
     end
 
+    # Close the client connection.
+    #
+    # @note The client sets #stopped? to true and runs the adapter's #closing
+    # callback. The server is responsible for implementation details like
+    # closing the client's socket.
+    #
     def stop
       return if stopped?
       @adapter.closing
       @stopped = true
     end
 
-    def run
+    # Start running the client. This method will start the thread that reads
+    # client input from IO.
+    #
+    def start
       return unless stopped?
       @stopped = false
       @adapter.opening
       run_input_thread
     end
+    # @deprecated Prefer #start to #run for non-blocking client/server methods
+    alias run start
 
+    # Notify the adapter that the client is sending data.
+    #
+    # @param data [String]
     def sending data
       @adapter.sending data
     end
 
+    # Read the client input. Return nil if the input buffer is empty.
+    #
+    # @return [String, nil]
     def read
       tmp = nil
       mutex.synchronize do

data/lib/backport/machine.rb

@@ -1,11 +1,13 @@
 module Backport
+  # The Backport server controller.
+  #
   class Machine
     def initialize
       @stopped = true
     end
 
     # Run the machine. If a block is provided, it gets executed before the
-    # maching starts its main loop. The main loop halts program execution
+    # maching starts its main loop. The main loop blocks program execution
     # until the machine is stopped.
     #
     # @return [void]
@@ -43,17 +45,23 @@ module Backport
       server.start unless stopped?
     end
 
-    private
-
     # @return [Array<Server::Base>]
     def servers
       @servers ||= []
     end
 
+    def tick
+      servers.delete_if(&:stopped?)
+      stop if servers.empty?
+      servers.each(&:tick)
+    end
+
+    private
+
     def run_server_thread
       servers.map(&:start)
       until stopped?
-        servers.each(&:tick)
+        tick
         sleep 0.001
       end
     end

data/lib/backport/server.rb

@@ -1,4 +1,6 @@
 module Backport
+  # Classes and modules for Backport servers.
+  #
   module Server
     autoload :Base,        'backport/server/base'
     autoload :Connectable, 'backport/server/connectable'

data/lib/backport/server/base.rb

@@ -1,16 +1,33 @@
 module Backport
   module Server
+    # An extendable server class that provides basic start/stop functionality
+    # and common callbacks.
+    #
     class Base
-      def started?
-        @started ||= false
-        @started
+      # Start the server.
+      #
+      def start
+        return if started?
+        starting
+        @started = true
       end
 
+      # Stop the server.
+      #
       def stop
+        return if stopped?
         stopping
         @started = false
       end
 
+      def started?
+        @started ||= false
+      end
+
+      def stopped?
+        !started?
+      end
+
       # A callback triggered when a Machine starts running or the server is
       # added to a running machine. Subclasses should override this method to
       # provide their own functionality.
@@ -30,11 +47,6 @@ module Backport
       #
       # @return [void]
       def tick; end
-
-      def start
-        starting
-        @started = true
-      end
     end
   end
 end

data/lib/backport/server/connectable.rb

@@ -1,5 +1,9 @@
 module Backport
   module Server
+    # A mixin for Backport servers that communicate with clients.
+    #
+    # Connectable servers check clients for incoming data on each tick.
+    #
     module Connectable
       def tick
         clients.each do |client|
@@ -16,6 +20,7 @@ module Backport
         clients.map(&:stop)
       end
 
+      # @return [Array<Client>]
       def clients
         @clients ||= []
       end

data/lib/backport/server/interval.rb

@@ -1,16 +1,25 @@
 module Backport
   module Server
+    # A Backport periodical interval server.
+    #
     class Interval < Base
+      # @param period [Float] The interval time in seconds.
+      # @param block [Proc] The proc to run on each interval.
+      # @yieldparam [Interval]
       def initialize period, &block
         @period = period
         @block = block
         @last_time = Time.now
       end
 
+      def starting
+        @last_time = Time.now
+      end
+
       def tick
         now = Time.now
-        return unless now - @last_time > @period
-        @block.call
+        return unless now - @last_time >= @period
+        @block.call self
         @last_time = now
       end
     end

data/lib/backport/server/stdio.rb

@@ -1,5 +1,7 @@
 module Backport
   module Server
+    # A Backport STDIO server.
+    #
     class Stdio < Base
       include Connectable
 

data/lib/backport/server/tcpip.rb

@@ -2,11 +2,14 @@ require 'socket'
 
 module Backport
   module Server
+    # A Backport TCP server. It runs a thread to accept incoming connections
+    # and automatically stops when the socket is closed.
+    #
     class Tcpip < Base
       include Connectable
 
-      def initialize host: 'localhost', port: 1117, adapter: Adapter
-        @socket = TCPServer.new(host, port)
+      def initialize host: 'localhost', port: 1117, adapter: Adapter, socket_class: TCPServer
+        @socket = socket_class.new(host, port)
         @adapter = adapter
         @stopped = false
       end
@@ -31,16 +34,46 @@ module Backport
 
       def stopping
         super
+        return if socket.closed?
         begin
-          socket.shutdown
-        rescue Errno::ENOTCONN, IOError
-          # ignore
+          socket.shutdown Socket::SHUT_RDWR
+        rescue Errno::ENOTCONN, IOError => e
+          Backport.logger.info "Minor exception while stopping server [#{e.class}] #{e.message}"
         end
         socket.close
       end
 
-      def stopped?
-        @stopped
+      # Accept an incoming connection using accept_nonblock. Return the
+      # resulting Client if a connection was accepted or nil if no connections
+      # are pending.
+      #
+      # @return [Client, nil]
+      def accept
+        result = nil
+        mutex.synchronize do
+          begin
+            conn = socket.accept_nonblock
+            addr = conn.addr(true)
+            data = {
+              family: addr[0],
+              port: addr[1],
+              hostname: addr[2],
+              address: addr[3]
+            }
+            clients.push Client.new(conn, conn, @adapter, data)
+            clients.last.run
+            result = clients.last
+          rescue IO::WaitReadable, Errno::EAGAIN => e
+            # ignore
+          rescue Errno::ENOTSOCK, IOError => e
+            Backport.logger.info "Server stopped with minor exception [#{e.class}] #{e.message}"
+            stop
+          rescue Exception => e
+            Backport.logger.warn "Server stopped with major exception [#{e.class}] #{e.message}"
+            stop
+          end
+        end
+        result
       end
 
       private
@@ -55,24 +88,10 @@ module Backport
       def start_accept_thread
         Thread.new do
           until stopped?
-            begin
-              conn = socket.accept
-              mutex.synchronize do
-                addr = conn.addr(true)
-                data = {
-                  family: addr[0],
-                  port: addr[1],
-                  hostname: addr[2],
-                  address: addr[3]
-                }
-                clients.push Client.new(conn, conn, @adapter, data)
-                clients.last.run
-              end
-            rescue Exception => e
-              STDERR.puts "Server stopped with exception [#{e.class}] #{e.message}"
-              stop
-              break
-            end
+            client = accept
+            Backport.logger.info "Client connected: #{client.adapter.remote}" unless client.nil?
+            sleep 0.01
+            stop if socket.closed?
           end
         end
       end

data/lib/backport/version.rb

@@ -1,3 +1,3 @@
-module Backport
-  VERSION = "0.2.0"
-end
+module Backport
+  VERSION = '0.3.0'.freeze
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: backport
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Fred Snyder
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-12-21 00:00:00.000000000 Z
+date: 2019-01-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -75,6 +75,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rspec"
+- ".rubocop.yml"
 - ".travis.yml"
 - CHANGELOG.md
 - Gemfile