client_for_poslynx 0.2.4 → 0.2.5

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    Y2M2MDJlODNlYWUyOTQ4MGY2MWU5MjAxNzhjMzY3ZTYzYTY4YTZhMg==
+    ZmJmMWFiZTY5MDAyYWRiMDM4ZGUxY2ZhYzJhZjEwNmJmMDc3ODU3NQ==
   data.tar.gz: !binary |-
-    MmRiYjM3YzcwN2MwNzM1NjdiNjlkNGUyNmU3NTViMDU3Mjg3MGNhOQ==
+    NmZkZTU4MGVlOGVjY2VkMzgxNjU2MjdhM2E3MDFhOWUyNmQyOWY1Yg==
 SHA512:
   metadata.gz: !binary |-
-    OTIwNDhmN2I4MzIyOTFkYmI5MzM2NzBhNTgzNDg1OGMxNDdlZjM3MzcyMjI1
-    ODVmZTk5YjNlMDVjMmMxNTNlMGNkZGM0NGNiM2RkNGRkMWIzYzY5YmM0NjNl
-    MjkyOTQzNWMyMWExZDBlOWU1YTRlYTc5YjQ3NjJiMDVjNzVkNGU=
+    YTliZjg2OGE3MjIwYjMwNzFiZmI5ZjVhZGVkMDRmZWE2ZmVkM2E0ZWQwZjk5
+    NjQ4NzUxNzg5OGI0NGZhZGVjNGY3YjI0ZGNiYTZkNDAxMDVlNDE3ZjY0Y2U0
+    ZDkxOThmODRmMWYwMTI5ZjRkMWVlM2YwZGVjNzgxMThiYTliNWY=
   data.tar.gz: !binary |-
-    MzNiYmNmMDRhYmJjNmZjODc4MjEwNzhhMzNiZDk5ODA4MTc5Mjg1ODNjY2Fl
-    YWE5MDJiM2NkNmQwM2IwM2VmMzQ3NGVkZTAyZTg3OWExYWNiZTViOGEzMjQx
-    YjMzNjhhNWVkN2FkNjdjZDIwNWM2MDVlMWMwNjFkZmMxMDIxNjQ=
+    YmEwNTQ1NzZlM2RhNjc1YzNlZTg0ZDk2NDhhMmQ1OWMxODZhMjY2YWZkYjkw
+    ZDg3NWJiZTJkOWZiMDY2ODY5MTkyODZlMTlmMTlhNmVlODNlNzcwY2UzMTFl
+    NDRmZjlhNGViZWZhNjk2ZjJlZjM4OWE1YzNjZmUxMjkxNmZmY2Q=

data/CHANGELOG

@@ -23,3 +23,9 @@ Version 0.2.3
 Version 0.2.4
 - Fix bug: Fake terminal script crashes during user interaction
   for a debit sale request without a specified cash back amount.
+
+Version 0.2.4
+- Introduce experimental signature image parsing and conversion
+  to SVG.
+- Fix bug: New format of POSLynx response message XML was causing
+  client to hang.

data/README.md

@@ -45,6 +45,9 @@ lib/client_for_poslynx/has_client_colsole_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'.
+
 ## Known Limitations
 
 * Only a subset of the possible messages and elements is supported.

data/foo.svg

@@ -0,0 +1,20 @@
+<svg version="1.1"
+     width="67.17mm" height="13.434mm"
+     viewBox="0 0 640 128"
+     preserveAspectRatio='none'
+     xmlns="http://www.w3.org/2000/svg"
+>
+
+  <path d='M 40,10 l 0,30 0,30 -5,5 -3,1 -3,-1 -5,-5
+           M 24,10 l 30,0
+           M 65,40 l 10,0 6,4 4,6 0,15 -4,6 -6,4 -10,0 -6,-4 -4,-6 0,-15, 4,-6
+           M 93,40 l 14,28 5,10
+           M 130,40 l -15,30 -15,30 M 160,50 l 0,0'
+        stroke='black'
+        stroke-width='1mm'
+        stroke-linejoin='round'
+        stroke-linecap='square'
+        fill='none'
+  />
+
+</svg>

data/lib/client_for_poslynx/bit_sequence.rb

@@ -0,0 +1,139 @@
+# coding: binary
+
+module ClientForPoslynx
+  class BitSequence
+    class TooManyBitsLong   < StandardError ; end
+    class NumberOutOfBounds < StandardError ; end
+
+    class << self
+      private :new
+
+      def from_packed_bits(packed_string)
+        digits_string = packed_string.unpack('B*').first
+        from_bit_digits( digits_string )
+      end
+
+      alias ^ from_packed_bits
+
+      def new_empty
+        from_bit_digits('')
+      end
+
+      def from_bit_digits(digits_string)
+        new( digits_string )
+      end
+
+      alias / from_bit_digits
+
+      def from_unsigned(value, seq_length)
+        if seq_length > 64
+          raise TooManyBitsLong, "Can't build a representation more than 64 bits long from an unsigned number"
+        end
+        if value < 0
+          raise NumberOutOfBounds, "Can't build an unsigned representation of a negative number"
+        end
+        if value >= 2 ** seq_length
+          raise NumberOutOfBounds, "The largest value representable in #{seq_length} bits is less than #{value}"
+        end
+        packed_bits = [ value ].pack('Q>')
+        bit_seq = from_packed_bits( packed_bits )
+        bit_seq.shift( 64 - seq_length )
+        bit_seq
+      end
+
+      def from_sign_and_magnitude_of(value, seq_length)
+        magnitude = value.abs
+        magnitude_seq = from_unsigned( magnitude, seq_length - 1 )
+        sign_bit = from_bit_digits( value < 0 ? '1' : '0' )
+        magnitude_seq.unshift( sign_bit )
+      end
+
+      def from_uuencoded(uuencoded)
+        packed_bits = uuencoded.unpack('u').first
+        from_packed_bits( packed_bits )
+      end
+    end
+
+    def initialize(digits_string)
+      @digits_string = digits_string
+    end
+
+    def inspect
+      "#<#{self.class.name}: #{pretty_digits}>"
+    end
+
+    def pretty_digits
+      nibbles = digits_string.scan(/.{1,4}/)
+      bytes = nibbles.each_slice(2).map{ |n| n.join(' ') }
+      bytes.join('  ')
+    end
+
+    def ==(other)
+      return false unless other.respond_to?( :to_bit_digits )
+      digits_string == other.to_bit_digits
+    end
+
+    def to_packed_bits
+      [ digits_string ].pack('B*')
+    end
+
+    def to_bit_digits
+      digits_string
+    end
+
+    def uuencode
+      [ to_packed_bits ].pack('u')
+    end
+
+    def length
+      digits_string.length
+    end
+
+    def first_bit_digit
+      digits_string[0..0]
+    end
+
+    def push(sequence)
+      digits_string << sequence.to_bit_digits
+      self
+    end
+
+    alias << push
+
+    def shift(bit_count)
+      digits_taken = digits_string[0...bit_count]
+      digits_string[0...bit_count] = ''
+      self.class.from_bit_digits( digits_taken )
+    end
+
+    def unshift( bit_sequence )
+      digits_string[0...0] = bit_sequence.to_bit_digits
+      self
+    end
+
+    def as_unsigned
+      if length > 64
+        raise TooManyBitsLong,
+          "Cannot coerce sequence longer than 64 bits to unsigned number"
+      end
+      little_endian_digits = digits_string.reverse + '0' * 64
+      packed_little_endian = [ little_endian_digits ].pack('b*')
+      packed_little_endian.unpack('Q<').first
+    end
+
+    def as_sign_and_magnitude
+      if length > 65
+        raise TooManyBitsLong,
+          "Cannot coerce sequence longer than 65 bits to unsigned number"
+      end
+      magnitude_seq = self.class.from_bit_digits( digits_string[1..-1] )
+      magnitude = magnitude_seq.as_unsigned
+      first_bit_digit == '1' ? - magnitude : magnitude
+    end
+
+    private
+
+    attr_reader :digits_string
+
+  end
+end

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

@@ -11,6 +11,7 @@ module ClientForPoslynx
         def visit_PinPadInitialize(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
 
         def visit_general(visitee) ; end
 

data/lib/client_for_poslynx/data/requests/credit_card_sale.rb

@@ -20,6 +20,7 @@ module ClientForPoslynx
         attr_element_mapping attribute: :track_1,              element: 'Track1'
         attr_element_mapping attribute: :card_number,          element: 'CardNumber'
         attr_element_mapping attribute: :expiry_date,          element: 'ExpiryDate'
+        attr_element_mapping attribute: :capture_signature,    element: 'ReqPPSigCapture'
 
       end
 

data/lib/client_for_poslynx/data/requests/pin_pad_get_signature.rb

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

data/lib/client_for_poslynx/data/requests.rb

@@ -5,6 +5,7 @@ require_relative 'requests/debit_card_sale'
 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/can_visit'
 
 module ClientForPoslynx

data/lib/client_for_poslynx/data/responses/credit_card_sale.rb

@@ -23,6 +23,7 @@ module ClientForPoslynx
         attr_element_mapping attribute: :transaction_date,         element: 'TransactionDate'
         attr_element_mapping attribute: :transaction_time,         element: 'TransactionTime'
         attr_element_mapping attribute: :input_method,             element: 'InputMethod'
+        attr_element_mapping attribute: :signature,                element: 'Signature'
         attr_element_mapping attribute: :receipt,                  element: 'Receipt',         numbered_lines: 'Receipt%d'
         attr_element_mapping attribute: :customer_receipt,         element: 'ReceiptCustomer', numbered_lines: 'Receipt%d'
 

data/lib/client_for_poslynx/data/responses/pin_pad_get_signature.rb

@@ -0,0 +1,18 @@
+# coding: utf-8
+
+require_relative 'abstract_response'
+
+module ClientForPoslynx
+  module Data
+    module Responses
+
+      class PinPadGetSignature < AbstractResponse
+
+        defining_property_value attribute: :command, element: 'Command', value: 'PPGETSIGNATURE'
+        attr_element_mapping attribute: :signature,  element: 'Signature'
+
+      end
+
+    end
+  end
+end

data/lib/client_for_poslynx/data/responses.rb

@@ -5,6 +5,7 @@ require_relative 'responses/debit_card_sale'
 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'
 
 module ClientForPoslynx
   module Data

data/lib/client_for_poslynx/experimental.rb

@@ -0,0 +1,16 @@
+# coding: utf-8
+
+# Require this file to load experimental features that
+# are not yet expected to be fully usable.
+
+# Bit sequence is actually in pretty good shape, but it's
+# here because it is only used by SignatureImage.
+require "client_for_poslynx/bit_sequence"
+
+# SignatureImage currently only supports the legacy
+# Hypercom/Equinox signature data format, which is useful
+# to approximately 0% of POSLynx users. It has also not
+# been tested with real data produced by a payment terminal,
+# so it is possible that some understandings about the
+# format are incorrect.
+require "client_for_poslynx/signature_image"

data/lib/client_for_poslynx/has_client_console_support.rb

@@ -22,7 +22,7 @@ module ClientForPoslynx
         conn = TCPSocket.new( config.host, config.port )
         conn.puts request.xml_serialize
         response = get_response_from( conn )
-        conn.close unless conn.eof?
+        conn.close unless conn.closed?
         response
       end
 
@@ -81,6 +81,12 @@ module ClientForPoslynx
         }
       end
 
+      def example_pin_pad_get_signature
+        ClientForPoslynx::Data::Requests::PinPadGetSignature.new.tap { |req|
+          assign_common_example_request_attrs_to req
+        }
+      end
+
       private
 
       def get_response_from( connection )

data/lib/client_for_poslynx/message_handling/xml_extractor.rb

@@ -23,11 +23,12 @@ module ClientForPoslynx
         root_name = nil
         while true
           line = stream.gets
+          puts line
           message << line
-          if (! root_name) && line =~ /^<([A-Za-z_][^\s>]*)[ >]/
+          if (! root_name) && line =~ /^(?:<\?.+?\?>)?<([A-Za-z_][^\s>]*)[ >]/
             root_name = $1
           end
-          break if root_name && line =~ /<\/#{root_name}\s*>$/
+          break if root_name && line =~ /<\/#{root_name}\s*>\s*$/
         end
         message
       end

data/lib/client_for_poslynx/signature_image/draw.rb

@@ -0,0 +1,43 @@
+# coding: utf-8
+
+module ClientForPoslynx
+  class SignatureImage
+
+    class Draw
+      DELTA_BITS_LONG = 6
+      BIT_SEQUENCE_LENGTH = 1 + DELTA_BITS_LONG * 2
+
+      def self.first_in_bit_sequence(bit_seq)
+        bit_seq.first_bit_digit == '0' &&
+          bit_seq.length >= BIT_SEQUENCE_LENGTH
+      end
+
+      def self.parse_from_bit_sequence!(bit_seq)
+        bit_seq.shift 1
+        dx_bit_seq = bit_seq.shift( DELTA_BITS_LONG )
+        dy_bit_seq = bit_seq.shift( DELTA_BITS_LONG )
+        new( dx_bit_seq.as_sign_and_magnitude, dy_bit_seq.as_sign_and_magnitude )
+      end
+
+      attr_reader :dx, :dy
+
+      def initialize(dx, dy)
+        @dx = dx
+        @dy = dy
+      end
+
+      def ==(other)
+        return false unless self.class === other
+        return dx == other.dx && dy == other.dy
+      end
+
+      def to_bit_sequence
+        bit_seq = ClientForPoslynx::BitSequence / '0'
+        bit_seq << ClientForPoslynx::BitSequence.from_sign_and_magnitude_of( dx, DELTA_BITS_LONG )
+        bit_seq << ClientForPoslynx::BitSequence.from_sign_and_magnitude_of( dy, DELTA_BITS_LONG )
+      end
+
+    end
+
+  end
+end

data/lib/client_for_poslynx/signature_image/move.rb

@@ -0,0 +1,43 @@
+# coding: utf-8
+
+module ClientForPoslynx
+  class SignatureImage
+
+    class Move
+      X_BITS_LONG = 10
+      Y_BITS_LONG = 7
+      BIT_SEQUENCE_LENGTH = 1 + X_BITS_LONG + Y_BITS_LONG
+
+      def self.first_in_bit_sequence(bit_seq)
+        bit_seq.first_bit_digit == '1' &&
+          bit_seq.length >= BIT_SEQUENCE_LENGTH
+      end
+
+      def self.parse_from_bit_sequence!(bit_seq)
+        bit_seq.shift 1
+        x_bit_seq = bit_seq.shift( X_BITS_LONG )
+        y_bit_seq = bit_seq.shift( Y_BITS_LONG )
+        new( x_bit_seq.as_unsigned, y_bit_seq.as_unsigned )
+      end
+
+      attr_reader :x, :y
+
+      def initialize(x,y)
+        @x = x
+        @y = y
+      end
+
+      def ==(other)
+        return false unless self.class === other
+        return x == other.x && y == other.y
+      end
+
+      def to_bit_sequence
+        bit_seq = ClientForPoslynx::BitSequence / '1'
+        bit_seq << ClientForPoslynx::BitSequence.from_unsigned( x, X_BITS_LONG )
+        bit_seq << ClientForPoslynx::BitSequence.from_unsigned( y, Y_BITS_LONG )
+      end
+    end
+
+  end
+end

data/lib/client_for_poslynx/signature_image/to_svg_converter.rb

@@ -0,0 +1,99 @@
+# coding: utf-8
+
+module ClientForPoslynx
+  class SignatureImage
+
+    class ToSvgConverter
+
+      class << self
+
+        private :new
+
+        def convert( signature_image )
+          new( signature_image ).call
+        end
+
+      end
+
+      attr_accessor :signature_image
+      private       :signature_image=
+
+      def initialize( signature_image )
+        self.signature_image = signature_image
+      end
+
+      def call
+        apply_document_characteristics
+
+        path_el = svg_document.create_element('path')
+        svg_element.add_child path_el
+
+        apply_path_characteristics_to path_el
+
+        path_el['d'] = path_data
+
+        svg_document.to_xml
+      end
+
+      private
+
+      def apply_document_characteristics
+        svg_element['width'              ] = '67.17mm'
+        svg_element['height'             ] = '13.434mm'
+        svg_element['viewBox'            ] = '0 0 640 128'
+        svg_element['preserveAspectRatio'] = 'none'
+      end
+
+      def svg_element
+        svg_document.root
+      end
+
+      def svg_document
+        @svg_document ||= begin
+          doc = Nokogiri::XML::Document.new
+          root_el = doc.root = doc.create_element('svg')
+          root_el.default_namespace = 'http://www.w3.org/2000/svg'
+          root_el['version'] = '1.1'
+          doc
+        end
+      end
+
+      def apply_path_characteristics_to(path_el)
+        apply_stroke_styling_to path_el
+        path_el['fill'] = 'none'
+      end
+
+      def apply_stroke_styling_to(path_el)
+        path_el['stroke'         ] = 'black'
+        path_el['stroke-width'   ] = '1mm'
+        path_el['stroke-linejoin'] = 'round'
+        # Square line cap improves visibility of zero-length
+        # lines (dots).
+        path_el['stroke-linecap' ] = 'square'
+      end
+
+      def path_data
+        data = ''
+        signature_image.shape_step_groups.each do |shape_steps|
+          data << abs_moveto_instruction_for_move_step( shape_steps.first )
+          data << rel_lineto_instruction_for_draw_steps( shape_steps[1..-1] )
+        end
+        data
+      end
+
+      def abs_moveto_instruction_for_move_step(step)
+        "M #{step.x},#{step.y} "
+      end
+
+      def rel_lineto_instruction_for_draw_steps(steps)
+        return 'l 0,0 ' if steps.empty?
+
+        steps.reduce( 'l ' ) { |instruction, step|
+          instruction << "#{step.dx},#{step.dy} "
+        }
+      end
+
+    end
+
+  end
+end

data/lib/client_for_poslynx/signature_image.rb

@@ -0,0 +1,97 @@
+# coding: utf-8
+
+require_relative 'signature_image/move'
+require_relative 'signature_image/draw'
+require_relative 'signature_image/to_svg_converter'
+
+module ClientForPoslynx
+
+  class SignatureImage
+
+    class << self
+
+      def deserialize(serialized_data)
+        packed_binary = uudecode( serialized_data )
+        bit_seq = ClientForPoslynx::BitSequence.from_packed_bits( packed_binary )
+
+        sig_image = new
+        step_types = [ SignatureImage::Move, SignatureImage::Draw ]
+        while true
+          step_type = step_types.detect{ |st| st.first_in_bit_sequence( bit_seq ) }
+          break if step_type.nil?
+          step = step_type.parse_from_bit_sequence!( bit_seq )
+          sig_image << step
+        end
+
+        sig_image
+      end
+
+      def uudecode(uuencoded)
+        uuencoded.unpack('u').first
+      end
+
+    end
+
+    def ==(other)
+      return false unless self.class === other
+      sequence == other.sequence
+    end
+
+    def move(*args)
+      sequence << Move.new(*args)
+    end
+
+    def draw(*args)
+      sequence << Draw.new(*args)
+    end
+
+    def <<(step)
+      sequence << step
+    end
+
+    def each_step
+      sequence.each do |step| ; yield step ; end
+    end
+
+    def shape_step_groups
+      groups = []
+      group = []
+      sequence.each do |step|
+        if SignatureImage::Move === step
+          group = []
+          groups << group
+        end
+        group << step
+      end
+      groups
+    end
+
+    def serialize_legacy
+      unless Move === sequence.first
+        raise 'Must have an initial move-type step in order to serialize'
+      end
+      bit_seq = ClientForPoslynx::BitSequence.new_empty
+      sequence.each do |step|
+        bit_seq << step.to_bit_sequence
+      end
+      bit_seq.uuencode
+    end
+
+    protected
+
+    def sequence
+      @sequence ||= []
+    end
+
+    private
+
+    def pack_binary_digits(digits_string)
+      [ digits_string ].pack('B*')
+    end
+
+    def uuencode_packed_bits(packed_bits_string)
+      [ packed_bits_string ].pack('u')
+    end
+  end
+
+end

data/lib/client_for_poslynx/version.rb

@@ -1,5 +1,5 @@
 # coding: utf-8
 
 module ClientForPoslynx
-  VERSION = '0.2.4'
+  VERSION = '0.2.5'
 end