client_for_poslynx 0.3.0 → 0.9.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    MDIyYTM1NTlkMTFhYTllNzI4ZDNlZjBlMGJjY2E3MzcxNjQ1ODJmNA==
+    OGRhYTY1N2JmMWVkZmVlNzA3MzM3MTBmYjY5YzVhMTE2YTE5YjQ5Mg==
   data.tar.gz: !binary |-
-    ZGM2ODlhZmQ2ZDZiMWM5ODkwM2QyNjc4MTdmMzFhMGU4OTVkYmNmZg==
+    N2YxY2IzMTUzODE1NjI2OGEwOWE3ZTFiYzVhMTMzY2IzOGExZTRhNQ==
 SHA512:
   metadata.gz: !binary |-
-    MDE0NDIxOTM5NWI3YTU5OTg5OGM2ZDRhYzMzNDcxNzdkMzQ1NGY2OGQ2MTNl
-    ZDk5ZjBiZTVjMzE2Mzc0ZGRkM2JjZmFjZjBkZWEzOGYyOTM0N2RhYWE4ZDM0
-    ZGE2YjYzOWU1OGE0MzkyMzQwYTIwYWI4NjQzZmYwMjJiNTMyYmE=
+    MGRlY2MwMTgxMWU3YWExNGIxODE4MDI3NThkZDZjMTkwMmVjM2Y2MDk1MjQ4
+    MTRmODhhYjcxN2VmY2FkOWMwYTU5MjI4MTZmYTY4YTE1MzI3MzIzZDRkNmNm
+    MDRmMGE5ZTZjZDM0YTQ0NzFiNmY0N2ZmMTFiZWFiMTY1MmYxOGI=
   data.tar.gz: !binary |-
-    NzA1ZmFiMDc1MDYyNTc4NTQyODZjZGNlZWI5N2U2OWE2NzkzNjM4MjYxZjBm
-    MjYzMmM5NDZjMjY3MTBmNGQyYjdlYWU0NDk1NWE3MjZiZTJhMmJlZjQyZmYz
-    YjA1NmJlNGUyOTIzNTY1MGMyYTQyNzY4MGZlMDE3YzFhYWQzMTM=
+    ZjVkODM0YThiMzZlZDFkM2QwZDhlMDY5MDAwMTk1YTUyYzEzNDIxMzQ1YzIw
+    YWNhOWNkZWRiZWM0YjY2MGE3NzY2NmNhOWM1MzRjYTc5MTM1ZmFiMGJkZDVl
+    MTYyMGU1OTliMWM2MDRlMGZhZDEzZjNiYzBhNDQ1NzhiZTU0NjI=

data/CHANGELOG

@@ -43,3 +43,15 @@ Version 0.3.0
 - Change word separators in poslynx_client_console from under-
   scores to dashes.
 - Fake Poslynx includes signature image data in response.
+
+Version 0.9.0
+- Add a network client in the form of an EventManager protocol.
+- Add a structured network client for use from within an irb
+  console.
+- Add ExampleRequestFactory class.
+- Remove the client console script aince the structured client
+  example request factory now provide the same capabilities from
+  within any irb session.
+- Overhaul the fake pos terminal script to be based on
+  EventMachine and to allow request processing to be interrupted
+  by the receipt of a new request.

data/README.md

@@ -9,52 +9,179 @@ Technologies.
 Features:
 
 * Data models for requests and responses.
-* Writing requests to output streams.
-* Reading responses from input streams.
+* Network interaction using an EventMachine protocol.
+* Simplified network interaction using a structured client
+  adapter.
 * A fake POSLynx appliance + PIN Pad script.
-* A POSLynx client console script.
 
-The best introduction to this gem is probably to play around with
-with the POSLynx client console.  Assuming you have a POSLynx
-unit with IP address 192.168.1.123, listening on port 54321 using
-SSL encryption, with a registered client MAC of 000000000000, an
-example poslynx client session might look like...
-
-    $ bundle exec poslynx_client_console 173.195.60.144:14270 --use-ssl --client_mac=000000000000
-    1.9.3-p545 :001 > req = poslynx_client.example_pin_pad_display_message_request
-     => #<ClientForPoslynx::Data::Requests::PinPadDisplayMessage:0x007f941b4b1fe8 @client_mac="001C42E644FE", @text_lines=["First example line", "Second example line"], @line_count=2, @button_labels=["1st of optional buttons", "2nd button"]>
-    1.9.3-p545 :002 > resp = poslynx_client.send_request(req)
-    <?xml version="1.0" standalone="yes" ?><PLResponse><Command>PPDISPLAY</Command><Result>Success</Result><ResultText>Success</ResultText><Response>2nd button</Response></PLResponse>
-     => #<ClientForPoslynx::Data::Responses::PinPadDisplayMessage:0x007f941b4b8230 @result="Success", @result_text="Success", @button_response="2nd button", @source_data="<?xml version=\"1.0\" standalone=\"yes\" ?><PLResponse><Command>PPDISPLAY</Command><Result>Success</Result><ResultText>Success</ResultText><Response>2nd button</Response></PLResponse>\r\n">
-
-This gem also provides a fake POS/terminal application that you
-can run in a separate console window when you are working without
-access to an actual POSLynx unit and PIN pad.  To start the fake
-POS/terminal listening on port 3010...
-
-    bundle exec fake_pos_terminal 3010
-
-If you then want to start the client console to interact with the
-fake POS/terminal instance on the same machine...
-
-    bundle exec poslynx_client_console :3010
+## Overview
+
+The `client_for_poslynx` gem provides network adapters that can
+be used to send requests to a POSLynx unit and receive the
+responses to those requests.  The gem also includes data models
+with XML serialization/deserialization that are used by those
+network adapters or may be used as part of a different network
+adapter if you prefer to build your own.
+
+The first network adapter provided is in the form of a protocol
+for EventMachine. EventMachine is a gem for implementing
+event-driven communication clients and servers.  Essentially,
+being event-driven means that requests are sent and responses are
+received asynchronously.  The application receives a call-back
+when the server responds or the connection is lost, etc.
+
+The second network adapter this gem provides is a "structured"
+(as opposed to event-driven) API.  This is primarily provided
+as a convenience for use in situations where the event-driven
+API is inconvenient, such as when experimenting with the gem
+from an irb command line session.
+
+In addition to the network client libraries, this gem includes
+a script that acts as a fake POSLynx + PIN Pad.  This is useful
+when you are working without access to an actual POSLynx and
+PIN Pad, and want to test your client code and try out
+workflows.  This script will probably be extracted into a
+separate gem soon.
 
 ## Usage
 
-The code in the
-lib/client_for_poslynx/has_client_console_support.rb file
-provides a good example of how to use the facilities that this
-gem provides.
-
-Some releases may also include experimental features that must
-be separately loaded by requiring "client_for_poslynx/experimental'.
+### Using the structured client
+
+A quick and easy way to try out this gem is to use the structured
+client and example-request factory from an irb console.
+
+Assuming you have a POSLynx host running at 192.168.1.99 on port
+1234 with SSL required, and if your lane has a registered client
+MAC value of 123456789ABC, then with the client_for_poslynx gem
+installed, you should be able to execute a sequence similar to
+the following.
+
+    $ irb
+    1.9.3-p545 :001 > require 'client_for_poslynx'
+     => true
+    1.9.3-p545 :002 > client = ClientForPoslynx::Net::StructuredClient.new('192.168.1.99', 1234, true)
+     => #<ClientForPoslynx::Net::StructuredClient:0x007fefa2103aa8 @directive_queue=#<Queue:0x007fefa21039e0 @que=[], @waiting=[], @mutex=#<Mutex:0x007fefa2103968>>, @activity_queue=#<Queue:0x007fefa2103940 @que=[], @waiting=[], @mutex=#<Mutex:0x007fefa2103300>>, @em_thread=#<Thread:0x007fefa2103260 sleep>>
+    1.9.3-p545 :003 > reqf = ClientForPoslynx::ExampleRequestFactory.new('1234567890ABC')
+     => #<ClientForPoslynx::ExampleRequestFactory:0x007fefa2036030 @client_mac="1234567890ABC">
+    1.9.3-p545 :004 > req = reqf.pin_pad_initialize_request
+     => #<ClientForPoslynx::Data::Requests::PinPadInitialize:0x007fefa204f760 @client_mac="1234567890ABC", @idle_prompt="Example idle prompt">
+    1.9.3-p545 :005 > client.send_request req
+     => nil
+    1.9.3-p545 :006 > client.get_response
+     => #<ClientForPoslynx::Data::Responses::PinPadInitialize:0x007fefa21106e0 @result="Success", @result_text="PinPad Initialized", @error_code="1000", @source_data="<?xml version=\"1.0\" standalone=\"yes\" ?><PLResponse><Command>PPINIT</Command><Result>Success</Result><ResultText>PinPad Initialized</ResultText><ErrorCode>1000</ErrorCode></PLResponse>">
+    1.9.3-p545 :007 > client.end_session
+     => nil
+
+### Using the EventMachine protocol
+
+The following example code demonstrates how to write an
+event-driven client using EventMachine and the POSLynx protocol
+for EventMachine.
+
+    require 'client_for_poslynx'
+    
+    HOST       = '192.168.1.25'
+    PORT       =  12345
+    CLIENT_MAC = '000000000000'
+    USE_SSL    =  true
+    
+    class ButtonSelectionDemo < EM::Connection
+      include EM::Protocols::POSLynx
+    
+      def connection_completed
+        puts "IP connection has been opened"
+        if USE_SSL
+          puts "Starting SSL"
+          start_tls verify_peer: false
+        else
+          puts "Using raw connection. No SSL"
+          display_the_message
+        end
+      end
+    
+      def ssl_handshake_completed
+        puts "SSL session has been successfully started"
+        display_the_message
+      end
+    
+      def display_the_message
+        puts "Sending the PIN Pad Display Message request"
+
+        req = ClientForPoslynx::Data::Requests::PinPadDisplayMessage.new
+        req.client_mac = CLIENT_MAC
+        req.line_count = 2
+        req.text_lines = [
+          "Heads, we clean the basement",
+          "Tails, we go to the movies"
+        ]
+        req.button_labels = %w[ Heads Tails ]
+    
+        send_request req
+      end
+    
+      def receive_response(response)
+        puts "Received response from POSLynx"
+        puts "Result text:     #{response.result_text}"
+        puts "Selected button: #{response.button_response}"
+    
+        puts "Closing the connection"
+        close_connection
+      end
+    
+      def unbind
+        puts "The connection has been closed"
+        puts "Terminating the event loop"
+        EM.stop_event_loop
+      end
+    
+    end
+    
+    # This code will block until the event loop exits.
+    EM.run do
+      EM.connect HOST, PORT, ButtonSelectionDemo
+      EM.error_handler do |e|
+        raise e
+      end
+    end
+    
+    puts "The event loop has ended"
+    puts "Bye"
+    
+    # == Sample output ==
+    # IP connection has been opened
+    # Starting SSL
+    # SSL session has been successfully started
+    # Sending the PIN Pad Display Message request
+    # Received response from POSLynx
+    # Result text:     Success
+    # Selected button: Tails
+    # Closing the connection
+    # The connection has been closed
+    # Terminating the event loop
+    # The event loop has ended
+    # Bye
+
+### Using the `fake_pos_terminal` script
+
+The `fake_pos_terminal` script runs a console-based facsimile of
+a PIN pad connected to a POSLynx device, listening on a local TCP
+port.  The script takes a single parameter indicating the port
+number to listen on.
+
+Under some circumstances, if you have installed the
+`client_for_poslynx` gem using Bundler, you might need to use
+`bundle exec` to run the script.
+
+To run the script listening on port 3010 using `bundle exec`:
+
+    $ bundle exec fake_pos_terminal 3010
+
+To stop the script, send an interrupt signal by pressing Ctrl+C.
 
 ## Known Limitations
 
 * Only a subset of the possible messages and elements is supported.
   __More will be added. Contributions are welcome and encouraged. :)__
-* Performs serialization of requests and parsing of responses, but
-  does not encapsulate actually making TCP connections and requests.
 
 ## Installation
 

data/TODO.txt

@@ -0,0 +1,6 @@
+ClientForPoslynx Gem development to-do items
+============================================
+
+Extract the fake POS terminal into a separate gem since it
+introduces Gem dependencies that ClientForPoslynx does not
+otherwise have.

data/bin/fake_pos_terminal

@@ -12,7 +12,7 @@ end
 # file name for input.
 $*.replace []
 
-# The only option we car about is --help, so we either show usage
+# The only option we care about is --help, so we either show usage
 # for --help or because an unrecognized option was given.
 show_usage = option_args.length > 0
 

data/client_for_poslynx.gemspec

@@ -22,8 +22,10 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 1.9.3'
 
   spec.add_dependency 'nokogiri', "~> 1.5"
+  spec.add_dependency 'eventmachine', "~> 1.0.0"
+  spec.add_dependency 'ruby-termios'
 
   spec.add_development_dependency "bundler", "~> 1.6"
   spec.add_development_dependency "rake"
-  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "rspec", "~> 3.0"
 end

data/lib/client_for_poslynx/data/abstract_data.rb

@@ -16,6 +16,10 @@ module ClientForPoslynx
           blank_new
         end
 
+        def short_name
+          name.split( '::' ).last
+        end
+
         def xml_parse(source_xml)
           doc = XmlDocument.from_xml( source_xml )
           data_class = concrete_data_class_for_nokogiri_document( doc )

data/lib/client_for_poslynx/data/requests/abstract_request.rb

@@ -14,6 +14,10 @@ module ClientForPoslynx
           instance
         end
 
+        def self.response_class
+          Data::Responses.const_get( short_name )
+        end
+
         def self.root_element_name
           ROOT_ELEMENT_NAME
         end

data/lib/client_for_poslynx/data/requests/can_visit.rb

@@ -9,6 +9,7 @@ module ClientForPoslynx
         def visit_CreditCardSale(visitee)             ; visit_general visitee ; end
         def visit_DebitCardSale(visitee)              ; visit_general visitee ; end
         def visit_PinPadInitialize(visitee)           ; visit_general visitee ; end
+        def visit_PinPadReset(visitee)                ; visit_general visitee ; end
         def visit_PinPadDisplayMessage(visitee)       ; visit_general visitee ; end
         def visit_PinPadDisplaySpecifiedForm(visitee) ; visit_general visitee ; end
         def visit_PinPadGetSignature(visitee)         ; visit_general visitee ; end

data/lib/client_for_poslynx/data/requests/pin_pad_reset.rb

@@ -0,0 +1,17 @@
+# coding: utf-8
+
+require_relative 'abstract_request'
+
+module ClientForPoslynx
+  module Data
+    module Requests
+
+      class PinPadReset < AbstractRequest
+
+        defining_property_value attribute: :command, element: 'Command', value: 'PPRESET'
+
+      end
+
+    end
+  end
+end

data/lib/client_for_poslynx/data/requests.rb

@@ -6,6 +6,7 @@ require_relative 'requests/pin_pad_initialize'
 require_relative 'requests/pin_pad_display_message'
 require_relative 'requests/pin_pad_display_specified_form'
 require_relative 'requests/pin_pad_get_signature'
+require_relative 'requests/pin_pad_reset'
 require_relative 'requests/can_visit'
 
 module ClientForPoslynx

data/lib/client_for_poslynx/data/responses/abstract_response.rb

@@ -8,6 +8,10 @@ module ClientForPoslynx
 
       class AbstractResponse < AbstractData
 
+        def self.request_class
+          Data::Requests.const_get( short_name )
+        end
+
         def self.root_element_name
           ROOT_ELEMENT_NAME
         end

data/lib/client_for_poslynx/data/responses/pin_pad_reset.rb

@@ -0,0 +1,17 @@
+# coding: utf-8
+
+require_relative 'abstract_response'
+
+module ClientForPoslynx
+  module Data
+    module Responses
+
+      class PinPadReset < AbstractResponse
+
+        defining_property_value attribute: :command, element: 'Command', value: 'PPRESET'
+
+      end
+
+    end
+  end
+end

data/lib/client_for_poslynx/data/responses.rb

@@ -6,6 +6,7 @@ require_relative 'responses/pin_pad_initialize'
 require_relative 'responses/pin_pad_display_message'
 require_relative 'responses/pin_pad_display_specified_form'
 require_relative 'responses/pin_pad_get_signature'
+require_relative 'responses/pin_pad_reset'
 
 module ClientForPoslynx
   module Data

data/lib/client_for_poslynx/example_request_factory.rb

@@ -0,0 +1,96 @@
+# coding: utf-8
+
+module ClientForPoslynx
+
+  # A class of factories for building request data instances that
+  # are pre-populated with example data. This is primarily useful
+  # for exploration and experimentation in the irb console.
+  class ExampleRequestFactory
+    attr_reader :client_mac
+
+    # Initializes a ne factory instance, optionally with a
+    # client_mac value to be assigned to each request-data object
+    # that the factory builds.
+    def initialize(client_mac = nil)
+      @client_mac = client_mac
+    end
+
+    def pin_pad_initialize_request
+      Data::Requests::PinPadInitialize.new.tap { |req|
+        assign_common_example_request_attrs_to req
+        now_text = Time.now.strftime('%H:%M:%S')
+        req.idle_prompt = "Example idle prompt at #{now_text}"
+      }
+    end
+
+    def pin_pad_reset_request
+      Data::Requests::PinPadReset.new.tap { |req|
+        assign_common_example_request_attrs_to req
+      }
+    end
+
+    def pin_pad_display_message_request
+      ClientForPoslynx::Data::Requests::PinPadDisplayMessage.new.tap { |req|
+        assign_common_example_request_attrs_to req
+        req.text_lines = [
+          "First example line",
+          "Second example line",
+        ]
+        req.line_count = 2
+        req.button_labels = [
+          "1st of optional buttons",
+          "2nd button",
+        ]
+      }
+    end
+
+    def credit_card_sale_request
+      ClientForPoslynx::Data::Requests::CreditCardSale.new.tap { |req|
+        assign_common_example_request_attrs_to req
+        req.merchant_supplied_id = 'INVC-123-MERCH-SUPPL'
+        req.amount               = '101.25'
+        req.input_source         = 'EXTERNAL'
+        req.capture_signature    = 'Yes'
+      }
+    end
+
+    def debit_card_sale_request
+      ClientForPoslynx::Data::Requests::DebitCardSale.new.tap { |req|
+        assign_common_example_request_attrs_to req
+        req.merchant_supplied_id = 'INVC-123-MERCH-SUPPL'
+        req.amount               = '101.25'
+        req.cash_back            =  '20.00'
+        req.input_source         = 'EXTERNAL'
+      }
+    end
+
+    def pin_pad_display_specified_form_request
+      ClientForPoslynx::Data::Requests::PinPadDisplaySpecifiedForm.new.tap { |req|
+        assign_common_example_request_attrs_to req
+        req.form_name = 'my_special_form'
+        req.text_values = [
+          "First example text value",
+          "Second example text value",
+        ]
+        req.button_labels = [
+          "1st of optional buttons",
+          "2nd button"
+        ]
+      }
+    end
+
+    def pin_pad_get_signature
+      ClientForPoslynx::Data::Requests::PinPadGetSignature.new.tap { |req|
+        assign_common_example_request_attrs_to req
+      }
+    end
+
+    private
+
+    def assign_common_example_request_attrs_to(request)
+      request.client_mac = client_mac if client_mac
+    end
+
+  end
+
+end

data/lib/client_for_poslynx/fake_pos_terminal/console_user_interface/content_formatter.rb

@@ -0,0 +1,75 @@
+# coding: utf-8
+
+require 'delegate'
+
+module ClientForPoslynx
+  module FakePosTerminal
+    class ConsoleUserInterface
+
+      module ContentFormatter
+        extend self
+
+        extend FakePosTerminal::ValueFormatting
+
+        def multiline_message(text_lines)
+          centered_lines = text_lines.map { |text| text.center(68) }
+          "\n" << centered_lines * "\n" << "\n\n"
+        end
+
+        def buttons(button_labels)
+          button_strings = button_labels.map { |label| "[ #{label} ]" }
+          tot_button_space = button_strings.map(&:length).inject{ |m, length| m + length }
+          tot_marginal_space = 68 - tot_button_space
+          padding_size = tot_marginal_space / ( button_strings.length * 2 )
+          padding = ' ' * padding_size
+          button_strings.map! { |string| padding + string + padding }
+          ( button_strings * '' ).center( 68 )
+        end
+
+        def welcome_with_idle_prompt(prompt)
+'
+                        ___       _    _            ___
+             |   |   | |    |    / \  / \  |     | |
+             |   |   | |    |   |    |   | |\   /| |    
+             |   |   | |--  |   |    |   | | \ / | |--
+             |  / \  | |    |   |    |   | |  |  | |    
+              \/   \/  |___ |___ \_/  \_/  |  |  | |___
+
+' + "  (#{prompt})\n"
+        end
+
+        def signature_entry_box
+'
+
+      Sign here...
+     -----------------------------------------------------------
+    |                                                           |
+    |                                                           |
+    |                                                           |
+     -----------------------------------------------------------
+
+'
+        end
+
+        def payment_confirmation(amount)
+          lines = []
+          lines << "TOTAL AMOUNT"
+          lines << format_usd( amount )
+          multiline_message(lines)
+        end
+
+        def card_swipe_request(request_data)
+          total       = request_data.amount
+          transaction = 'PURCHASE'
+          lines = []
+          lines << "Please swipe your card"
+          lines << "Total: " + format_usd( total ) if total
+          lines << "Transaction: " + transaction
+          multiline_message( lines )
+        end
+
+      end
+
+    end
+  end
+end