sip2 0.1.1 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8f73fce390c230b1c0d95bba4221ebe77368b49a394635d84d8bd8314208ebb
-  data.tar.gz: c1b9beff001b1e3774a57853d2b031c5154fe51b793be2c301968744e61ca08d
+  metadata.gz: 7ef89c74848c5fbf09675afeb914f52985512f780fdcdc086288cebf6cd245c1
+  data.tar.gz: db0228463ed3b7466c650d4f3882befa65deeebbdd7433692698321dcada9a4b
 SHA512:
-  metadata.gz: 44d2323ee3939e99bdb192c5f61ce0be327321e99f5260592f62260ad3145d2681353ef759aff7a3193c09c7b5403e1f08f50fac661ecf22a063ec3ba475cfa8
-  data.tar.gz: 22e1645b0b13fcdff5de58757a9ba052191173c7fd374572fdadfaeba99a66b4b495d3dbb2b98dc717692f2f3c0442c975769c6917aaf7097d4c6f9a600ffeee
+  metadata.gz: 3b57c2fc70a1514c5bd29741b5ec07f08f539105231ba0849f27e62d960e12d667a9e1dc22a089ddd250a85fef82497fc1ba0c3821060c651179bd8880d9ae9d
+  data.tar.gz: 056c703e7f951b0aeb92b41322d050627f3c354162d6dc8af985a3ae1ca649e100be6620d3cbe68e36090a8c7c64b00a98ff647394c5260918b2a01f7da9bc1c

data/README.md

@@ -42,6 +42,45 @@ patron =
 puts 'Valid patron' if patron && patron.authenticated?
 ```
 
+### Using TLS
+
+The Sip2::Client will use TLS if a
+[SSLContext](https://ruby-doc.org/stdlib-2.4.10/libdoc/openssl/rdoc/OpenSSL/SSL/SSLContext.html)
+is passed in the `ssl_context` parameter. There are quite a few ways this can be configured, but that will
+depend on how the server being connected to is configured. A basic example is:
+
+```ruby
+# Setup a cert store using the system certificates/trust chain
+cert_store = OpenSSL::X509::Store.new
+cert_store.set_default_paths
+
+# Setup the SSL context
+ssl_context = OpenSSL::SSL::SSLContext.new
+ssl_context.verify_mode = OpenSSL::SSL::VERIFY_PEER # This is important. We want to verify the certificate is legitimate 
+ssl_context.min_version = OpenSSL::SSL::TLS1_2_VERSION # Generally good practice to enforce the most recent TLS version
+ssl_context.cert_store = cert_store # Use the certificate store we configured above
+
+# Raise an exception if the certificate doesn't check out
+ssl_context.verify_callback = proc do |preverify_ok, context|
+  raise OpenSSL::SSL::SSLError, <<~ERROR.strip if preverify_ok != true || context.error != 0
+    SSL Verification failed -- Preverify: #{preverify_ok}, Error: #{context.error_string} (#{context.error})
+  ERROR
+
+  true
+end
+
+client = Sip2::Client.new(host: 'my.sip2.host.net', port: 6001, ssl_context: ssl_context)
+```
+
+If you needed to explicitly specify the certificate to be used there are a few options available
+to use instead of cert_store (see the documentation for full details and other options):
+ * ca_file          - path to a file containing a CA certificate
+ * ca_path          - path to a directory containing CA certificates
+ * client_ca        - a certificate or array of certificates
+ * client_cert_cb   - callback where an array containing an X509 certificate and key are returned
+
+Be sure to validate that your setup behaves the way you expect it to.
+Pass in an invalid certificate and see it fails. Pass a mismatching hostname and see it fails. etc.
 
 ## Contributing
 

data/lib/sip2/client.rb

@@ -1,20 +1,35 @@
+# frozen_string_literal: true
+
 module Sip2
   #
   # Sip2 Client
   #
   class Client
-    def initialize(host:, port:, ignore_error_detection: false, timeout: nil)
+    def initialize(host:, port:, ignore_error_detection: false, timeout: nil, ssl_context: nil)
       @host = host
       @port = port
       @ignore_error_detection = ignore_error_detection
       @timeout = timeout || NonBlockingSocket::DEFAULT_TIMEOUT
+      @ssl_context = ssl_context
     end
 
-    def connect
-      socket = NonBlockingSocket.connect @host, @port, @timeout
-      yield Connection.new(socket, @ignore_error_detection) if block_given?
+    def connect # rubocop:disable Metrics/MethodLength
+      socket = NonBlockingSocket.connect host: @host, port: @port, timeout: @timeout
+
+      # If we've been provided with an SSL context then use it to wrap out existing connection
+      if @ssl_context
+        socket = ::OpenSSL::SSL::SSLSocket.new socket, @ssl_context
+        socket.hostname = @host # Needed for SNI
+        socket.sync_close = true
+        socket.connect
+        socket.post_connection_check @host # Validate the peer certificate matches the host
+      end
+
+      if block_given?
+        yield Connection.new(socket: socket, ignore_error_detection: @ignore_error_detection)
+      end
     ensure
-      socket.close if socket
+      socket&.close
     end
   end
 end

data/lib/sip2/connection.rb

@@ -1,57 +1,66 @@
+# frozen_string_literal: true
+
 module Sip2
   #
   # Sip2 Connection
   #
   class Connection
-    @connection_modules = []
-
-    class << self
-      attr_reader :connection_modules
-
-      def add_connection_module(module_name)
-        @connection_modules << module_name
-      end
-    end
-
-    include Messages::Login
-    include Messages::PatronInformation
+    LINE_SEPARATOR = "\r"
 
-    def initialize(socket, ignore_error_detection)
+    def initialize(socket:, ignore_error_detection: false)
       @socket = socket
       @ignore_error_detection = ignore_error_detection
       @sequence = 1
     end
 
-    def method_missing(method_name, *args)
-      if Connection.connection_modules.include?(method_name.to_sym)
-        send_and_handle_message(method_name, *args)
-      else
+    def send_message(message)
+      message = with_checksum with_error_detection message
+      write_with_timeout message
+      # Read the response and strip any leading newline
+      # - Some ACS terminate messages with /r/n by mistake.
+      #   We need to remove from the front (i.e. buffer remnant from the previous message)
+      response = read_with_timeout&.[](/\A\n?(.*)\z/, 1)
+      response if sequence_and_checksum_valid? response
+    ensure
+      @sequence += 1
+    end
+
+    def method_missing(method_name, *args, **kwargs)
+      message_class = Messages::Base.message_class_for_method(method_name)
+      if message_class.nil?
         super
+      else
+        message_class.new(self).action_message(*args, **kwargs)
       end
     end
 
     def respond_to_missing?(method_name, _include_private = false)
-      Connection.connection_modules.include?(method_name.to_sym) || super
+      !Messages::Base.message_class_for_method(method_name).nil? || super
     end
 
     private
 
-    def send_and_handle_message(message_type, *args)
-      message = send "build_#{message_type}_message", *args
-      message = with_checksum with_error_detection message
-      response = send_message message
-      return if response.nil?
+    def write_with_timeout(message, separator: LINE_SEPARATOR)
+      ::Timeout.timeout connection_timeout, WriteTimeout do
+        @socket.write message + separator
+      end
+    end
 
-      send "handle_#{message_type}_response", response
+    def read_with_timeout(separator: LINE_SEPARATOR)
+      ::Timeout.timeout connection_timeout, ReadTimeout do
+        @socket.gets(separator)&.chomp(separator)
+      end
     end
 
-    def send_message(message)
-      @socket.send_with_timeout message
-      @socket.gets_with_timeout
+    def connection_timeout
+      # We want the underlying connection where the timeout is configured,
+      # so if we're dealing with an SSLSocket then we need to unwrap it
+      io = @socket.respond_to?(:io) ? @socket.io : @socket
+      io.connection_timeout || NonBlockingSocket::DEFAULT_TIMEOUT
     end
 
     def with_error_detection(message)
-      message + '|AY' + @sequence.to_s
+      "#{message}|AY#{@sequence}"
     end
 
     def with_checksum(message)
@@ -64,19 +73,18 @@ module Sip2
       message.each_char { |m| check += m.ord }
       check += "\0".ord
       check = (check ^ 0xFFFF) + 1
-      format '%4.4X', check
+      format '%<check>4.4X', check: check
     end
 
     def sequence_and_checksum_valid?(response)
       return true if @ignore_error_detection
+      return false unless response.is_a? String
 
-      sequence_regex = /^(?<message>.*?AY(?<sequence>[0-9]+)AZ)(?<checksum>[A-F0-9]{4})$/
+      sequence_regex = /\A(?<message>.*?AY(?<sequence>[0-9]+)AZ)(?<checksum>[A-F0-9]{4})\z/
       match = response.strip.match sequence_regex
       match &&
         match[:sequence] == @sequence.to_s &&
         match[:checksum] == checksum_for(match[:message])
-    ensure
-      @sequence += 1
     end
   end
 end

data/lib/sip2/messages/base.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Sip2
+  module Messages
+    #
+    # Sip2 Base message handler
+    #
+    class Base
+      @message_class_lookup = {}
+
+      # Class helper to fetch the descendant "message" class based on a method name
+      #
+      # @param [String] method_name the underscore case name of the class to fetch
+      # @return [Class] the message class fetched based on the method_name,
+      #                 `nil` if no descendant was found
+      # @example
+      #   message_class_for_method('patron_information')
+      #   => Sip2::Messages::PatronInformation
+      def self.message_class_for_method(method_name) # rubocop:disable Metrics/MethodLength
+        return @message_class_lookup[method_name] if @message_class_lookup.key? :method_name
+
+        @message_class_lookup[method_name] =
+          begin
+            # classify the method name so we can fetch the message class of the same name
+            class_name = method_name.to_s.capitalize.gsub(%r{(?:_|(/))([a-z\d]*)}i) do
+              "#{Regexp.last_match(1)}#{Regexp.last_match(2).capitalize}"
+            end
+            message_class = Messages.const_get(class_name)
+            message_class if message_class && message_class < self
+          rescue NameError
+            nil
+          end
+      end
+
+      def initialize(connection)
+        @connection = connection
+      end
+
+      # Action the message, passing the dynamic arguments to the specific message implementation
+      #
+      # @param [*various] args Arguments to pass to the specific message implementation
+      # @return returns `nil` if there was no valid message returned.
+      #         Otherwise value will depend on the specific message. See the `handle_response`
+      #         method in those classes for more information
+      def action_message(**args)
+        message = build_message(**args)
+        response = @connection.send_message message
+        return if response.nil?
+
+        handle_response(response)
+      end
+
+      private
+
+      def build_message(**)
+        raise NotImplementedError, "#{self.class} must implement `build_message` method"
+      end
+
+      def handle_response(_response)
+        raise NotImplementedError, "#{self.class} must implement `handle_response` method"
+      end
+    end
+  end
+end

data/lib/sip2/messages/login.rb

@@ -1,20 +1,32 @@
+# frozen_string_literal: true
+
 module Sip2
   module Messages
     #
-    # Sip2 Login message module
+    # Sip2 Login message
     #
-    module Login
-      def self.included(klass)
-        klass.add_connection_module :login
-      end
-
+    # https://developers.exlibrisgroup.com/wp-content/uploads/2020/01/3M-Standard-Interchange-Protocol-Version-2.00.pdf
+    #
+    # Request message 93
+    #  * UID algorithm       - 1 char, fixed-length required field; the algorithm used
+    #                          to encrypt the user id
+    #  * PWD algorithm       - 1 char, fixed-length required field; the algorithm used
+    #                          to encrypt the password
+    #  * login user id  - CN - variable-length required field
+    #  * login password - CO - variable-length required field
+    #  * location code  - CP - variable-length required field
+    #
+    # Response message 94
+    #  * ok - 1 char, fixed-length required field: 0 or 1
+    #
+    class Login < Base
       private
 
-      def build_login_message(username, password, location_code = nil)
+      def build_message(username:, password:, location_code: nil)
         code = '93' # Login
         uid_algorithm = pw_algorithm = '0' # Plain text
-        username_field = 'CN' + username
-        password_field = 'CO' + password
+        username_field = "CN#{username}"
+        password_field = "CO#{password}"
         location_code = location_code.strip if location_code.is_a? String
         location_field = location_code ? "|CP#{location_code}" : ''
 
@@ -23,8 +35,8 @@ module Sip2
         ].join
       end
 
-      def handle_login_response(response)
-        sequence_and_checksum_valid?(response) && response[/^94([01])AY/, 1] == '1'
+      def handle_response(response)
+        response[/\A94([01])AY/, 1] == '1'
       end
     end
   end

data/lib/sip2/messages/patron_information.rb

@@ -1,16 +1,27 @@
+# frozen_string_literal: true
+
 module Sip2
   module Messages
     #
-    # Sip2 Patron information message module
+    # Sip2 Patron information message
     #
-    module PatronInformation
-      def self.included(klass)
-        klass.add_connection_module :patron_information
-      end
-
+    # https://developers.exlibrisgroup.com/wp-content/uploads/2020/01/3M-Standard-Interchange-Protocol-Version-2.00.pdf
+    #
+    # Request message 63
+    #  * language               - 3 char, fixed-length required field
+    #  * transaction date       - 18 char, fixed-length required field: YYYYMMDDZZZZHHMMSS
+    #  * summary                - 10 char, fixed-length required field
+    #  * institution id    - AO - variable-length required field
+    #  * patron identifier - AA - variable-length required field
+    #  * terminal password - AC - variable-length optional field
+    #  * patron password   - AD - variable-length optional field
+    #  * start item        - BP - variable-length optional field
+    #  * end item          - BQ - variable-length optional field
+    #
+    class PatronInformation < Base
       private
 
-      def build_patron_information_message(uid, password, terminal_password = nil)
+      def build_message(uid:, password:, terminal_password: nil)
         code = '63' # Patron information
         language = '000' # Unknown
         timestamp = Time.now.strftime('%Y%m%d    %H%M%S')
@@ -21,10 +32,10 @@ module Sip2
         ].join
       end
 
-      def handle_patron_information_response(response)
-        return unless sequence_and_checksum_valid?(response)
+      def handle_response(response)
+        return unless /\A#{Sip2::Responses::PatronInformation::RESPONSE_ID}/o.match?(response)
 
-        Sip2::PatronInformation.new response
+        Sip2::Responses::PatronInformation.new response
       end
     end
   end

data/lib/sip2/messages/status.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Sip2
+  module Messages
+    #
+    # Sip2 Patron information message
+    #
+    # https://developers.exlibrisgroup.com/wp-content/uploads/2020/01/3M-Standard-Interchange-Protocol-Version-2.00.pdf
+    #
+    # Request message 99
+    #  * status code      - 1 char, fixed-length required field: 0, 1 or 2
+    #  * max print width  - 3 char, fixed-length required field
+    #  * protocol version - 4 char, fixed-length required field: x.xx
+    #
+    class Status < Base
+      STATUS_CODE_LOOKUP = {
+        ok: 0,
+        out_of_paper: 1,
+        about_to_shut_down: 2
+      }.freeze
+
+      private
+
+      def build_message(status_code: :ok, max_print_width: 999, protocol_version: 2)
+        [
+          '99', # SC Status
+          normalize_status_code(status_code),
+          normalize_print_width(max_print_width),
+          normalize_protocol_version(protocol_version)
+        ].join
+      end
+
+      def normalize_status_code(code)
+        format(
+          '%<code>d',
+          code: (code.is_a?(Symbol) ? STATUS_CODE_LOOKUP[code] : code).to_i.abs
+        )[0]
+      end
+
+      def normalize_print_width(width)
+        format('%03<width>d', width: width % 1000)
+      end
+
+      def normalize_protocol_version(version)
+        format('%.2<version>f', version: version % 10)
+      end
+
+      def handle_response(response)
+        return unless /\A#{Sip2::Responses::Status::RESPONSE_ID}/o.match?(response)
+
+        Sip2::Responses::Status.new response
+      end
+    end
+  end
+end

data/lib/sip2/non_blocking_socket.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'socket'
 require 'timeout'
 
@@ -8,24 +10,11 @@ module Sip2
   #
   class NonBlockingSocket < Socket
     DEFAULT_TIMEOUT = 5
-    SEPARATOR = "\r".freeze
 
     attr_accessor :connection_timeout
 
-    def send_with_timeout(message, separator = SEPARATOR)
-      ::Timeout.timeout (connection_timeout || DEFAULT_TIMEOUT), WriteTimeout do
-        send message + separator, 0
-      end
-    end
-
-    def gets_with_timeout(separator = SEPARATOR)
-      ::Timeout.timeout (connection_timeout || DEFAULT_TIMEOUT), ReadTimeout do
-        gets separator
-      end
-    end
-
     # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-    def self.connect(host, port, timeout = DEFAULT_TIMEOUT)
+    def self.connect(host:, port:, timeout: DEFAULT_TIMEOUT)
       # Convert the passed host into structures the non-blocking calls can deal with
       addr = Socket.getaddrinfo(host, nil)
       sockaddr = Socket.pack_sockaddr_in(port, addr[0][3])
@@ -41,13 +30,13 @@ module Sip2
           # indicating the connection is in progress.
           socket.connect_nonblock(sockaddr)
         rescue IO::WaitWritable
-          # IO.select will block until the socket is writable or the timeout
-          # is exceeded - whichever comes first.
-          if IO.select(nil, [socket], nil, timeout)
+          # wait_writable waits until the socket is writable without blocking,
+          # and returns self or `nil` when times out
+          if socket.wait_writable(timeout)
             begin
               # Verify there is now a good connection
               socket.connect_nonblock(sockaddr)
-            rescue Errno::EISCONN # rubocop:disable Lint/HandleExceptions
+            rescue Errno::EISCONN
               # Good news everybody, the socket is connected!
             rescue StandardError
               # An unexpected exception was raised - the connection is no good.
@@ -55,7 +44,7 @@ module Sip2
               raise
             end
           else
-            # IO.select returns nil when the socket is not ready before timeout
+            # wait_writable returns nil when the socket is not ready before timeout
             # seconds have elapsed
             socket.close
             raise ConnectionTimeout

data/lib/sip2/responses/base.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Sip2
+  module Responses
+    #
+    # Sip2 Base response
+    #
+    class Base
+      attr_reader :raw_response
+
+      def initialize(raw_response)
+        @raw_response = raw_response
+      end
+
+      TIME_ZONE_LOOKUP_TABLE = {
+        '-12:00' => %w[Y],
+        '-11:00' => %w[X BST],
+        '-10:00' => %w[W HST BDT],
+        '-09:00' => %w[V YST HDT],
+        '-08:00' => %w[U PST YDT],
+        '-07:00' => %w[T MST PDT],
+        '-06:00' => %w[S CST MDT],
+        '-05:00' => %w[R EST CDT],
+        '-04:00' => %w[Q AST EDT],
+        '-03:00' => %w[P ADT],
+        '-02:00' => %w[O],
+        '-01:00' => %w[N],
+        '+00:00' => %w[Z GMT WET],
+        '+01:00' => %w[A CET BST],
+        '+02:00' => %w[B EET],
+        '+03:00' => %w[C],
+        '+04:00' => %w[D],
+        '+05:00' => %w[E],
+        '+06:00' => %w[F],
+        '+07:00' => %w[G],
+        '+08:00' => %w[H SST WST],
+        '+09:00' => %w[I JST],
+        '+10:00' => %w[K JDT],
+        '+11:00' => %w[L],
+        '+12:00' => %w[M NZST],
+        '+13:00' => %w[NZDT]
+      }.freeze
+
+      LANGUAGE_LOOKUP_TABLE = {
+        '000' => 'Unknown',
+        '001' => 'English',
+        '002' => 'French',
+        '003' => 'German',
+        '004' => 'Italian',
+        '005' => 'Dutch',
+        '006' => 'Swedish',
+        '007' => 'Finnish',
+        '008' => 'Spanish',
+        '009' => 'Danish',
+        '010' => 'Portuguese',
+        '011' => 'Canadian-French',
+        '012' => 'Norwegian',
+        '013' => 'Hebrew',
+        '014' => 'Japanese',
+        '015' => 'Russian',
+        '016' => 'Arabic',
+        '017' => 'Polish',
+        '018' => 'Greek',
+        '019' => 'Chinese',
+        '020' => 'Korean',
+        '021' => 'North American Spanish',
+        '022' => 'Tamil',
+        '023' => 'Malay',
+        '024' => 'United Kingdom',
+        '025' => 'Icelandic',
+        '026' => 'Belgian',
+        '027' => 'Taiwanese'
+      }.freeze
+
+      protected
+
+      DATE_MATCH_REGEX = '(\d{4})(\d{2})(\d{2})(.{4})(\d{2})(\d{2})(\d{2})'
+
+      def parse_fixed_response(position, count = 1)
+        raw_response[/\A#{self.class::RESPONSE_ID}.{#{position}}(.{#{count}})/, 1]
+      end
+
+      def parse_fixed_boolean(position)
+        parse_fixed_response(position) == 'Y'
+      end
+
+      def parse_optional_boolean(message_id)
+        raw_response[/(?:\A.{#{self.class::FIXED_LENGTH_CHARS}}|\|)#{message_id}([YN])\|/, 1] == 'Y'
+      end
+
+      def parse_text(message_id)
+        raw_response[/(?:\A.{#{self.class::FIXED_LENGTH_CHARS}}|\|)#{message_id}(.*?)\|/, 1]
+      end
+
+      def parse_datetime(position)
+        match = raw_response.match(/\A#{self.class::RESPONSE_ID}.{#{position}}#{DATE_MATCH_REGEX}/)
+        return unless match
+
+        _, year, month, day, zone, hour, minute, second = match.to_a
+        Time.new(
+          year.to_i, month.to_i, day.to_i,
+          hour.to_i, minute.to_i, second.to_i,
+          offset_from_zone(zone)
+        )
+      end
+
+      def offset_from_zone(zone)
+        zone.strip!
+        lookup = TIME_ZONE_LOOKUP_TABLE.find { |_, v| v.include? zone }
+        lookup ? lookup.first : '+00:00'
+      end
+    end
+  end
+end