backport 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 631a99833ea290a7aa20e2e18f188eb19b81a141e32288feeb96ac514c39a86c
-  data.tar.gz: 5dcd3ea31192dbb810d18f7e5ca6c3757f3613a8e0a625f0d14e7801714a0e62
+  metadata.gz: 2aedfc84d845aedeb6d7146cb21a74c4d1d74d90844407982ce454e8aa2d16b3
+  data.tar.gz: e222830378478e7990601880b42e60dd4e34ba1791e63345a2a5fa0a2898bbf8
 SHA512:
-  metadata.gz: 1ab759e6cd1fb063dbc9f56648d0f98771b3b2390593937c73c6d6b8e655110644b94028f2739dab3bb2f7b5ca704d2bba0838d604866b9939f607eccd85fae5
-  data.tar.gz: 8e6531f1ad46e37f01086991bca2c6ac1ddd262c381fb514a3a4b0674b5d7001412c1b469ae56a03d50a2edf69040bd761940413b3b2d741d4fb7ec3d1b3bfec
+  metadata.gz: 5cd8632b158f0e5dda4e5377b5fc74a9e7ae416a738941dcf276cd48d8040c671eb9e337a089215e092ec499fecbadfaf6c015f49f09b72bc4cee556780afa4f
+  data.tar.gz: e52ea4e36b3bfbd397dabc9410d07af6106d1c7bc1e9dbac98d18a2def432300e64696ee3e277ad1e19639d61027ccb46d3a3f665603031ffab26c81d4f7ba83

data/.rspec

@@ -1,3 +1,2 @@
---format documentation
 --color
 --require spec_helper

data/.travis.yml

@@ -3,5 +3,16 @@ sudo: false
 language: ruby
 cache: bundler
 rvm:
+  - 2.1
+  - 2.2
+  - 2.3
+  - 2.4
+  - 2.5.1
   - 2.5.3
+  - jruby-9.0.5.0
+  - jruby-9.1.16.0
+matrix:
+  include:
+    - rvm: 2.4
+      os: osx
 before_install: gem install bundler -v 1.17.2

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+## 0.2.0 - December 21, 2018
+- Minor bug fixes in STDIO server
+- More efficient client reads
+- Rename server methods `prepare` for clarity
+- Improved socket state handling
+- More accurate interval time
+- Adapter#remote attribute
+- Adapter#close method
+- Socket exception handling
+
+## 0.1.0 - December 20, 2018
+First release

data/README.md

@@ -20,7 +20,7 @@ gem 'backport'
 
 ## Usage
 
-This example demonstrates a simple echo server.
+A simple echo server:
 
 ```ruby
 require 'backport'
@@ -40,8 +40,17 @@ module MyAdapter
 end
 
 Backport.run do
-  Backport.start_tcp_server(adapter: MyAdapter)
-  Backport.start_interval 1 do
+  Backport.prepare_tcp_server(host: 'localhost', port: 8000, adapter: MyAdapter)
+end
+```
+
+An interval server that runs once per second:
+
+```ruby
+require 'backport'
+
+Backport.run do
+  Backport.prepare_interval 1 do
     puts "tick"
   end
 end

data/backport.gemspec

@@ -23,4 +23,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.17"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "simplecov", "~> 0.14"
 end

data/lib/backport.rb

@@ -8,28 +8,57 @@ module Backport
   autoload :Client,  'backport/client'
 
   class << self
-    def start_stdio_server adapter: Adapter
-      machine.start_server Backport::Server::Stdio.new(adapter: adapter)
+    # 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
 
-    def start_tcp_server host: 'localhost', port: 1117, adapter: Adapter
-      machine.start_server Backport::Server::Tcpip.new(host: host, port: port, adapter: adapter)
+    # 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
 
-    def start_interval period, &block
-      machine.start_server Backport::Server::Interval.new(period, &block)
+    # 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

data/lib/backport/adapter.rb

@@ -1,27 +1,67 @@
 module Backport
   class Adapter
-    def initialize output
+    # 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
     end
 
-    def opening
-      STDERR.puts "Opening"
-    end
+    # A callback triggered when a client connection is opening. Subclasses
+    # and/or modules should override this method to provide their own
+    # functionality.
+    #
+    # @return [void]
+    def opening; end
 
-    def closing
-      STDERR.puts "Closing"
-    end
+    # A callback triggered when a client connection is closing. Subclasses
+    # and/or modules should override this method to provide their own
+    # functionality.
+    #
+    # @return [void]
+    def closing; end
 
-    def sending data
-      STDERR.puts "Client sent #{data}"
-    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.
+    #
+    # @param data [String]
+    # @return [void]
+    def sending(data); end
 
+    # Send data to the client.
+    #
+    # @param data [String]
+    # @return [void]
     def write data
-      @out.print data
+      @out.write data
+      @out.flush
     end
 
+    # Send a line of data to the client.
+    #
+    # @param data [String]
+    # @return [void]
     def write_line data
       @out.puts data
+      @out.flush
+    end
+
+    def closed?
+      @closed ||= false
+    end
+
+    def close
+      return if closed?
+      @closed = true
+      closing
     end
   end
 end

data/lib/backport/client.rb

@@ -1,10 +1,12 @@
 module Backport
   class Client
-    def initialize input, output, adapter
+    # @return [Adapter]
+    attr_reader :adapter
+
+    def initialize input, output, adapter, remote = {}
       @in = input
       @out = output
-      # @todo Adapter can either be an Adapter class or a module
-      @adapter = make_adapter(adapter)
+      @adapter = make_adapter(adapter, remote)
       @stopped = true
       @buffer = ''
     end
@@ -41,11 +43,11 @@ module Backport
 
     private
 
-    def make_adapter cls_mod
-      if cls_mod.is_a?(Class)
-        @adapter = cls_mod.new(@out)
-      elsif cls_mod.is_a?(Module)
-        @adapter = Adapter.new(@out)
+    def make_adapter cls_mod, remote
+      if cls_mod.is_a?(Class) && cls_mod <= Backport::Adapter
+        @adapter = cls_mod.new(@out, remote)
+      elsif cls_mod.class == Module
+        @adapter = Adapter.new(@out, remote)
         @adapter.extend cls_mod
       else
         raise TypeError, "#{cls_mod} is not a valid Backport adapter"
@@ -59,13 +61,17 @@ module Backport
     def run_input_thread
       Thread.new do
         until stopped?
-          char = @in.getc
-          if char.nil?
-            STDERR.puts "Client received nil. Stopping"
+          @in.flush
+          begin
+            chars = @in.sysread(255)
+          rescue EOFError, Errno::ECONNRESET
+            chars = nil
+          end
+          if chars.nil?
             stop
             break
           end
-          mutex.synchronize { @buffer.concat char }
+          mutex.synchronize { @buffer.concat chars }
         end
       end
     end

data/lib/backport/machine.rb

@@ -4,30 +4,48 @@ module Backport
       @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
+    # until the machine is stopped.
+    #
+    # @return [void]
     def run
       return unless stopped?
+      servers.clear
       @stopped = false
       yield if block_given?
       run_server_thread
     end
 
+    # Stop the machine.
+    #
+    # @return [void]
     def stop
       servers.map(&:stop)
       servers.clear
       @stopped = true
     end
 
+    # True if the machine is stopped.
+    #
     def stopped?
       @stopped ||= false
     end
 
-    def start_server server
+    # Add a server to the machine. The server will be started when the machine
+    # starts. If the machine is already running, the server will be started
+    # immediately.
+    #
+    # @param server [Server::Base]
+    # @return [void]
+    def prepare server
       servers.push server
+      server.start unless stopped?
     end
 
     private
 
-    # @return [Array<Backport::Server>]
+    # @return [Array<Server::Base>]
     def servers
       @servers ||= []
     end
@@ -35,10 +53,7 @@ module Backport
     def run_server_thread
       servers.map(&:start)
       until stopped?
-        servers.each do |server|
-          server.tick
-          sleep 0.001
-        end
+        servers.each(&:tick)
         sleep 0.001
       end
     end

data/lib/backport/server/base.rb

@@ -1,21 +1,40 @@
 module Backport
   module Server
     class Base
-      def stopped?
-        @stopped = false if @stopped.nil?
-        @stopped
+      def started?
+        @started ||= false
+        @started
       end
 
       def stop
         stopping
-        @stopped = true
+        @started = false
       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.
+      #
+      # @return [void]
+      def starting; end
+
+      # A callback triggered when the server is stopping. Subclasses should
+      # override this method to provide their own functionality.
+      #
+      # @return [void]
       def stopping; end
 
+      # A callback triggered from the main loop of a running Machine.
+      # Subclasses should override this method to provide their own
+      # functionality.
+      #
+      # @return [void]
       def tick; end
 
-      def start; end
+      def start
+        starting
+        @started = true
+      end
     end
   end
 end

data/lib/backport/server/connectable.rb

@@ -8,7 +8,7 @@ module Backport
         end
       end
 
-      def start
+      def starting
         clients.map(&:run)
       end
 
@@ -16,8 +16,6 @@ module Backport
         clients.map(&:stop)
       end
 
-      protected
-
       def clients
         @clients ||= []
       end

data/lib/backport/server/interval.rb

@@ -8,13 +8,10 @@ module Backport
       end
 
       def tick
-        return unless Time.now - @last_time > @period
+        now = Time.now
+        return unless now - @last_time > @period
         @block.call
-        @last_time = Time.now
-      end
-
-      def stop
-        @stopped = true
+        @last_time = now
       end
     end
   end

data/lib/backport/server/stdio.rb

@@ -6,7 +6,7 @@ module Backport
       def initialize input: STDIN, output: STDOUT, adapter: Adapter
         @in = input
         @out = output
-        @in.binmode
+        @out.binmode
         @adapter = adapter
         clients.push Client.new(input, output, adapter)
       end

data/lib/backport/server/tcpip.rb

@@ -8,28 +8,44 @@ module Backport
       def initialize host: 'localhost', port: 1117, adapter: Adapter
         @socket = TCPServer.new(host, port)
         @adapter = adapter
-      end
-
-      def stopped?
-        @stopped ||= false
+        @stopped = false
       end
 
       def tick
         mutex.synchronize do
           clients.each do |client|
+            if client.adapter.closed?
+              client.stop
+              next
+            end
             input = client.read
             client.sending input unless input.nil?
           end
+          clients.delete_if(&:stopped?)
         end
       end
 
-      def start
-        super
+      def starting
         start_accept_thread
       end
 
+      def stopping
+        super
+        begin
+          socket.shutdown
+        rescue Errno::ENOTCONN, IOError
+          # ignore
+        end
+        socket.close
+      end
+
+      def stopped?
+        @stopped
+      end
+
       private
 
+      # @return [TCPSocket]
       attr_reader :socket
 
       def mutex
@@ -39,10 +55,23 @@ module Backport
       def start_accept_thread
         Thread.new do
           until stopped?
-            conn = socket.accept
-            mutex.synchronize do
-              clients.push Client.new(conn, conn, @adapter)
-              clients.last.run
+            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
           end
         end

data/lib/backport/version.rb

@@ -1,3 +1,3 @@
 module Backport
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: backport
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Fred Snyder
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-12-20 00:00:00.000000000 Z
+date: 2018-12-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.14'
 description: 
 email:
 - fsnyder@castwide.com
@@ -62,6 +76,7 @@ files:
 - ".gitignore"
 - ".rspec"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md