handle-system-rest 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80560da22c69f15df93fe8e75c12627751d4a67d2737d872677d7e6acca7eb3c
-  data.tar.gz: fc09852264bb245a026acfa8efe66fed8c6e85d71140064e120bda81a54326b8
+  metadata.gz: ed36556bd087f406808b48bfe9b178baf67601df43e0217edd92d82048248d95
+  data.tar.gz: 1a7720a452974ac4be21b59ef237f753e0b06b3a5f2c73bba6dff158e8a45c8f
 SHA512:
-  metadata.gz: 518f266900d680dcc2b826042187109fc7addd8f73a5395500e854be76619ec04d6e0c987737b322b0f4dd083ecc029cc7ce438141f0ae011d1d39cf1842884f
-  data.tar.gz: f29c169459e00f9374b8172f82337b9d1f5a6b220a4238ae1d384be2d72b1bf3c6e1d7097502adab74989ce82c84a9e15cc83bf88fa4c443521aa192a909b0ed
+  metadata.gz: a4658e4ce5b7cf369ae604ae99eb2ccee86eeba41cc2a88ea8b2fada1ae0b973ebcdf57c3d5100978abc08196c728b330ace29b7a04f1db01dd355e1ba9f1fe9
+  data.tar.gz: c4a250a09db5ce4a183b13ca90e8efaadf7db4ceb02647d95d1275c25e5c0b7ef317c6bc69af49bc338453b92f902b673a58ff6590787723b632f380724d8cfe

data/README.md

@@ -10,7 +10,7 @@ This library works with Handle System version 8 or higher.  For older versions o
 
 Before you start using the library, you need to convert your Handle server's private key into PEM format.  The Handle Server distribution directory (e.g., `/hs/handle-9.2.0`) has a utility, `hdl-convert-key`, for doing this.  Your private key (`admpriv.bin`) is in the server directory (e.g., `/hs/svr_1`).
 
-On the Handle server, Run this command to convert the file:
+On the Handle server, run this command to convert the file:
 
 ```
 /hs/handle-9.2.0/bin/hdl-convert-key /hs/svr_1/admpriv.bin -o /hs/svr_1/admpriv.pem

data/handle_system.gemspec

@@ -9,12 +9,12 @@ Gem::Specification.new do |spec|
   spec.email         = ['dwalker@calstate.edu']
 
   spec.summary       = 'A library for interfacing with the Handle System JSON REST API.'
-  spec.description   =  spec.summary + ' This gem works with Handle System ' +
-                        'version 8 or higher. For older versions of the ' +
-                        "Handle System, which didn't have a JSON API, " +
-                        'consider using the handle-system gem'
+  spec.description   = spec.summary + ' This gem works with Handle System ' +
+                       'version 8 or higher. For older versions of the ' +
+                       "Handle System, which didn't have a JSON API, " +
+                       'consider using the handle-system gem.'
   spec.homepage      = 'https://github.com/csuscholarworks/handle-system'
-  spec.license       = 'APACHE'
+  spec.license       = 'Apache-2.0'
   spec.required_ruby_version = Gem::Requirement.new('>= 2.5.0')
 
   spec.metadata['homepage_uri'] = spec.homepage

data/lib/handle_system/client.rb

@@ -13,9 +13,10 @@ module HandleSystem
     # @param [String] server         ip_address:port, e.g., 123.456.78.9:8000
     # @param [String] hs_admin       handle administrator
     # @param [String] priv_key_path  file path to private key
+    # @param [String] pass_phrase    [optional] pass phrase for private key
     #
-    def initialize(server, hs_admin, priv_key_path)
-      @http_client = HttpClient.new(server, hs_admin, priv_key_path)
+    def initialize(server, hs_admin, priv_key_path, pass_phrase = nil)
+      @http_client = HttpClient.new(server, hs_admin, priv_key_path, pass_phrase)
       @handle_base = 'http://hdl.handle.net/'
     end
 
@@ -24,29 +25,40 @@ module HandleSystem
     #
     # @param [String] handle    e.g., 20.500.12345/876
     # @param [String] url       the url we want to register
-    # @param [String] email     [optional] email address to add to record
-    # @param [String] hs_admin  [optional] handle administrator to add to record
+    # @param [String] email     [optional] email address
+    # @param [String] hs_admin  [optional] handle administrator
     #
     # @return [string] the new handle url at hdl.handle.net
     #
     def create(handle, url, email = nil, hs_admin = nil)
-      body = Record.new.from_values(handle, url, email, hs_admin).json
-      json = @http_client.put_it('/handles/' + handle, body)
-      @handle_base + json['handle']
+      set_record(handle, url, email, hs_admin, false)
     end
 
-    # creating and updating handle records is the same thing
-    alias update create
+    #
+    # Update an existing handle
+    #
+    # Will create a new handle if no record already exists
+    #
+    # @param [String] handle    e.g., 20.500.12345/876
+    # @param [String] url       the url we want to register
+    # @param [String] email     [optional] email address
+    # @param [String] hs_admin  [optional] handle administrator
+    #
+    # @return [string] the new handle url at hdl.handle.net
+    #
+    def update(handle, url, email = nil, hs_admin = nil)
+      set_record(handle, url, email, hs_admin, true)
+    end
 
     #
     # Return the full record for a handle
     #
     # @param [String] handle  handle identifier
     #
-    # @return [<JSON>] the handle record
+    # @return [HandleSystem::Record] the handle record
     #
     def get(handle)
-      json = @http_client.get_it('/handles/' + handle)
+      json = @http_client.get('/handles/' + handle)
       Record.new.from_json(json)
     end
 
@@ -58,8 +70,29 @@ module HandleSystem
     # @return [Boolean] true if we deleted the record
     #
     def delete(handle)
-      json = @http_client.delete_it('/handles/' + handle)
+      json = @http_client.delete('/handles/' + handle)
       return true if json['responseCode'] == 1
     end
+
+    protected
+
+    #
+    # Create or update a handle
+    #
+    # @param [String] handle     e.g., 20.500.12345/876
+    # @param [String] url        the url we want to register
+    # @param [String] email      [optional] email address to add to record
+    # @param [String] hs_admin   [optional] handle administrator
+    # @param [Boolean] overwrite [optional] overwrite any existing record?
+    #                              default: false
+    #
+    # @return [string] the new handle url at hdl.handle.net
+    #
+    def set_record(handle, url, email = nil, hs_admin = nil, overwrite = false)
+      body = Record.new.from_values(handle, url, email, hs_admin).json
+      url = '/handles/' + handle + '?overwrite=' + overwrite.to_s
+      json = @http_client.put(url, body)
+      @handle_base + json['handle']
+    end
   end
 end

data/lib/handle_system/exceptions.rb

@@ -11,20 +11,40 @@ module HandleSystem
     attr_reader :response_code
 
     # @return [String] the handle specified in the request
-    attr_reader :handle
+    attr_accessor :handle
+
+    # @return [String] the URL we sent that produced the error
+    attr_accessor :url
 
     #
     # New Handle server Error
     #
-    # @param [Integer] code    handle protocol response code for the message
-    # @param [String] handle   the handle specified in the request
-    # @param [String] message  error message
+    # @param [Integer] response_code  handle protocol response code for the message
+    # @param [String] message         error message
     #
-    def initialize(code, handle, message)
-      @response_code = code.to_int unless code.nil?
-      @handle = handle
+    def initialize(response_code, message)
+      @response_code = response_code.to_int unless response_code.nil?
       super(message)
     end
+
+    #
+    # Handle server response codes / description
+    #
+    # @return [Hash]  in the form of code => description
+    #
+    def self.response_codes
+      {
+        2 => 'An unexpected error on the server',
+        100 => 'Handle not found',
+        101 => 'Handle already exists',
+        102 => 'Invalid handle',
+        200 => 'Values not found',
+        201 => 'Value already exists',
+        202 => 'Invalid value',
+        301 => 'Server not responsible for handle',
+        402 => 'Authentication needed'
+      }
+    end
   end
 
   #

data/lib/handle_system/http_client.rb

@@ -23,10 +23,12 @@ module HandleSystem
     # @param [String] server         ip_address:port, e.g., 123.456.78.9:8000
     # @param [String] hs_admin       handle administrator
     # @param [String] priv_key_path  file path to private key
+    # @param [String] pass_phrase    [optional] pass phrase for private key
     #
-    def initialize(server, hs_admin, priv_key_path)
+    def initialize(server, hs_admin, priv_key_path, pass_phrase = nil)
       @hs_admin = hs_admin
       @private_key_path = priv_key_path
+      @pass_phrase = pass_phrase
       @base_url = 'https://' + server + '/api'
       @session_id = initialize_session
     end
@@ -39,11 +41,10 @@ module HandleSystem
     # @raise HandleSystem::Error  if we got an error from the server
     # @return [JSON]      parsed json response from handle server
     #
-    def get_it(path)
+    def get(path)
       url = @base_url + path
-      json = self.class.get(url, options).parsed_response
-      check_errors(json)
-      json
+      response = self.class.get(url, options)
+      process_response(url, response)
     end
 
     #
@@ -55,11 +56,10 @@ module HandleSystem
     # @raise HandleSystem::Error  if we got an error from the server
     # @return [JSON]      parsed json response from handle server
     #
-    def put_it(path, body)
+    def put(path, body)
       url = @base_url + path
-      json = self.class.put(url, body: body, **options).parsed_response
-      check_errors(json)
-      json
+      response = self.class.put(url, body: body, **options)
+      process_response(url, response)
     end
 
     #
@@ -70,19 +70,47 @@ module HandleSystem
     # @raise HandleSystem::Error  if we got an error from the server
     # @return [JSON]      parsed json response from handle server
     #
-    def delete_it(path)
+    def delete(path)
       url = @base_url + path
-      json = self.class.delete(url, options).parsed_response
-      check_errors(json)
-      json
+      response = self.class.delete(url, options)
+      process_response(url, response)
     end
 
     private
 
+    #
+    # Extract JSON from response, throw any errors we found
+    #
+    # @param [String] url the URL we sent
+    # @param [HttParty::Response] response
+    #
+    # @return [JSON] the json response from the server
+    #
+    def process_response(url, response)
+      json = response.parsed_response
+      response_code = json['responseCode']
+      return json unless response_code != 1
+
+      # we got an error response from the handle server, so convert it into
+      # an actual exception and throw it here
+
+      message = if json['message']
+                  json['message']
+                elsif Error.response_codes.include? response_code
+                  Error.response_codes[response_code]
+                else
+                  'Unexpected error'
+                end
+
+      error = Error.new(response_code, message)
+      error.handle = json['handle']
+      error.url = url
+      raise error
+    end
+
     #
     # Header and connection options
     #
-    # @raise HandleSystem::Error
     # @return [Hash]
     #
     def options
@@ -95,19 +123,6 @@ module HandleSystem
       }
     end
 
-    #
-    # If we got an error message from the handle server, convert it into
-    # an actual exception and throw it here
-    #
-    # @param [JSON] json  handle server json response
-    # @raise HandleSystem::Error
-    #
-    def check_errors(json)
-      return unless json['message']
-
-      raise Error.new(json['responseCode'], json['handle'], json['message'])
-    end
-
     #
     # Initialize a new session with the handle server using its
     # challenge-response framework
@@ -152,16 +167,17 @@ module HandleSystem
       combined_nonce = server_nonce + client_nonce
 
       # create combined nonce digest and sign with private key
-      private_key = OpenSSL::PKey::RSA.new(File.read(@private_key_path))
+      key_file = File.read(@private_key_path)
+      private_key = OpenSSL::PKey::RSA.new(key_file, @pass_phrase)
       signature = private_key.sign(OpenSSL::Digest::SHA256.new, combined_nonce)
 
       # build the authorization header
       header = 'Handle sessionId="' + session_id + '", ' \
-              'id="' + CGI.escape(@hs_admin) + '", ' \
-              'type="HS_PUBKEY", ' \
-              'cnonce="' + Base64.encode64(client_nonce) + '", ' \
-              'alg="SHA256", ' \
-              'signature="' + Base64.encode64(signature) + '"'
+               'id="' + CGI.escape(@hs_admin) + '", ' \
+               'type="HS_PUBKEY", ' \
+               'cnonce="' + Base64.encode64(client_nonce) + '", ' \
+               'alg="SHA256", ' \
+               'signature="' + Base64.encode64(signature) + '"'
       header.gsub("\n", '')
     end
   end

data/lib/handle_system/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HandleSystem
-  VERSION = '0.1.1'
+  VERSION = '0.1.2'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: handle-system-rest
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - David Walker
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-05-18 00:00:00.000000000 Z
+date: 2020-05-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -40,7 +40,7 @@ dependencies:
         version: '0'
 description: A library for interfacing with the Handle System JSON REST API. This
   gem works with Handle System version 8 or higher. For older versions of the Handle
-  System, which didn't have a JSON API, consider using the handle-system gem
+  System, which didn't have a JSON API, consider using the handle-system gem.
 email:
 - dwalker@calstate.edu
 executables: []
@@ -65,7 +65,7 @@ files:
 - lib/handle_system/version.rb
 homepage: https://github.com/csuscholarworks/handle-system
 licenses:
-- APACHE
+- Apache-2.0
 metadata:
   homepage_uri: https://github.com/csuscholarworks/handle-system
   source_code_uri: https://github.com/csuscholarworks/handle-system