handle-system 0.0.3

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in handle.gemspec
+gemspec
+gem 'simplecov', group: :development

data/LICENSE.txt

@@ -0,0 +1,34 @@
+HANDLE RUBY GEM
+===============
+Copyright (c) 2013 Michael Klein
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+HANDLE SYSTEM AND JAVA LIBRARIES
+================================
+HANDLE SYSTEM, HANDLE.NET, HDL, HDL.NET, and GLOBAL HANDLE REGISTRY are trademarks owned by CNRI. 
+
+Copyright © Corporation for National Research Initiatives 2013; All Rights Reserved.
+
+Made available under the Handle System Public License Agreement v.2 
+< http://hdl.handle.net/4263537/5030 >

data/README.md

@@ -0,0 +1,57 @@
+# Handle [![Build Status](https://secure.travis-ci.org/mbklein/handle.png)](http://travis-ci.org/mbklein/handle)
+
+Classes and methods for dealing with [Handle System](http://handle.net/) servers and handles. 
+
+## Platform Notes
+
+`Handle::Connection` and `Handle::Persistence` have two implementations each – one for JRuby,
+and one for everything else. Under JRuby, it calls Java HSAdapter methods directly. Under MRI 
+or other non-JVM rubies, it shells out to command line tools (particularly `hdl-qresolver` 
+and `hdl-genericbatch`) behind the scenes to do its work.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'handle'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install handle
+
+## Usage
+
+```ruby
+require 'handle'
+
+# Set up an authenticated connection
+conn = Handle::Connection.new('0.NA/admin.handle', 300, 
+  '/path/to/private/key/file', 'privkey-passphrase')
+
+# Create an empty record
+record = conn.create_record('handle.prefix/new.handle')
+
+# Two ways to add fields
+record.add(:URL, 'http://example.edu/').index = 2
+record.add(:Email, 'someone@example.edu').index = 6
+record << Handle::Field::HSAdmin.new('0.NA/admin.handle')
+
+# Manipulate permissions
+record.last.perms.public_read = false
+
+record.save
+
+record = conn.resolve_handle('handle.prefix/new.handle')
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,28 @@
+require "bundler/gem_tasks"
+require 'rake/tasklib'
+require 'rdoc/task'
+
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = FileList['./spec/**/*_spec.rb']
+end
+  
+task :default => :spec
+
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "handle #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/lib/handle/command/connection.rb

@@ -0,0 +1,134 @@
+require 'tempfile'
+
+module Handle
+  module Command
+    HDL_HOME = ENV['HDL_HOME'] || '/usr/local/handle'
+
+    class Batch
+      def initialize(handle, index, auth)
+        @batch_file = Tempfile.new('hdl') 
+        auth_type = auth.length == 2 ? "PUBKEY" : "SECKEY"
+        @batch_file.puts "AUTHENTICATE #{auth_type}:#{index}:#{handle}"
+        @batch_file.puts auth.select { |p| not (p.nil? or p.empty?) }.join('|')
+      end
+
+      def cleanup
+        @batch_file.close unless @batch_file.closed?
+        @batch_file.unlink
+      end
+
+      def execute!
+        @batch_file.close
+        cmd = File.join(HDL_HOME, 'bin', 'hdl-genericbatch')
+        output = `#{cmd} #{@batch_file.path} 2>/dev/null`
+        results = output.lines.select { |line| line =~ /^=+>/ }
+        results.each do |rs|
+          (status, message) = rs.scan(/^=+>(.+)\[[0-9]+\]: (.+)/).flatten
+          (action, handle, code, message) = message.split(/:\s*/,4)
+          if status == 'FAILURE'
+            exception = Handle::HandleError.new message
+            exception.set_backtrace(caller[3..-1])
+            raise exception
+          end
+        end
+        return true
+      end
+
+      def add_handle_values(handle, record)
+        @batch_file.puts "\nADD #{handle}"
+        @batch_file.puts record.to_batch
+      end
+
+      def create_handle(handle, record)
+        @batch_file.puts "\nCREATE #{handle}"
+        @batch_file.puts record.to_batch
+      end
+
+      def delete_handle(handle)
+        @batch_file.puts "\nDELETE #{handle}"
+      end
+
+      def delete_handle_values(handle, record)
+        indexes = record.collect(&:index).join(',')
+        @batch_file.puts "\nREMOVE #{indexes}:#{handle}"
+      end
+
+      def update_handle_values(handle, record)
+        @batch_file.puts "\nMODIFY #{handle}"
+        @batch_file.puts record.to_batch
+      end
+    end
+
+    class Connection
+      def initialize(handle, index, *auth, &block)
+        @handle = handle
+        @index  = index
+        @auth_params = auth
+        if block_given?
+          batch &block
+        end
+      end
+
+      def batch
+        context = Batch.new(@handle, @index, @auth_params)
+        begin
+          yield context
+          result = context.execute!
+        ensure
+          context.cleanup
+        end
+        result
+      end
+
+      def add_handle_values(*args)
+        batch { |b| b.add_handle_values(*args) }
+      end
+
+      def create_handle(*args)
+        batch { |b| b.create_handle(*args) }
+      end
+
+      def delete_handle(*args)
+        batch { |b| b.delete_handle(*args) }
+      end
+
+      def delete_handle_values(*args)
+        batch { |b| b.delete_handle_values(*args) }
+      end
+
+      def update_handle_values(*args)
+        batch { |b| b.update_handle_values(*args) }
+      end
+
+      def create_record(handle)
+        result = Handle::Record.new
+        result.connection = self
+        result.handle = handle
+        result
+      end
+
+      def resolve_handle(handle, types=[], indexes=[], auth=true)
+        cmd = File.join(HDL_HOME, 'bin', 'hdl-qresolver')
+        response = `#{cmd} #{handle} 2>/dev/null`.strip
+        if response =~ /^Got Response:/
+          response = response.lines.select { |line| line =~ /^\s*index=/ }.join("")
+          result = Handle::Record.from_data(response)
+          result.connection = self
+          result.handle = handle
+          result
+        else
+          (code, message) = response.lines.to_a.last.scan(/Error\(([0-9]+)\): (.+)$/).flatten
+          exception_klass = case code.to_i
+          when 100 then Handle::NotFound
+          else          Handle::HandleError
+          end
+          exception = exception_klass.new message
+          exception.set_backtrace(caller)
+          raise exception
+        end
+      end
+
+    end
+  end
+  Connection = Command::Connection
+end

data/lib/handle/command/persistence.rb

@@ -0,0 +1,57 @@
+module Handle
+  module Command
+    module Persistence
+      attr_accessor :handle, :connection
+
+      def to_batch
+        self.collect do |field|
+          perm_params = field.perms.to_s
+          data_type = case field.class.value_type
+          when 'HS_ADMIN'  then 'ADMIN'
+          when 'HS_SITE'   then 'FILE'
+          when 'HS_PUBKEY' then 'FILE'
+          else 'UTF8'
+          end
+          "#{field.index} #{field.class.value_type} #{field.ttl} #{perm_params} #{data_type} #{field.value_str}"
+        end
+      end
+
+      def reload
+        self.initialize_with(connection.resolve_handle(self.handle).fields)
+      end
+
+      def save(new_handle=nil)
+        save_handle = new_handle || self.handle
+        if save_handle.nil?
+          raise Handle::HandleError.new("No handle provided.")
+        end
+
+        if save_handle == self.handle
+          begin
+            original = connection.resolve_handle(save_handle)
+            actions = original | self
+            actions.each_value { |v| v.connection = connection }
+            [:delete,:update,:add].each do |action|
+              unless actions[action].empty?
+                connection.send("#{action}_handle_values".to_sym, save_handle, actions[action])
+              end
+            end
+          rescue Handle::NotFound
+            connection.create_handle(save_handle, self)
+            @handle = save_handle
+          end
+        else
+          connection.create_handle(save_handle, self)
+          @handle = save_handle
+        end
+        self
+      end
+
+      def destroy
+        connection.delete_handle(self.handle)
+      end
+    end
+  end
+  Persistence = Command::Persistence
+end
+

data/lib/handle/command.rb

@@ -0,0 +1,2 @@
+require 'handle/command/connection'
+require 'handle/command/persistence'

data/lib/handle/field/admin.rb

@@ -0,0 +1,79 @@
+module Handle
+  module Field
+    class HSAdmin < Base
+      value_type 'HS_ADMIN'
+      default_index 100
+
+      attr_accessor :admin_handle
+      attr :admin_perms, :admin_index
+
+      def initialize(handle=nil)
+        super()
+        @admin_handle = handle
+        @admin_index = 300
+        @admin_perms = Handle::Permissions.new(
+          :add_handle, :delete_handle, :add_na, :delete_na, 
+          :modify_values, :remove_values, :add_values, :read_values, 
+          :modify_admin, :remove_admin, :add_admin, :list_handles, 
+        )
+        @admin_perms.bitmask = 0b111111111111
+      end
+
+      def value
+        values = [self.admin_perms.bitmask, 0, 13, self.admin_handle, 0, self.admin_index]
+        values.pack('nnnZ*cn')
+      end
+
+      def value_str
+        [self.admin_index,self.admin_perms.to_s,self.admin_handle].join(':')
+        #value.bytes.collect { |b| '%2.2X' % b }.join('')
+      end
+
+      def value=(bytes)
+        if bytes =~ /^([0-9]+):([01]+):(.+)$/
+          self.admin_index = $1.to_i
+          self.admin_perms.bitmask = $2.to_i(2)
+          self.admin_handle = $3
+        else
+          if bytes =~ /^[0-9A-Fa-f]+$/
+            bytes = bytes.scan(/../).map(&:hex).pack('C*')
+          end
+          values = bytes.unpack('nnnZ*cn')
+          self.admin_perms.bitmask = values[0]
+          self.admin_handle = values[3]
+          self.admin_index = values[5] unless values[5].nil? or values[5] == 0
+        end
+      end
+
+      def to_h
+        result = super.merge({
+          admin_handle: self.admin_handle,
+          admin_index:  self.admin_index,
+          admin_perms:  self.admin_perms.bitmask
+        })
+        result.delete(:value)
+        result
+      end      
+
+      def to_s
+        " index=#{self.index} type=#{self.class.value_type} ttl=#{self.ttl} #{self.perms} #{value_str.inspect}"
+      end
+
+      def admin_index=(value)
+        @admin_index = value.to_i
+      end
+
+      def merge!(hash)
+        hash.each_pair do |key,value|
+          k = key.to_sym
+          self.perms.bitmask = value if k == :perms
+          self.admin_perms.bitmask = value if k == :admin_perms
+          if [:admin_handle, :admin_index, :index, :ttl, :value].include? k
+            self.send(:"#{k.to_s}=", value)
+          end
+        end
+        self
+      end
+    end
+  end
+end

data/lib/handle/field.rb

@@ -0,0 +1,125 @@
+module Handle
+  module Field
+    class Base    
+      attr_accessor :value
+      attr :index, :ttl, :perms
+
+      class << self
+        @@value_types = {}
+        def value_type val=nil
+          if val
+            if @value_type
+              @@value_types.delete(@value_type)
+            end
+            @value_type = val
+            @@value_types[val] = self
+          end
+          @value_type
+        end
+
+        def default_index val=nil
+          val ? @default_index = val : @default_index
+        end
+
+        def from_hash(hash)
+          type = hash.values_at(:type,'type').compact.first
+          if @@value_types.has_key? type
+            klass = @@value_types[type]
+            result = klass.new
+            result.merge!(hash)
+          end
+        end
+
+        def from_string(str)
+          attrs, perms, data = str.scan(/^\s*(.+) ([10rw\-]+) "(.+)"$/).flatten
+          attrs = attrs.split(/\s+/).inject({}) { |hash,attr| 
+            (k,v) = attr.split(/\=/,2) 
+            hash[k.to_sym] = v
+            hash
+          }
+          type = attrs.delete(:type)
+          if @@value_types.has_key? type
+            klass = @@value_types[type]
+            result = klass.new
+            result.merge!(attrs)
+            result.perms.bitmask = perms.gsub(/./) { |m| m =~ /[0\-]/ ? '0' : '1' }.to_i(2)
+            result.value = data
+            result
+          else
+            nil
+          end
+        end
+
+        def from_data(data)
+          if data.is_a?(Hash)
+            self.from_hash(data)
+          else
+            self.from_string(data.to_s)
+          end
+        end
+      end
+
+      def initialize
+        @index = self.class.default_index
+        @ttl = 86400
+        @perms = Handle::Permissions.new(:admin_read, :admin_write, :public_read, :public_write, 0b1110)
+      end
+
+      def ==(other)
+        self.to_s == other.to_s
+      end
+
+      def index=(value)
+        @index = value.to_i
+      end
+
+      def ttl=(value)
+        @ttl = value.to_i
+      end
+
+      def merge!(hash)
+        hash.each_pair do |key,value|
+          k = key.to_sym
+          value = value.to_i if [:perms,:index].include?(k)
+          self.perms.bitmask = value if k == :perms
+          if [:index, :ttl, :value].include? k
+            self.send(:"#{k.to_s}=", value)
+          end
+        end
+        self
+      end
+
+      def to_h
+        {
+          index: self.index,
+          type:  self.class.value_type,
+          ttl:   self.ttl,
+          perms: self.perms.bitmask,
+          value: self.value
+        }
+      end
+
+      def to_json *args
+        self.to_h.to_json *args
+      end
+
+      def to_s
+        " index=#{self.index} type=#{self.class.value_type} ttl=#{self.ttl} #{self.perms} #{self.value.inspect}"
+      end
+
+      def value_str
+        value.to_s
+      end
+    end
+
+    class URL      < Base ; value_type 'URL'        ; end
+    class URN      < Base ; value_type 'URN'        ; end
+    class Email    < Base ; value_type 'EMAIL'      ; end
+    class HSSite   < Base ; value_type 'HS_SITE'    ; end
+    class HSServ   < Base ; value_type 'HS_SERV'    ; end
+    class HSAlias  < Base ; value_type 'HS_ALIAS'   ; end
+    class HSPubKey < Base ; value_type 'HS_PUB_KEY' ; default_index 300 ; end
+    class HSSecKey < Base ; value_type 'HS_SEC_KEY' ; default_index 301 ; end
+    class HSVList  < Base ; value_type 'HS_VLIST'   ; default_index 400 ; end
+  end
+end

data/lib/handle/java/connection.rb

@@ -0,0 +1,95 @@
+module Handle
+  module Java
+    class Connection
+      # A more Ruby-ish HSAdapter
+
+      def initialize(handle, index, *auth)
+        # accept either a key file or the key itself
+        if auth.length == 2 and (not auth[0].bytes.to_a.include?(0)) and File.exists?(auth[0])
+          auth[0] = File.read(auth[0])
+        end
+        auth_params = auth.collect { |p| p.to_java_bytes }
+        protect {
+          @conn = Native::HSAdapterFactory.new_instance(handle, index, *auth_params)
+        }
+      end
+
+      def add_handle_values(handle, record)
+        protect {
+          @conn.addHandleValues(handle, record.to_java)
+        }
+      end
+
+      def create_handle(handle, record)
+        protect {
+          @conn.createHandle(handle, record.to_java)
+        }
+      end
+
+      def create_record(handle)
+        result = Handle::Record.new
+        result.connection = self
+        result.handle = handle
+        result
+      end
+
+      def delete_handle(handle)
+        protect {
+          @conn.deleteHandle(handle)
+        }
+      end
+
+      def delete_handle_values(handle, record)
+        protect {
+          @conn.deleteHandleValues(handle, record.to_java)
+        }
+      end
+
+      def resolve_handle(handle, types=[], indexes=[], auth=true)
+        protect {
+          java_response = @conn.resolveHandle(
+            handle, types.to_java(:string), 
+            indexes.to_java(:int), auth
+          )
+          result = Handle::Record.from_data(java_response)
+          result.connection = self
+          result.handle = handle
+          result
+        }
+      end
+
+      def use_udp=(value)
+        protect {
+          @conn.setUseUDP(value)
+        }
+      end
+
+      def update_handle_values(handle, record)
+        protect {
+          @conn.updateHandleValues(handle, record.to_java)
+        }
+      end
+
+      def native
+        @conn
+      end
+
+      protected
+      def protect
+        begin
+          response = yield
+        rescue Native::HandleException => err
+          exception_klass = case err.getCode()
+          when 9 then Handle::NotFound
+          else        Handle::HandleError
+          end
+          exception = exception_klass.new err.message
+          exception.set_backtrace(caller)
+          raise exception
+        end
+        response.nil? ? true : response
+      end
+    end
+  end
+  Connection = Java::Connection
+end

data/lib/handle/java/persistence.rb

@@ -0,0 +1,54 @@
+module Handle
+  module Java
+    module Persistence
+      attr_accessor :handle, :connection
+
+      def to_java
+        result = self.collect do |field|
+          perm_params = field.perms.to_bool
+          Native::HandleValue.new(field.index.to_java(:int), field.class.value_type.to_java_bytes, 
+            field.value.to_java_bytes, Native::HandleValue::TTL_TYPE_RELATIVE.to_java(:byte), 
+            field.ttl.to_java(:int), 0.to_java(:int), nil, *perm_params)
+        end
+        result.to_java(Native::HandleValue)
+      end
+
+      def reload
+        self.initialize_with(connection.resolve_handle(self.handle).fields)
+      end
+
+      def save(new_handle=nil)
+        save_handle = new_handle || self.handle
+        if save_handle.nil?
+          raise Handle::HandleError.new("No handle provided.")
+        end
+
+        if save_handle == self.handle
+          begin
+            original = connection.resolve_handle(save_handle)
+            actions = original | self
+            actions.each_value { |v| v.connection = connection }
+            [:delete,:update,:add].each do |action|
+              unless actions[action].empty?
+                connection.send("#{action}_handle_values".to_sym, save_handle, actions[action])
+              end
+            end
+          rescue Handle::NotFound
+            connection.create_handle(save_handle, self)
+            @handle = save_handle
+          end
+        else
+          connection.create_handle(save_handle, self)
+          @handle = new_handle
+        end
+        self
+      end
+
+      def destroy
+        connection.delete_handle(self.handle)
+      end
+    end
+  end
+  Persistence = Java::Persistence
+end
+

data/lib/handle/java.rb

@@ -0,0 +1,18 @@
+require 'java'
+# Load all jarfiles in $HDL_HOME/lib
+hdl_home = ENV['HDL_HOME'] || File.expand_path('../../../vendor/handle',__FILE__)
+Dir[File.join(hdl_home,'lib','*.jar')].each { |f| require f }
+
+module Handle
+  module Java
+    module Native
+      java_import     'net.handle.hdllib.HandleException'
+      java_import     'net.handle.hdllib.HandleValue'
+      java_import     'net.handle.api.HSAdapter'
+      java_import     'net.handle.api.HSAdapterFactory'
+    end
+  end
+end
+
+require 'handle/java/connection'
+require 'handle/java/persistence'