triannon-client 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 441323f7e1dd09f5f178e4cf69616de6b83b3412
-  data.tar.gz: a7ad7fb1d115be0de670a307e0c590adfebd7350
+  metadata.gz: fa133f38dd35b61695e30ed8efec553ea53711dd
+  data.tar.gz: 751821968feed148b466c6e88686ec2aa2f8b6a5
 SHA512:
-  metadata.gz: fbf5b789df0b9efc5e034d145cfe6e2ef89951f5c6e0851db138e2e37ac0ea9e14b244f0311ab6cdca41909b116c8f2b3d9c8f6ac9c4b3214a617d081f16418d
-  data.tar.gz: 600389b5a8483bfeda17b81c7536663a70bdfc3b5f2f4bb8f1769392e8a7cdc3dbf4c8a2e2dd16f885fd2667f3084fb44993b84dd32a9987e2ab29425aaa0633
+  metadata.gz: 1d13a81a4e7f7931ab25acd7b722ed22631d8f07b2ca4f31010ef4b925a7c219540f55f0e4a477baa8861fc6da0eeff3ac13da0f6977c7bc2d8c705eea69aedf
+  data.tar.gz: 93179351efed9e2f834f69c81fcf872e658960263ba2a38f87d828d8f4c7053832a4efaf12bbf634c3989c8ff14c5c10bae4c7faace3a04f42870c478ebc6e4f

data/.env_example

@@ -12,7 +12,21 @@ export TRIANNON_LOG_FILE='log/triannon_client.log'
 
 # Configure the triannon service
 export TRIANNON_HOST='http://localhost:3000'
-export TRIANNON_USER=''
-export TRIANNON_PASS=''
+
+# Parameters for triannon client authentication
+export TRIANNON_CLIENT_ID=''
+export TRIANNON_CLIENT_PASS=''
+
+# Parameters for triannon container
 export TRIANNON_CONTAINER='/annotations/foo'
+export TRIANNON_CONTAINER_USER=''
+export TRIANNON_CONTAINER_WORKGROUPS=''
+
 
+# The following configuration settings in comments may work with the triannon
+# server setup on localhost and running the 'development' config.
+#export TRIANNON_CLIENT_ID='clientA'
+#export TRIANNON_CLIENT_PASS='secretA'
+#export TRIANNON_CONTAINER='/annotations/bar'
+#export TRIANNON_CONTAINER_USER='test'
+#export TRIANNON_CONTAINER_WORKGROUPS='org:wg-A'

data/.rspec

@@ -0,0 +1 @@
+--color

data/README.md

@@ -21,7 +21,7 @@ gem 'triannon-client'
 
 Then execute:
 
-```console
+```sh
 bundle
 ```
 
@@ -31,21 +31,28 @@ bundle
 ### Configuration
 
 Edit a `.env` file to configure the triannon server address etc.
-(see .env_example); or use a configure block, e.g.
+(see .env_example); or use a configure block.  The configuration
+for authentication depends on prior triannon server configuration.
+This example configuration may work with a triannon server running on localhost in the development environment (see below for details).
 
 ```ruby
 require 'triannon-client'
+::TriannonClient.reset
 ::TriannonClient.configure do |config|
-  config.debug = true
-  config.host = 'http://triannon.example.org:8080'
-  config.user = 'authUser'
-  config.pass = 'secret'
-  container   = '/annotations/'
+  config.debug = false
+  config.host = 'http://localhost:3000'
+  config.client_id = 'clientA'
+  config.client_pass = 'secretA'
+  config.container = '/annotations/bar'
+  config.container_user = ''
+  config.container_workgroups = 'org:wg-A, org:wg-B'
 end
 ```
 
 ### Get a client instance
 
+A new instance is initialized using the configuration parameters (see above).
+
 ```ruby
 tc = TriannonClient::TriannonClient.new
 ```
@@ -56,7 +63,7 @@ tc = TriannonClient::TriannonClient.new
 # return an RDF::Graph
 graph = tc.get_annotations
 anno_uris = tc.annotation_uris(graph)
-anno_ids = anno_uris.collect {|uri| tc.annotation_id(uri) }
+anno_ids = anno_uris.map {|uri| tc.annotation_id(uri) }
 ```
 
 ### Get a particular annotation
@@ -91,24 +98,48 @@ id = tc.annotation_id(uri) #=> "45%2F4a%2Fc0%2F93%2F454ac093-b37d-4580-bebd-449f
 tc.delete_annotation(id)
 ```
 
-Note: the annotation URI contains a pair-tree path (created by a Fedora 4 repository for 
-triannon annotations).  The annotation ID is the entire pair-tree path, after a URI escape.
-The URI escape makes it easier to work with the ID for tc.get_annotation(id) and 
-tc.delete_annotation(id).  For more information on object storage using pair-trees, see
+Note: the annotation URI contains a pair-tree path (created by a Fedora 4 repository for triannon annotations).  The annotation ID is the entire pair-tree path, after a URI escape. The URI escape makes it easier to work with the ID for `tc.get_annotation(id)` and `tc.delete_annotation(id)`.  For more information on object storage using pair-trees, see
   - http://www.slideshare.net/jakkbl/dcc-pair-posterppt
   - https://wiki.ucop.edu/display/Curation/PairTree
 
 ## Development
 
-Clone and install:
+#### Clone and install:
 
-```console
-./bin/setup.sh
+```sh
+git clone https://github.com/sul-dlss/triannon-client.git
+cd triannon-client
+./bin/setup.sh  # runs bundle install
 ```
 
-Run tests:
+#### Run tests:
 
-```console
-./bin/test.sh
+```sh
+rake
 ```
 
+The server request/response cycle has been recorded in `spec/fixtures/vcr_cassettes` (see http://www.relishapp.com/vcr).
+
+#### Tests with live server interactions
+
+- Startup a triannon server running on localhost in the development environment (the `spec/spec_helper.rb` is configured to interact with this server). For details on running triannon in development, see
+  - https://gist.github.com/darrenleeweber/bcfc9698ce5f5af8f465 
+  - https://github.com/sul-dlss/triannon#running-this-code-in-development 
+
+```sh
+git clone https://github.com/sul-dlss/triannon.git
+git clone https://gist.github.com/bcfc9698ce5f5af8f465.git triannon_reset
+cp ./triannon_reset/triannon_server_reset.sh triannon/bin/
+cd triannon
+./bin/triannon_server_reset.sh
+# GO GET A TASTY BEVERAGE ;-)
+```
+
+- Run the triannon client specs against the localhost server.
+```sh
+git clone https://github.com/sul-dlss/triannon-client.git
+cd triannon-client
+./bin/setup.sh  # bundle update and package
+rm -rf spec/fixtures/vcr_cassettes
+rake
+```

data/Rakefile

@@ -1,7 +1,20 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:spec)
 
 desc 'Default: run specs.'
-task :default => :spec
-task :specs => :spec
+task :default => :ci
+
+desc 'Run specs (without .env file)'
+task :ci do
+  # Manage .env file around specs.
+  FileUtils.mv '.env', '.env_bak', force: true
+  Rake::Task['spec'].invoke
+  FileUtils.mv '.env_bak', '.env', force: true
+end

data/lib/triannon-client.rb

@@ -1,15 +1,20 @@
 require 'dotenv'
 Dotenv.load
-# The pry dependency must be available when the client is configured to
-# run in debug mode, where it will fall into a pry console for rescue blocks.
-require 'pry'
-require 'pry-doc'
+
+# pry must be available when the client is configured to run in debug mode,
+# where it will fall into a pry console for rescue blocks.
+if ENV['DEBUG']
+  require 'pry'
+  require 'pry-doc'
+end
+
 # require rest client prior to linkeddata, so the latter can use it.
 require 'rest-client'
 # If a proxy is present, RestClient needs explicit configuration to use it.
 # (The ruby stdlib http client will use a proxy automatically.)
 RestClient.proxy = ENV['http_proxy'] unless ENV['http_proxy'].nil?
 RestClient.proxy = ENV['HTTP_PROXY'] unless ENV['HTTP_PROXY'].nil?
+
 require 'linkeddata'
 require_relative 'triannon-client/configuration'
 require_relative 'triannon-client/triannon_client'
@@ -18,9 +23,9 @@ require_relative 'triannon-client/triannon_client'
 # working with open annotations in a Triannon server, see
 # https://github.com/sul-dlss/triannon
 module TriannonClient
-  # configuration at the module level, see
-  # http://brandonhilkert.com/blog/ruby-gem-configuration-patterns/
 
+  # Configuration at the module level, see
+  # http://brandonhilkert.com/blog/ruby-gem-configuration-patterns/
   class << self
     attr_writer :configuration
   end
@@ -36,4 +41,5 @@ module TriannonClient
   def self.configure
     yield(configuration)
   end
+
 end

data/lib/triannon-client/configuration.rb

@@ -5,40 +5,52 @@ module TriannonClient
 
     attr_accessor :debug
     attr_accessor :logger
+    attr_reader :log_file
 
+    # Parameters for triannon server
     attr_accessor :host
-    attr_accessor :user
-    attr_accessor :pass
+    # attr_accessor :user # triannon doesn't support basic auth
+    # attr_accessor :pass # triannon doesn't support basic auth
+
+    # Parameters for triannon container
     attr_accessor :container
+    attr_accessor :container_user
+    attr_accessor :container_workgroups
+
+    # Parameters for triannon client authentication
+    attr_accessor :client_id
+    attr_accessor :client_pass
 
     def initialize
       @debug = env_boolean('DEBUG')
 
       @host = ENV['TRIANNON_HOST'] || 'http://localhost:3000'
-      @user = ENV['TRIANNON_USER'] || ''
-      @pass = ENV['TRIANNON_PASS'] || ''
+      # @user = ENV['TRIANNON_USER'] || '' # triannon doesn't support basic auth
+      # @pass = ENV['TRIANNON_PASS'] || '' # triannon doesn't support basic auth
+
+      # Parameters for triannon client authentication
+      @client_id   = ENV['TRIANNON_CLIENT_ID'] || ''
+      @client_pass = ENV['TRIANNON_CLIENT_PASS'] || ''
+
+      # Parameters for triannon container
       @container = ENV['TRIANNON_CONTAINER'] || ''
       @container += '/' unless(@container.empty? || @container.end_with?('/'))
+      @container_user = ENV['TRIANNON_CONTAINER_USER'] || ''
+      @container_workgroups = ENV['TRIANNON_CONTAINER_WORKGROUPS'] || ''
 
       # logger
-      log_file = ENV['TRIANNON_LOG_FILE'] || 'triannon_client.log'
-      log_file = File.absolute_path log_file
-      @log_file = log_file
-      log_path = File.dirname log_file
-      unless File.directory? log_path
-        # try to create the log directory
-        Dir.mkdir log_path rescue nil
-      end
       begin
+        log_file = ENV['TRIANNON_LOG_FILE'] || 'log/triannon_client.log'
+        @log_file = File.absolute_path log_file
+        FileUtils.mkdir_p File.dirname(@log_file) rescue nil
         log_dev = File.new(@log_file, 'w+')
       rescue
         log_dev = $stderr
         @log_file = 'STDERR'
       end
       log_dev.sync = true if @debug # skip IO buffering in debug mode
-      @logger = Logger.new(log_dev, 'monthly')
+      @logger = Logger.new(log_dev, 'weekly')
       @logger.level = @debug ? Logger::DEBUG : Logger::INFO
-
     end
 
     def env_boolean(var)

data/lib/triannon-client/triannon_client.rb

@@ -13,66 +13,117 @@ module TriannonClient
     CONTENT_TYPE_OA   = "#{JSONLD_TYPE}; profile=\"#{PROFILE_OA}\""
 
     attr_reader :config
+    attr_accessor :auth
     attr_accessor :site
     attr_accessor :container
 
     # Initialize a new triannon client
-    # All params are optional, the defaults are set in
-    # the ::TriannonClient.configuration
-    # @param host [String] HTTP URI for triannon server
-    # @param user [String] Authorized username for access to triannon server
-    # @param pass [String] Authorized password for access to triannon server
-    # @param container [String] The container path on the triannon server
-    def initialize(host=nil, user=nil, pass=nil, container=nil)
+    # All params are set using ::TriannonClient.configuration
+    def initialize
       # Configure triannon-app service
       @config = ::TriannonClient.configuration
-      host ||= @config.host
+      host = @config.host
       host.chomp!('/') if host.end_with?('/')
-      user ||= @config.user
-      pass ||= @config.pass
       @site = RestClient::Resource.new(
         host,
-        user: user,
-        password: pass,
+        cookies: {},
+        headers: jsonld_payloads,
         open_timeout: 5,
         read_timeout: 30
       )
-      container ||= @config.container
+      @auth = @site['/auth']
+      container = @config.container
       container = "/#{container}"  unless container.start_with?('/')
       container =  "#{container}/" unless container.end_with?('/')
       @container = @site[container]
     end
 
+    # Reset authentication
+    def authenticate!
+      @access_expiry = nil
+      authenticate
+    end
+
+    def authenticate
+      if @access_expiry.to_i < Time.now.to_i
+        @access_code = nil
+        @site.headers.delete :Authorization
+        @site.options[:cookies] = {}
+      end
+      @access_code || begin
+        # 1. Obtain a client authorization code (short-lived token)
+        return false if @config.client_id.empty? && @config.client_pass.empty?
+        client = {
+          clientId: @config.client_id,
+          clientSecret: @config.client_pass
+        }
+        response = @auth["/client_identity"].post client.to_json, json_payloads
+        @auth.options[:cookies] = response.cookies  # save the cookie data
+        return false unless response.code == 200
+        auth = JSON.parse(response.body)
+        auth_code = auth['authorizationCode']
+        return false if auth_code.nil?
+        # 2. The client POSTs user credentials for a container, which modifies
+        #    content in the cookies.
+        return false if @config.container_user.empty? && @config.container_workgroups.empty?
+        user = {
+          userId: @config.container_user,
+          workgroups: @config.container_workgroups
+        }
+        client_auth = "?code=#{auth_code}"
+        response = @auth["/login#{client_auth}"].post user.to_json, json_payloads
+        @auth.options[:cookies] = response.cookies  # save the cookie data
+        return false unless response.code == 200
+        # 3. The client, on behalf of user, obtains a long-lived access token.
+        response = @auth["/access_token#{client_auth}"].get # no content type
+        @auth.options[:cookies] = response.cookies  # save the cookie data
+        return false unless response.code == 200
+        access = JSON.parse(response.body)
+        return false if access['accessToken'].nil?
+        @access_code = "Bearer #{access['accessToken']}"
+        @access_expiry = Time.now.to_i + access['expiresIn'].to_i
+        @site.headers[:Authorization] = @access_code
+      end
+    end
+
     # Delete an annotation
     # @param id [String] an annotation ID
     # @response [true|false] true when successful
     def delete_annotation(id)
       check_id(id)
+      tries = 0
       begin
+        tries += 1
+        authenticate if tries == 2
         response = @container[id].delete
         # HTTP DELETE response codes: A successful response SHOULD be
         # 200 (OK) if the response includes an entity describing the status,
         # 202 (Accepted) if the action has not yet been enacted, or
         # 204 (No Content) if the action has been enacted but the response
         # does not include an entity.
-        [200, 202, 204].include?(response.code)
+        return [200, 202, 204].include?(response.code)
       rescue RestClient::Exception => e
+        msg = e.message
         response = e.response
         if response.is_a?(RestClient::Response)
-          # If an annotation doesn't exist, consider the request a 'success'
-          return true if [404, 410].include?(response.code)
+          case response.code
+          when 401
+            retry if tries == 1
+          when 403
+            # DELETE is not authorized
+          when 404, 410
+            # If an annotation doesn't exist, consider it a 'success'
+            return true
+          end
           msg = response.body
-        else
-          msg = e.message
         end
         @config.logger.error("Failed to DELETE annotation: #{id}, #{msg}")
         binding.pry if @config.debug
-        false
       rescue => e
         binding.pry if @config.debug
         @config.logger.error("Failed to DELETE annotation: #{id}, #{e.message}")
-        false
       end
+      false
     end
 
     # POST and open annotation to triannon; the response contains an ID
@@ -87,16 +138,23 @@ module TriannonClient
       tries = 0
       begin
         tries += 1
-        response = @container.post post_data, :content_type => JSONLD_TYPE, :accept => JSONLD_TYPE
+        authenticate if tries == 2
+        response = @container.post post_data
       rescue RestClient::Exception => e
-        sleep 1*tries
-        retry if tries < 3
+        msg = e.message
         response = e.response
+        if response.is_a?(RestClient::Response)
+          case response.code
+          when 401
+            retry if tries == 1
+          when 403
+            # POST is not authorized
+          end
+          msg = "Failed to POST annotation: #{response.code}, #{response.body}"
+        end
         binding.pry if @config.debug
-        @config.logger.error("Failed to POST annotation: #{response.code}, #{response.body}")
+        @config.logger.error(msg)
       rescue => e
-        sleep 1*tries
-        retry if tries < 3
         binding.pry if @config.debug
         @config.logger.error("Failed to POST annotation: #{e.message}")
       end
@@ -107,17 +165,26 @@ module TriannonClient
     # @param content_type [String] HTTP mime type (defaults to 'application/ld+json')
     # @response [RDF::Graph] RDF::Graph of open annotations (can be empty on failure)
     def get_annotations(content_type=JSONLD_TYPE)
-      check_content_type(content_type)
+      content_type = check_content_type(content_type)
+      g = RDF::Graph.new
       begin
         response = @container.get({:accept => content_type})
-        # TODO: switch yard for different response.code?
-        # TODO: log a failure for a response.code == 404
-        response2graph(response)
+        g = response2graph(response)
       rescue => e
+        msg = e.message
+        r = e.response rescue nil
+        if r.is_a?(RestClient::Response)
+          case r.code
+          when 404
+            msg = "Failed to GET annotations: #{r.code}"
+          else
+            msg = "Failed to GET annotations: #{r.code}, #{r.body}"
+          end
+        end
         binding.pry if @config.debug
-        @config.logger.error("Failed to GET annotations: #{e.message}")
-        RDF::Graph.new # return an empty graph
+        @config.logger.error(msg)
       end
+      g
     end
 
     # Get an annotation (with a default annotation context)
@@ -126,16 +193,26 @@ module TriannonClient
     # @response [RDF::Graph] RDF::Graph of the annotation (can be empty on failure)
     def get_annotation(id, content_type=JSONLD_TYPE)
       check_id(id)
-      check_content_type(content_type)
+      content_type = check_content_type(content_type)
+      g = RDF::Graph.new
       begin
         response = @container[id].get({:accept => content_type})
-        # TODO: switch yard for different response.code?
-        response2graph(response)
+        g = response2graph(response)
       rescue => e
+        msg = e.message
+        r = e.response rescue nil
+        if r.is_a?(RestClient::Response)
+          case r.code
+          when 404
+            msg = "Failed to GET annotation: #{id}, #{r.code}"
+          else
+            msg = "Failed to GET annotation: #{id}, #{r.code}, #{r.body}"
+          end
+        end
         binding.pry if @config.debug
-        @config.logger.error("Failed to GET annotation: #{id}, #{e.message}")
-        RDF::Graph.new # return an empty graph
+        @config.logger.error(msg)
       end
+      g
     end
 
     # Get an annotation using a IIIF context
@@ -152,22 +229,31 @@ module TriannonClient
       get_annotation(id, CONTENT_TYPE_OA)
     end
 
-    # Parse a Triannon response into an RDF::Graph
+    # Parse a Triannon response into an RDF::Graph; the graph can be empty
+    # on failure to parse input.  The response must contain a content-type that
+    # is available in RDF::Format.content_types (see code specs for details).
     # @param response [RestClient::Response] A RestClient::Response from Triannon
     # @response graph [RDF::Graph] An RDF::Graph instance
     def response2graph(response)
       unless response.is_a? RestClient::Response
-        raise ArgumentError, 'response must be a RestClient::Response'
+        raise ArgumentError, 'response2graph only accepts a RestClient::Response'
       end
       content_type = response.headers[:content_type]
-      check_content_type(content_type)
+      content_type = check_content_type(content_type)
       g = RDF::Graph.new
       begin
-        format = RDF::Format.for(:content_type => content_type)
-        format.reader.new(response) do |reader|
-          reader.each_statement {|s| g << s }
+        case content_type
+        when /ld\+json/
+          g = RDF::Graph.new.from_jsonld(response.body)
+        when /turtle/
+          g = RDF::Graph.new.from_ttl(response.body)
+        else
+          format = RDF::Format.for(:content_type => content_type)
+          format.reader.new(response.body) do |reader|
+            reader.each_statement {|s| g << s }
+          end
         end
-      rescue
+      rescue => e
         binding.pry if @config.debug
         @config.logger.error("Failed to parse response into RDF::Graph: #{e.message}")
       end
@@ -198,6 +284,7 @@ module TriannonClient
     def check_content_type(content_type)
       type = content_type.split(';').first # strip off any parameters
       raise ArgumentError, CONTENT_ERROR unless CONTENT_TYPES.include? type
+      type
     end
 
     def check_id(id)
@@ -205,6 +292,14 @@ module TriannonClient
       raise ArgumentError, 'Invalid ID' if id.nil? || id.empty?
     end
 
+    def json_payloads
+      { accept: :json, content_type: :json }
+    end
+
+    def jsonld_payloads
+      { accept: JSONLD_TYPE, content_type: JSONLD_TYPE }
+    end
+
   end
 
 end