qa-ldf 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 855a7a374246e7b3deb9e2a05f275a7e1ac4b39b
-  data.tar.gz: 6fceb2d6ec1511192f388a7da4edcd37b223088a
+  metadata.gz: 4e5b26feeb2a751f305e34082e074a5599325599
+  data.tar.gz: 68ac921385f139cf2e261d7c3fb63d2ce88eb81e
 SHA512:
-  metadata.gz: e3c38a54bd7ec95604666dc08113e18d8f240976b21f2d39dbb40445d954455860dbf79494dd4811083e754494864fd54cd78582f4707b53f7dfdbc23a8e976e
-  data.tar.gz: 951a494528c90e84f66df9747a810e3b9a0a92fb9a6643058e91de475885b3b42c8d12017295daaa918e7c3ebefc3c165776ef7ddd881370301749c49ac7392f
+  metadata.gz: 7a7b32a4a9406d1974bf2c1c960bac71f337f9d48b0477c03bddf5006db7bd58b07d93e4b06ed01781262e297e83ff7291789b7f0f9ede08e480750463a039f6
+  data.tar.gz: 69041a0dda760ad8b2e84543db5f7ecb9e7795aa9fb6663bf6a740268ca6d28112a4e4329a37291b4fbb0658210020f7cbce29d3379030fcd409c0c67c10bf52

data/.rubocop.yml

@@ -5,6 +5,7 @@ AllCops:
 
 Metric/BlockLength:
   Exclude:
+    - 'qa-ldf.gemspec'
     - 'spec/**/*'
     - 'lib/qa/ldf/spec/**/*'
 

data/README.md

@@ -2,40 +2,86 @@ QuestioningAuthority::LDF
 =========================
 [![Apache 2.0 License](http://img.shields.io/badge/APACHE2-license-blue.svg)](./LICENSE)
 
-Providies bindings from [Questioning Authority](https://github.com/projecthydra-labs/questioning_authority) to the [linked data caching fragment server](https://github.com/ActiveTriples/linked-data-fragments) for fast query of RDF-based authorities.
+This sofware providies bindings from [Questioning Authority](https://github.com/projecthydra-labs/questioning_authority) to the [linked data caching fragment server](https://github.com/ActiveTriples/linked-data-fragments) for fast query of RDF-based authorities.
 
 What Does This Do?
 ------------------
 
-Provides a caching version of the [Questioning Authority](https://github.com/projecthydra-labs/questioning_authority) interface relying on the ActiveTriples LDF caching service.
+This gem offers a caching version of the [Questioning Authority](https://github.com/projecthydra-labs/questioning_authority) interface relying on the ActiveTriples LDF caching service. A set of linked data "authorities" are exposed through the Questioning Authority API, and cached for fast recall using the Linked Data Fragments Caching Server. Models on the Hydra/Rails side are provided to handle caching and easy presentation of labels.
 
-[TK] Why use this?
+Both the QA and LDF APIs are available in mountable forms, so they can run directly in your Hydra application---see below for details.
 
-Upcoming features include:
+### Why use this?
+
+The main reason you may be interested in this software is to handle local caching of linked data references in your metadata.
+
+### Upcoming features include:
 
   - Support for `Qa::Authority::Base#all` for all LDF authorities through [Hydra Core Partial Collection View](http://www.hydra-cg.com/spec/latest/core/#hydra:PartialCollectionView) style paging.
-  - A default search, accessing cached items.
+  - A default search, accessing only cached items.
 
 How Does it Work?
 -----------------
 
 ### [TK] Architecture Overview.
-### [TK] Mounting and configuring the LDF caching server.
-### [TK] LDF caching as an external service.
-### [TK] Configuring authorities.
+### Mounting and configuring the LDF caching server
+
+The LDF caching server can run as a mounted application within Rails. To use the caching server, add the following to your `Gemfile`:
+
+```ruby
+gem 'qa-ldf', '~>0.2.0'
+
+# for now use the active branch of the linked data caching fragment server
+gem 'ld_cache_fragment', github: 'ActiveTriples/linked-data-fragments', branch: 'feature/multi-dataset'
+```
+
+Then you need to mount the application to an unused route:
+
+```ruby
+# config/routes.rb
+
+Rails.application.routes.draw do
+  # ...
+  mount LinkedDataFragments::CacheServer::APPLICATION => '/ldcache'
+  # ...
+end
+```
+
+### LDF caching as an external service.
+
+The LDF caching server can run independently from your Hydra application as a lightweight, generic [Rack](http://www.rubydoc.info/github/rack/rack/file/SPEC) application, or as a standalone Rails app. You may want to deploy the server in this way so it can run on separate hardware, or to segregate Linked Data "follow your nose" network traffic.
+
+The simplest way to get a working application that will run on any Rack-compatible server is to create a `./config.ru` containing:
+
+```ruby
+# ./config.ru
+require 'ld_cache_fragment/cache_server'
+
+run LinkedDataFragments::CacheServer::APPLICATION
+```
+
+With this in your working directory, you can run `$ rackup` to launch a basic server. More robust deployments are possible using servers like [Puma](https://github.com/puma/puma#rackup).
+
+#### [TK] LDF caching as a Rails app
+
+### Configuring authorities.
 #### [TK] Models.
 #### [TK] Forms.
 
-[TK] Authority Sources
+Authority Sources
 ----------------------
 
-### [TK] LCNAF
-### [TK] FAST
+### LCNAF
+
+The Library of Congress Name Authority File
+
+### FAST
+
+Faceted Application of Subject Terminology
 
 [TK] Implementing Custom Authorities
 ------------------------------------
 
-
 License
 -------
 

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.3.0

data/lib/qa/ldf/authorities.rb

@@ -1 +1,2 @@
+require 'qa/ldf/authorities/fast'
 require 'qa/ldf/authorities/lc_names'

data/lib/qa/ldf/authorities/fast.rb

@@ -0,0 +1,54 @@
+require 'qa/ldf/namespaced_search_service'
+
+# frozen_string_literal: true
+module Qa
+  module LDF
+    ##
+    # A caching OCLC Faceted Application of Subject Terminology (FAST)
+    # authority.
+    #
+    # @see LinkedDataFragments::CacheServer
+    # @see http://www.oclc.org/research/themes/data-science/fast.html
+    class FAST < Authority
+      DEFAULT_DATASET_NAME = :fast
+      NAMESPACE            = 'http://id.id.worldcat.org/fast/'.freeze
+
+      register_namespace(namespace: NAMESPACE,
+                         klass:     self)
+
+      ##
+      # A specialized NamespacedSearchService that strips 'fst' from fast IDs
+      class SearchService < NamespacedSearchService
+        private
+
+        def apply_namespace(id)
+          super(id.gsub('fst', ''))
+        end
+      end
+
+      ##
+      # @return [String] the URI namespace associated with this authority
+      def self.namespace
+        NAMESPACE
+      end
+
+      ##
+      # Uses the LC AssignFast 'all' subauthority as the search provider
+      def search_service
+        @search_service ||= NamespacedSearchService.new do |service|
+          service.namespace      = NAMESPACE
+          service.parent_service =
+            Qa::Authorities::AssignFast.subauthority_for('all')
+        end
+      end
+    end
+  end
+
+  ##
+  # Alias to hack Qa's namespaced authority logic.
+  #
+  # @see https://github.com/projecthydra-labs/questioning_authority/issues/137
+  module Authorities
+    Fast = LDF::FAST
+  end
+end

data/lib/qa/ldf/authorities/lc_names.rb

@@ -1,3 +1,5 @@
+require 'qa/ldf/namespaced_search_service'
+
 # frozen_string_literal: true
 module Qa
   module LDF
@@ -11,11 +13,24 @@ module Qa
     class LCNames < Authority
       DEFAULT_DATASET_NAME = :lcnames
       NAMESPACE            = 'http://id.loc.gov/authorities/names/'.freeze
-      LC_SUBAUTHORITY      = 'names'.freeze
 
       register_namespace(namespace: NAMESPACE,
                          klass:     self)
 
+      ##
+      # A specialized NamespacedSearchService that strips info: uris
+      #
+      # The basic QA LCNames authority returns the info: URIs, instead of the
+      # http: URIs as IDs. This handles conversion between the two.
+      # @note This is not resilient to ids other than LCNames info: uris
+      class SearchService < NamespacedSearchService
+        private
+
+        def apply_namespace(id)
+          super(id.split('/').last)
+        end
+      end
+
       ##
       # @return [String] the URI namespace associated with this authority
       def self.namespace
@@ -25,8 +40,11 @@ module Qa
       ##
       # Uses the LC names subauthority as the search provider
       def search_service
-        @search_service ||=
-          Qa::Authorities::Loc.subauthority_for(LC_SUBAUTHORITY)
+        @search_service ||= SearchService.new do |service|
+          service.namespace      = NAMESPACE
+          service.parent_service =
+            Qa::Authorities::Loc.subauthority_for('names')
+        end
       end
     end
   end

data/lib/qa/ldf/authority.rb

@@ -119,7 +119,7 @@ module Qa
       ##
       # Search the vocabulary
       #
-      # @param _query [String] the query string
+      # @param query [String] the query string
       #
       # @return [Array<Hash<Symbol, String>>] the response as a JSON friendly
       #   hash

data/lib/qa/ldf/client.rb

@@ -32,7 +32,7 @@ module Qa
         cache_uri = RDF::URI(Qa::LDF::Configuration.instance[:endpoint])
         cache_uri.query = "subject=#{uri}"
         cache_uri = cache_uri / 'dataset' / dataset unless dataset.empty?
-        cache_uri
+        cache_uri.dup
       end
     end
   end

data/lib/qa/ldf/model.rb

@@ -61,6 +61,23 @@ module Qa
         self
       end
 
+      ##
+      # @param language [Symbol] a two letter (BCP47) language tag.
+      #
+      # @see ActiveTriples::RDFSource.rdf_label
+      # @see https://www.w3.org/TR/rdf11-concepts/#section-Graph-Literal
+      # @see https://tools.ietf.org/html/bcp47
+      def lang_label(language: :en)
+        labels = rdf_label
+
+        label = labels.find do |literal|
+          literal.respond_to?(:language) && literal.language == language
+        end
+
+        return labels.first unless label
+        label
+      end
+
       class << self
         ##
         # Builds a model from the graph.
@@ -91,9 +108,9 @@ module Qa
         #   protected.
         def from_qa_result(qa_result:)
           qa_result.dup
-          model = new(qa_result.delete(:id))
+          model = new(qa_result.delete(:id.to_s))
           model.set_value(model.send(:default_labels).first,
-                          qa_result.delete(:label))
+                          qa_result.delete(:label.to_s))
 
           model
         end

data/lib/qa/ldf/namespaced_search_service.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+module Qa
+  module LDF
+    ##
+    # A search service that wraps another SearchService and casts its ids to a
+    # namespace.
+    #
+    # @example
+    #   nsify = Qa::LDF::NamespacedSearchService.new do |service|
+    #     service.namespace      = 'http://example.com/ns/'
+    #     service.parent_service = a_search_service_instance
+    #   end
+    #
+    #   # when
+    #   a_search_service_endpoint.search('moomin') # => { 'id' => 'blah' }
+    #
+    #   # then
+    #   nsify.search('moomin') # => { 'id' => 'http://example.com/ns/blah' }
+    #
+    class NamespacedSearchService
+      ##
+      # @!attribute [rw] namespace
+      #   @return [String]
+      # @!attribute [rw] parent_service
+      #   @return [#search]
+      attr_accessor :namespace, :parent_service
+
+      ##
+      # @yieldparam service [NamespacedSearchService] yields self
+      def initialize
+        yield self
+      end
+
+      ##
+      # @see Qa::Authority::Base#search
+      def search(query)
+        responses = parent_service.search(query)
+
+        responses.map do |result|
+          result['id'] = apply_namespace(result['id'])
+          result
+        end
+      end
+
+      def apply_namespace(id)
+        return id if RDF::URI(id).valid?
+        (RDF::URI(namespace) / id).to_s
+      end
+    end
+  end
+end

data/lib/qa/ldf/spec/authority.rb

@@ -113,7 +113,7 @@ shared_examples 'an ldf authority' do
 
   describe '#search' do
     let(:query)    { 'My Fake Query' }
-    let(:response) { { my: 'response' } }
+    let(:response) { [{ my: 'response' }] }
 
     it 'gives an array' do
       expect(authority.search('tove')).to respond_to :to_ary

data/lib/qa/ldf/spec/model.rb

@@ -49,7 +49,7 @@ shared_examples 'an ldf model' do
   end
 
   describe '.from_qa_result' do
-    let(:json_hash) { { id: id, label: label, papa: 'moomin papa' } }
+    let(:json_hash) { { 'id' => id, 'label' => label, 'snork' => 'snork' } }
 
     it 'builds a model with the id as uri' do
       expect(described_class.from_qa_result(qa_result: json_hash))

data/qa-ldf.gemspec

@@ -22,7 +22,8 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = '>= 2.2.2'
 
-  spec.add_dependency 'qa', '~> 0.11.0'
+  spec.add_dependency 'rdf', '>= 2.0', '< 2.2.4'
+  spec.add_dependency 'qa',  '~> 0.11.0'
 
   spec.add_development_dependency 'active-fedora',     '~> 11.0'
   spec.add_development_dependency 'guard',             '~> 2.14'

data/spec/qa/ldf/authorities/fast_spec.rb

@@ -0,0 +1,58 @@
+require 'spec_helper'
+
+describe Qa::LDF::FAST do
+  it_behaves_like 'an ldf authority'
+
+  subject(:authority) do
+    auth = described_class.new
+
+    auth.client = FakeClient.new do |client|
+      client.graph = RDF::Graph.new
+      client.graph.insert(*statements)
+      client.label = ldf_label
+    end
+
+    auth
+  end
+
+  let(:statements) do
+    [RDF::Statement(RDF::URI(ldf_uri),
+                    RDF::Vocab::SKOS.prefLabel,
+                    RDF::Literal(ldf_label))]
+  end
+
+  let(:ldf_label) { 'Jansson, Tove' }
+  let(:ldf_uri)   { 'http://id.worldcat.org/fast/34647' }
+
+  before do
+    # mock empty responses for all queries;
+    # @todo contract test AssignFast authority
+    body = <<-eos
+{
+  "responseHeader":{
+    "status":0,
+    "QTime":468,
+    "params":{
+      "fl":"suggestall,idroot,auth,type",
+      "q":"suggestall:nothing_to_see_here",
+      "rows":"20"
+     }
+   },
+  "response":{"numFound":0,"start":0,"docs":[]}
+}
+eos
+
+    stub_request(:get, 'http://fast.oclc.org/searchfast/fastsuggest?' \
+                       'query=tove&queryIndex=suggestall&' \
+                       'queryReturn=suggestall,idroot,auth,type&' \
+                       'rows=20&suggest=autoSubject')
+      .with(headers: { 'Accept' => 'application/json' })
+      .to_return(status: 200, body: body, headers: {})
+  end
+
+  describe '#dataset' do
+    it 'defaults to :fast' do
+      expect(described_class.new.dataset).to eq :fast
+    end
+  end
+end

data/spec/qa/ldf/authorities/lc_names_spec.rb

@@ -27,20 +27,38 @@ describe Qa::LDF::LCNames do
   before do
     # mock empty responses for all queries;
     # see spec/contracts/qa_loc_as_search_service.rb for lc search service tests
+    # @todo: test that correct handling of namespacing
     stub_request(:get, 'http://id.loc.gov/search/?format=json&' \
                        'q=cs:http://id.loc.gov/authorities/names')
       .with(headers: { 'Accept' => 'application/json' })
       .to_return(status: 200, body: '[]', headers: {})
   end
 
-  describe '#search_service' do
-    it 'hits the upstream loc endpoint by default' do
-      query = 'a query'
-      url   = 'http://id.loc.gov/search/?format=json' \
-              "&q=#{query}&q=cs:http://id.loc.gov/authorities/names"
-      expect(a_request(:get, url))
+  describe '#search' do
+    context 'with real search service' do
+      it 'hits the upstream loc endpoint' do
+        query = 'a query'
+        url   = 'http://id.loc.gov/search/?format=json' \
+                "&q=#{query}&q=cs:http://id.loc.gov/authorities/names"
+        expect(a_request(:get, url))
 
-      authority.search_service.search(query)
+        authority.search(query)
+      end
+    end
+
+    context 'with fake search service' do
+      let(:search_service) do
+        FakeSearchService.new { |service| service.queries = searches }
+      end
+
+      let(:searches) { { 'moomin' => results } }
+      let(:results)  { [{ id: 'moomin123', name: 'Moomin' }] }
+
+      before { authority.search_service = search_service }
+
+      it 'returns the values' do
+        expect(authority.search('moomin')).to contain_exactly(*results)
+      end
     end
   end
 

data/spec/qa/ldf/namespaced_search_service_spec.rb

@@ -0,0 +1,25 @@
+require 'spec_helper'
+
+require 'qa/ldf/namespaced_search_service'
+
+describe Qa::LDF::NamespacedSearchService do
+  it_behaves_like 'an ldf search service'
+
+  subject(:search_service) do
+    described_class.new do |service|
+      service.namespace      = namespace
+      service.parent_service = fake_service
+    end
+  end
+
+  let(:namespace)       { 'http://example.com/ns/' }
+  let(:parent_searches) { { query => parent_response } }
+  let(:parent_response) { [{ 'id' => 'id', 'key' => 'value' }] }
+  let(:searches)        { { query => response } }
+  let(:query)           { 'tove' }
+  let(:response)        { [{ 'id' => namespace + 'id', 'key' => 'value' }] }
+
+  let(:fake_service) do
+    FakeSearchService.new { |service| service.queries = parent_searches }
+  end
+end

metadata

@@ -1,15 +1,35 @@
 --- !ruby/object:Gem::Specification
 name: qa-ldf
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Tom Johnson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-03-02 00:00:00.000000000 Z
+date: 2017-03-16 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: rdf
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 2.2.4
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 2.2.4
 - !ruby/object:Gem::Dependency
   name: qa
   requirement: !ruby/object:Gem::Requirement
@@ -177,6 +197,7 @@ files:
 - config/ldf.yml
 - lib/qa/ldf.rb
 - lib/qa/ldf/authorities.rb
+- lib/qa/ldf/authorities/fast.rb
 - lib/qa/ldf/authorities/lc_names.rb
 - lib/qa/ldf/authority.rb
 - lib/qa/ldf/client.rb
@@ -184,6 +205,7 @@ files:
 - lib/qa/ldf/empty_search_service.rb
 - lib/qa/ldf/json_mapper.rb
 - lib/qa/ldf/model.rb
+- lib/qa/ldf/namespaced_search_service.rb
 - lib/qa/ldf/spec.rb
 - lib/qa/ldf/spec/authority.rb
 - lib/qa/ldf/spec/model.rb
@@ -192,6 +214,7 @@ files:
 - qa-ldf.gemspec
 - spec/contracts/qa_loc_as_search_service_spec.rb
 - spec/integration/active_fedora_model_spec.rb
+- spec/qa/ldf/authorities/fast_spec.rb
 - spec/qa/ldf/authorities/lc_names_spec.rb
 - spec/qa/ldf/authority_spec.rb
 - spec/qa/ldf/client_spec.rb
@@ -199,6 +222,7 @@ files:
 - spec/qa/ldf/empty_search_service_spec.rb
 - spec/qa/ldf/json_mapper_spec.rb
 - spec/qa/ldf/model_spec.rb
+- spec/qa/ldf/namespaced_search_service_spec.rb
 - spec/qa/ldf_spec.rb
 - spec/spec_helper.rb
 - spec/support/cache_server.rb
@@ -233,6 +257,7 @@ summary: Provides a bridge between questioning authority and a caching linked da
 test_files:
 - spec/contracts/qa_loc_as_search_service_spec.rb
 - spec/integration/active_fedora_model_spec.rb
+- spec/qa/ldf/authorities/fast_spec.rb
 - spec/qa/ldf/authorities/lc_names_spec.rb
 - spec/qa/ldf/authority_spec.rb
 - spec/qa/ldf/client_spec.rb
@@ -240,6 +265,7 @@ test_files:
 - spec/qa/ldf/empty_search_service_spec.rb
 - spec/qa/ldf/json_mapper_spec.rb
 - spec/qa/ldf/model_spec.rb
+- spec/qa/ldf/namespaced_search_service_spec.rb
 - spec/qa/ldf_spec.rb
 - spec/spec_helper.rb
 - spec/support/cache_server.rb