sip2 0.0.11 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 62a9c7e482b7366879f24572357834bbbb0f4749
-  data.tar.gz: 15a6885fdd4355ef88a7015c9f3f09fa28c10005
+SHA256:
+  metadata.gz: 11edbd7e4605f2e348428819ca7045156eca4b95a34161c6a38b0aef0a3e7846
+  data.tar.gz: 854ee00429be13cc04ab99229dccdfc1a7055e106542d1e9c36c5f05a8d7b236
 SHA512:
-  metadata.gz: ba0270c5be9a2c2b776da93aa2b4e75739722e84b0d0a4c245c6ca001f0d083ceff7345d7963718521a557d1f0f1ad6299b5391cce1bd5f4d9d39f8affb017fa
-  data.tar.gz: 6b9bcfd1f82b8f407c47acfb79e01836acd895b43f94cedf2b9733efaf0e23ac08d45bf37f98f9609f6f5e203c6e97d13db4a1a9ab750f3833faabcf44a0ec0c
+  metadata.gz: 277765cd44b1086cda50dfb35393adaa25ff466e3c1cfb02ee2dd723471be68125b052b4741ab1178c6139c4c12571b31a95faa7d1fbc52058f075c676208fb2
+  data.tar.gz: 62016708c1636bf81aaf39fcab683c241a472339d28285411716414bcc57dbf1238cf97d2c8eab2de103f6c6e5d23fccb8a6a66eb90865bec3b27ccb287473fd

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.rb

@@ -1,14 +1,25 @@
+# frozen_string_literal: true
+
 require 'sip2/version'
 
-require 'sip2/patron_information'
+require 'openssl'
+
+require 'sip2/responses/base'
+require 'sip2/responses/patron_information'
+require 'sip2/responses/status'
 
+require 'sip2/messages/base'
 require 'sip2/messages/login'
 require 'sip2/messages/patron_information'
+require 'sip2/messages/status'
 
 module Sip2
   class TimeoutError < StandardError; end
+
   class ConnectionTimeout < TimeoutError; end
+
   class WriteTimeout < TimeoutError; end
+
   class ReadTimeout < TimeoutError; end
 end
 

data/lib/sip2/client.rb

@@ -1,19 +1,35 @@
+# frozen_string_literal: true
+
 module Sip2
   #
   # Sip2 Client
   #
   class Client
-    def initialize(host:, port:, ignore_error_detection: false)
+    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
-      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,56 +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 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)
-      if Connection.connection_modules.include?(method_name.to_sym)
-        send_and_handle_message(method_name, *args)
-      else
+      message_class = Messages::Base.message_class_for_method(method_name)
+      if message_class.nil?
         super
+      else
+        message_class.new(self).action_message(*args)
       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?
-      send "handle_#{message_type}_response", response
+    def write_with_timeout(message, separator: LINE_SEPARATOR)
+      ::Timeout.timeout connection_timeout, WriteTimeout do
+        @socket.write message + separator
+      end
     end
 
-    def send_message(message)
-      @socket.send_with_timeout message
-      @socket.gets_with_timeout
+    def read_with_timeout(separator: LINE_SEPARATOR)
+      ::Timeout.timeout connection_timeout, ReadTimeout do
+        @socket.gets(separator)&.chomp(separator)
+      end
+    end
+
+    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)
@@ -63,18 +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
-      sequence_regex = /^(?<message>.*?AY(?<sequence>[0-9]+)AZ)(?<checksum>[A-F0-9]{4})$/
+      return false unless response.is_a? String
+
+      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,9 +32,10 @@ module Sip2
         ].join
       end
 
-      def handle_patron_information_response(response)
-        return unless sequence_and_checksum_valid?(response)
-        Sip2::PatronInformation.new response
+      def handle_response(response)
+        return unless /\A#{Sip2::Responses::PatronInformation::RESPONSE_ID}/o.match?(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