qa 5.5.2 → 5.8.1

data/app/services/qa/pagination_service.rb

@@ -0,0 +1,586 @@
+module Qa
+  # Provide pagination processing used to respond to requests for paginated results.
+  #
+  # <b>Defaults for page_offset and page_limit:</b> (see example responses under #build_response)
+  #
+  # format == :json
+  #
+  # * if neither page_offset nor page_limit is passed in, then... (backward compatible)
+  #   * returns results as an Array<Hash>
+  #   * returns all results
+  #   * page_offset is "1"
+  #   * page_limit is total_num_found
+  #
+  # * if either page_offset or page_limit is passed in, then...
+  #   * returns results as an Array<Hash>
+  #   * returns a page of results
+  #   * default for page_offset is "1"
+  #   * default for page_limit is DEFAULT_PAGE_LIMIT (i.e., 10)
+  #
+  # format == :jsonapi
+  #
+  # * response is always in the jsonapi format
+  # * results are always paginated
+  # * default for page_offset is "1"
+  # * default for page_limit is DEFAULT_PAGE_LIMIT (i.e., 10)
+  #
+  # <b>How page_offset is calculated for pagination links:</b>
+  #
+  # expected page boundaries
+  #
+  # * Expected page boundaries are always calculated starting from page_offset=1
+  #   and the current page_limit.  The page boundaries will include the page_offsets
+  #   that cover all results.  For example, page_limit=10 with 36 results will have
+  #   page boundaries 1, 11, 21, 31.
+  #
+  # self url
+  #
+  # * The self url always has the page_offset for the current page, which defaults
+  #   to 1 if not passed in.
+  #
+  # first page url
+  #
+  # * The first page url always has page_offset=1.
+  #
+  # last page url
+  #
+  # * The last page url always has page_offset equal to the last of the expected page
+  #   boundaries regardless of the passed in page_offset.  For the example where
+  #   page_limit=10 with 36 results, the last page will always have page_offset=31.
+  #
+  # prev page url
+  #
+  # * Previous' page_offset is calculated from the passed in page_offset whether or
+  #   not it is on an expected page boundary.
+  #
+  # * For prev, page_offset = passed in page_offset - page_limit || nil if calculated as < 1
+  #   * when current page_offset (e.g. 1) is less than page_limit (e.g. 10), then page_offset
+  #     for prev will be nil (e.g. 1 - 10 = -9 which is < 1)
+  #   * when current page_offset is an expected page boundary (e.g. 21), then
+  #     page_offset for prev will also be a page boundary (e.g. 21 - 10 = 11
+  #     which is an expected page boundary)
+  #   * when current page_offset is not on an expected page boundary (e.g. 13), then
+  #     page_offset for prev will not be on an expected page boundary (e.g. 13 - 10 = 3
+  #     which is not an expected page boundary)
+  #
+  # next page url
+  #
+  # * Next's page_offset is calculated from the passed in page_offset whether or
+  #   not it is on an expected page boundary.
+  #
+  # * For next, page_offset = passed in page_offset + page_limit || nil if calculated > total number of results found
+  #   * when current page_offset (e.g. 31) is greater than total number of results (e.g. 36),
+  #     then page_offset for next will be nil (e.g. 31 + 10 = 41 which is > 36)
+  #   * when current page_offset is an expected page boundary (e.g. 21), then
+  #     page_offset for next will also be a page boundary (e.g. 21 + 10 = 31
+  #     which is an expected page boundary)
+  #   * when current page_offset is not on an expected page boundary (e.g. 13), then
+  #     page_offset for next will not be on an expected page boundary (e.g. 13 + 10 = 23
+  #     which is not an expected page boundary)
+  #
+  class PaginationService # rubocop:disable Metrics/ClassLength
+    # Default page_limit to use if not passed in with the request.
+    DEFAULT_PAGE_LIMIT = 10
+
+    # Error code for page_limit and page_offset when the value is not an integer.
+    ERROR_NOT_INTEGER = 901
+    # Error code for page_limit and page_offset when the value is below the acceptable range (e.g. < 1).
+    ERROR_OUT_OF_RANGE_TOO_SMALL = 902
+    # Error code for page_offset when the value is above the acceptable range (e.g. > total_num_found).
+    ERROR_OUT_OF_RANGE_TOO_LARGE = 903
+
+    # @param request [ActionDispatch::Request] The request from the controller.
+    #   To support pagination, it's params need to respond to:
+    #   * #page_offset [Integer] - the offset into the results for the start of the page (counts from 1; default: 1)
+    #   * #page_limit [Integer] - the max number of records to return in a page
+    #     * if format==:jsonapi, defaults to: DEFAULT_PAGE_LIMIT
+    #     * if page_offset is passed in, defaults to: DEFAULT_PAGE_LIMIT
+    #     * else when format==:json && page_offset.nil?, defaults to all results (backward compatible)
+    # @param results [Array<Hash>] results of a search query as processed by the authority module
+    # @param format [String] - if present, supported values are [:json | :jsonapi]
+    #     * when :json, the response is an array of results (default)
+    #     * when :jsonapi, the response follows the JSON API specification
+    #
+    # @see https://jsonapi.org/format/#fetching-pagination Pagination section of JSON API specification
+    # @see https://jsonapi.org/examples/#pagination JSON API example pagination
+    def initialize(request:, results:, format: :json)
+      @request = request
+      @results = results
+      @requested_format = format
+      @page_offset_error = false
+      @page_limit_error = false
+    end
+
+    # @return json results, optionally limited to requested page and optionally
+    #     formatted according to the JSON-API standard.  The default is to return
+    #     just the results for backward compatibility.  See examples.
+    #
+    # @example json without pagination (backward compatible) (used only if neither page_offset nor page_limit are passed in)
+    #   # request: q=term
+    #   # response: format=json, no pagination, all results
+    #   [
+    #     { "id": "1", "label": "term 1" },
+    #     { "id": "2", "label": "term 2" },
+    #     ...
+    #     { "id": "28", "label": "term 28" }
+    #   ]
+    #
+    # @example json with pagination (used if either page_offset or page_limit are passed in)
+    #   # request: q=term, page_offset=3, page_limit=2
+    #   # response: format=json, paginated, results 3..4
+    #   [
+    #     { "id": "3", "label": "term 3" },
+    #     { "id": "4", "label": "term 4" }
+    #   ]
+    #
+    # @example json-api with pagination using default page_offset and page_limit
+    #   # request: q=term, format=json-api
+    #   # response: format=json-api, paginated, results 1..10
+    #   {
+    #     "data": [
+    #       { "id": "1", "label": "term 1" },
+    #       { "id": "2", "label": "term 2" },
+    #       ...
+    #       { "id": "10", "label": "term 10" }
+    #     ],
+    #     "meta": {
+    #       "page": {
+    #         "page_offset": "1",
+    #         "page_limit": "10",
+    #         "actual_page_size": "10",
+    #         "total_num_found": "28",
+    #       }
+    #     }
+    #     "links": {
+    #       "self_url": "http://example.com/qa/search/local/states?q=new&format=json-api&page_limit=10&page_offset=1",
+    #       "first_url": "http://example.com/qa/search/local/states?q=new&format=json-api&page_limit=10&page_offset=1",
+    #       "prev_url": nil,
+    #       "next_url": "http://example.com/qa/search/local/states?q=new&format=json-api&page_limit=10&page_offset=11",
+    #       "last_url": "http://example.com/qa/search/local/states?q=new&format=json-api&page_limit=10&page_offset=21"
+    #     }
+    #   }
+    #
+    # @example json-api with pagination for page_offset=7 and page_limit=2
+    #   # request: q=term, format=json-api, page_offset=7, page_limit=2
+    #   # response: format=json, paginated, results 7..8
+    #   {
+    #     "data": [
+    #       { "id": "7", "label": "term 7" },
+    #       { "id": "8", "label": "term 8" }
+    #     ],
+    #     "meta": {
+    #       "page": {
+    #         "page_offset": "7",
+    #         "page_limit": "2",
+    #         "actual_page_size": "2",
+    #         "total_num_found": "28",
+    #       }
+    #     }
+    #     "links": {
+    #       "self_url": "http://example.com/qa/search/local/states?q=new&format=json-api&page_limit=2&page_offset=7",
+    #       "first_url": "http://example.com/qa/search/local/states?q=new&format=json-api&page_limit=2&page_offset=1",
+    #       "prev_url": "http://example.com/qa/search/local/states?q=new&format=json-api&page_limit=2&page_offset=5",
+    #       "next_url": "http://example.com/qa/search/local/states?q=new&format=json-api&page_limit=2&page_offset=9",
+    #       "last_url": "http://example.com/qa/search/local/states?q=new&format=json-api&page_limit=2&page_offset=27"
+    #     }
+    #   }
+    #
+    # @example json-api with page_offset and page_limit errors
+    #   # request: q=term, format=json-api, page_offset=0, page_limit=-1
+    #   # response: format=json-api, paginated, no results, errors
+    #   {
+    #     "data": [],
+    #     "meta": {
+    #       "page": {
+    #         "page_offset": "0",
+    #         "page_limit": "-1",
+    #         "actual_page_size": nil,
+    #         "total_num_found": "28",
+    #       }
+    #     }
+    #     "links": {
+    #       "self_url": "http://example.com/qa/search/local/states?q=new&format=json-api&page_limit=-1&page_offset=0",
+    #       "first_url": "http://example.com/qa/search/local/states?q=new&format=json-api&page_limit=10&page_offset=1",
+    #       "prev_url": nil,
+    #       "next_url": nil,
+    #       "last_url": "http://example.com/qa/search/local/states?q=new&format=json-api&page_limit=10&page_offset=21"
+    #     }
+    #     "errors": [
+    #       {
+    #         "status" => "200",
+    #         "source" => { "page_offset" => "0" },
+    #         "title" => "Page Offset Out of Range",
+    #         "detail" => "Offset 0 < 1 (first result).  Returning empty results."
+    #       },
+    #       {
+    #         "status" => "200",
+    #         "source" => { "page_limit" => "-1" },
+    #         "title" => "Page Limit Out of Range",
+    #         "detail" => "Page limit -1 < 1 (minimum limit).  Returning empty results."
+    #
+    #       }
+    #     ]
+    #   }
+    #
+    # @see DEFAULT_PAGE_LIMIT
+    # @see ERROR_NOT_INTEGER
+    # @see ERROR_OUT_OF_RANGE_TOO_SMALL
+    # @see ERROR_OUT_OF_RANGE_TOO_LARGE
+    def build_response
+      json_api? ? build_json_api_response : build_json_response
+    end
+
+    private
+
+      def errors?
+        page_offset_error? || page_limit_error?
+      end
+
+      def page_offset_error?
+        page_offset
+        @page_offset_error
+      end
+
+      def page_limit_error?
+        page_limit
+        @page_limit_error
+      end
+
+      # @return just the data as a JSON array
+      def build_json_response
+        errors? ? [] : build_data
+      end
+
+      # @return pages of results following the JSON API standard
+      def build_json_api_response
+        errors? ? build_json_api_response_with_errors : build_json_api_response_without_errors
+      end
+
+      def build_json_api_response_without_errors
+        {
+          "data" => build_data,
+          "meta" => build_meta,
+          "links" => build_links
+        }
+      end
+
+      def build_json_api_response_with_errors
+        {
+          "data" => [],
+          "meta" => build_meta,
+          "links" => build_links_when_errors,
+          "errors" => build_errors
+        }
+      end
+
+      def build_data
+        @results[start_index..last_index]
+      end
+
+      def build_meta
+        meta = {}
+        meta['page_offset'] = page_offset_error? ? @requested_page_offset.to_s : page_offset.to_s
+        meta['page_limit'] = page_limit_error? ? @requested_page_limit.to_s : page_limit.to_s
+        meta['actual_page_size'] = errors? ? "0" : actual_page_size.to_s
+        meta['total_num_found'] = total_num_found.to_s
+        { "page" => meta }
+      end
+
+      def build_links
+        links = {}
+        links['self'] = self_link
+        links['first'] = first_link
+        links['prev'] = prev_link
+        links['next'] = next_link
+        links['last'] = last_link
+        links
+      end
+
+      def build_links_when_errors
+        links = {}
+        links['self'] = "#{request_base_url}#{request_path}?#{request_query_string}"
+        links['first'] = first_link
+        links['prev'] = nil
+        links['next'] = nil
+        links['last'] = last_link
+        links
+      end
+
+      def build_errors
+        errors = []
+        errors << build_page_offset_error if page_offset_error?
+        errors << build_page_limit_error if page_limit_error?
+        errors
+      end
+
+      def build_page_offset_error
+        case @page_offset_error
+        when ERROR_NOT_INTEGER
+          build_page_offset_not_integer
+        when ERROR_OUT_OF_RANGE_TOO_LARGE
+          build_page_offset_too_large
+        when ERROR_OUT_OF_RANGE_TOO_SMALL
+          build_page_offset_too_small
+        end
+      end
+
+      def build_page_limit_error
+        case @page_limit_error
+        when ERROR_NOT_INTEGER
+          build_page_limit_not_integer
+        when ERROR_OUT_OF_RANGE_TOO_SMALL
+          build_page_limit_too_small
+        end
+      end
+
+      def build_page_offset_not_integer
+        {
+          "status" => "200",
+          "source" => { "page_offset" => @requested_page_offset },
+          "title" => "Page Offset Invalid",
+          "detail" => "Page offset #{@requested_page_offset} is not an Integer.  Returning empty results."
+        }
+      end
+
+      def build_page_offset_too_large
+        {
+          "status" => "200",
+          "source" => { "page_offset" => @requested_page_offset },
+          "title" => "Page Offset Out of Range",
+          "detail" => "Page offset #{@requested_page_offset} > #{total_num_found} (total number of results).  Returning empty results."
+        }
+      end
+
+      def build_page_offset_too_small
+        {
+          "status" => "200",
+          "source" => { "page_offset" => page_offset.to_s },
+          "title" => "Page Offset Out of Range",
+          "detail" => "Page offset #{@requested_page_offset} < 1 (first result).  Returning empty results."
+        }
+      end
+
+      def build_page_limit_not_integer
+        {
+          "status" => "200",
+          "source" => { "page_limit" => @requested_page_limit },
+          "title" => "Page Limit Invalid",
+          "detail" => "Page limit #{@requested_page_limit} is not an Integer.  Returning empty results."
+        }
+      end
+
+      def build_page_limit_too_small
+        {
+          "status" => "200",
+          "source" => { "page_limit" => @requested_page_limit.to_s },
+          "title" => "Page Limit Out of Range",
+          "detail" => "Page limit #{@requested_page_limit} < 1 (minimum limit).  Returning empty results."
+        }
+      end
+
+      def request_params
+        @request_params ||= @request.params
+      end
+
+      def request_query_params
+        @request_query_params ||= @request.query_parameters
+      end
+
+      def request_query_string
+        @request_query_string ||= @request.query_string
+      end
+
+      def request_base_url
+        @request_base_url ||= @request.base_url
+      end
+
+      def request_path
+        @request_path ||= @request.path
+      end
+
+      # @return [Boolean] true if results should be formatted according to JSON API standard
+      def json_api?
+        format == :jsonapi
+      end
+
+      # @param [Symbol] The requested format of the response (default=:json)
+      # @note Supported formats include [:json | :json-api].  For backward compatibility,
+      #   it defaults to :json.
+      def format
+        return @format if @format.present?
+        return @format = @requested_format if [:json, :jsonapi].include? @requested_format
+        Rails.logger.warn("Format '#{@requested_format}' is not a valid format for search.  Supported formats are [:json, :jsonapi].  Defaulting to :json.")
+        @format = :json
+      end
+
+      # @return [Integer] The first record to include in the response data. (default=1).
+      # @note The first record may be out of range (i.e., < 1 or > total_num_of_results),
+      # but it will always be numeric, defaulting to 1 if not specified or not an Integer.
+      def page_offset
+        return @page_offset if @page_offset.present?
+        return @page_offset = 1 unless page_offset_specified?
+        @page_offset = validated_request_page_offset || 1
+      end
+
+      # @return [Boolean] true if the request specifies the page offset; otherwise, false
+      def page_offset_specified?
+        request_params.keys.include?("page_offset") || request_params.keys.include?("startRecord")
+      end
+
+      # @return [Integer] The page offset as specified in the request_params, nil if invalid.
+      # @note The page offset can be specified with page_offset (preferred) or
+      #       startRecord (deprecated, supported for backward compatibility with
+      #       linked_data module pagination).
+      def requested_page_offset
+        return @requested_page_offset if @requested_page_offset.present?
+        @requested_page_offset = (request_params['page_offset'] || request_params['startRecord'])
+      end
+
+      # @return [Integer] The first record to include in the response data as
+      #     requested as long as it is an Integer; otherwise, returns nil.
+      def validated_request_page_offset
+        @page_offset_error = false
+        offset = Integer(requested_page_offset)
+        return offset if offset == 1
+        @page_offset_error = ERROR_OUT_OF_RANGE_TOO_SMALL if offset < 1
+        @page_offset_error = ERROR_OUT_OF_RANGE_TOO_LARGE if offset > total_num_found
+        offset
+      rescue ArgumentError
+        @page_offset_error = ERROR_NOT_INTEGER
+        nil
+      end
+
+      # @return [Integer] The requested maximum number of results to return (default=DEFAULT_PAGE_LIMIT | ALL)
+      # @see #default_page_limit
+      # @see DEFAULT_PAGE_LIMIT
+      def page_limit
+        return @page_limit if @page_limit.present?
+        return @page_limit = default_page_limit unless page_limit_specified?
+        @page_limit = validated_request_page_limit || default_page_limit
+      end
+
+      # @return [Boolean] true if the request specifies the page limit; otherwise, false
+      def page_limit_specified?
+        request_params.keys.include?("page_limit") || request_params.keys.include?("maxRecords")
+      end
+
+      # @return [Integer] The max number of records for a page as specified in the request_params.
+      # @note The page size limit can be specified with page_limit (preferred) or
+      #       maxRecords (deprecated, supported for backward compatibility with
+      #       linked_data module pagination).
+      def requested_page_limit
+        return @requested_page_limit if @requested_page_limit.present?
+        @requested_page_limit ||= (request_params['page_limit'] || request_params['maxRecords'])
+      end
+
+      # @return [Integer] The max number of records to include in response data as
+      #     requested as long as it is a positive Integer; otherwise, returns nil.
+      def validated_request_page_limit
+        @page_limit_error = false
+        limit = Integer(requested_page_limit)
+        @page_limit_error = ERROR_OUT_OF_RANGE_TOO_SMALL if limit < 1
+        limit.positive? ? limit : nil
+      rescue ArgumentError
+        @page_limit_error = ERROR_NOT_INTEGER
+        nil
+      end
+
+      # @return [Integer] The default to use when page_limit isn't specified.
+      # @note To maintain backward compatibility, the limit will be all results
+      #   if format is json and neither page_limit nor page_offset were specified.
+      def default_page_limit
+        return total_num_found unless json_api? || page_offset_specified? || page_limit_specified?
+        DEFAULT_PAGE_LIMIT
+      end
+
+      # @return [Integer] the index into the terms Array for the first record to
+      #     include in the page data
+      # @note page_offset begins counting at 1 and the Array index begins at 0.
+      def start_index
+        @start_index ||= page_offset - 1
+      end
+
+      # @return [Integer] the index into the terms Array for the last record to
+      #     include in the page data
+      def last_index
+        return @last_index if @last_index.present?
+        return @last_index = start_index if start_index >= last_possible_index
+        last_index = start_index + page_limit - 1
+        @last_index = last_index <= last_possible_index ? last_index : last_possible_index
+      end
+
+      # @return [Integer] the index for the last term in the Array
+      def last_possible_index
+        total_num_found - 1
+      end
+
+      # @return [Integer] actual number of results in the returned page of results;
+      #     0 if request is out of range
+      def actual_page_size
+        @actual_page_size ||= start_index <= last_possible_index ? last_index - start_index + 1 : 0
+      end
+
+      # @return [Integer] total number of terms matching the search query
+      def total_num_found
+        @results.length
+      end
+
+      # @return the URL to current page of results
+      def self_link
+        url_with(page_offset: page_offset)
+      end
+
+      # @return the URL to the first page of results
+      def first_link
+        url_with(page_offset: 1)
+      end
+
+      # @return the URL to the last page of results
+      def last_link
+        last_start = (total_num_found / page_limit) * page_limit + 1
+        last_start -= page_limit if last_start > total_num_found
+        last_start = 1 if last_start < 1
+        url_with(page_offset: last_start)
+      end
+
+      # @return the URL to the next page of results; nil if on last page
+      def next_link
+        next_start = page_offset + page_limit
+        next_start <= total_num_found ? url_with(page_offset: next_start) : nil
+      end
+
+      # @return the URL to the previous page of results; nil if on first page
+      def prev_link
+        return if page_offset == 1
+        prev_start = page_offset - page_limit
+        prev_start >= 1 ? url_with(page_offset: prev_start) : url_with(page_offset: 1)
+      end
+
+      # @return the original URL without the parameters
+      def url_without_parameters
+        URI.parse(request_base_url + request_path)
+      end
+
+      # Generate a URL based off the original URL and parameter values with page_offset
+      # updated based on the passed in value.
+      # @param page_offset [Integer] the value to use for page_offset
+      # @return [String] a full URL with the updated page_offset
+      def url_with(page_offset:)
+        updated_params = update_parameters(page_offset)
+
+        uri = url_without_parameters
+        uri.query = URI.encode_www_form(updated_params)
+        uri.to_s
+      end
+
+      # @param page_offset [Integer] the value to use for page_offset
+      # @return [Hash] parameter key-value pairs formatted for the URL using
+      #     the preferred parameter name and updated page_offset value
+      def update_parameters(page_offset)
+        updated_params = request_query_params.except('page_offset', 'page_limit')
+        updated_params['page_limit'] = page_limit
+        updated_params['page_offset'] = page_offset
+        updated_params
+      end
+  end
+end

data/config/initializers/mime_types.rb

@@ -0,0 +1,4 @@
+Mime::Type.register 'application/vnd.api+json', :jsonapi
+Mime::Type.register 'application/ld+json', :jsonld
+Mime::Type.register 'text/n3', :n3
+Mime::Type.register 'application/n-triples', :ntriples

data/config/routes.rb

@@ -9,6 +9,8 @@ Qa::Engine.routes.draw do
   get "/search/:vocab(/:subauthority)", controller: :terms, action: :search
   get "/show/:vocab/:id", controller: :terms, action: :show
   get "/show/:vocab/:subauthority/:id", controller: :terms, action: :show
+  get "/fetch/:vocab", controller: :terms, action: :fetch
+  get "/fetch/:vocab/:subauthority", controller: :terms, action: :fetch
 
   match "/search/linked_data/:vocab(/:subauthority)", to: 'application#options', via: [:options]
   match "/show/linked_data/:vocab/:id", to: 'application#options', via: [:options]
@@ -17,4 +19,6 @@ Qa::Engine.routes.draw do
   match "/search/:vocab(/:subauthority)", to: 'application#options', via: [:options]
   match "/show/:vocab/:id", to: 'application#options', via: [:options]
   match "/show/:vocab/:subauthority/:id", to: 'application#options', via: [:options]
+  match "/fetch/:vocab", to: 'application#options', via: [:options]
+  match "/fetch/:vocab/:subauthority", to: 'application#options', via: [:options]
 end

data/lib/qa/authorities/local/file_based_authority.rb

@@ -8,13 +8,14 @@ module Qa::Authorities
     def search(q)
       r = q.blank? ? [] : terms.select { |term| /\b#{q.downcase}/.match(term[:term].downcase) }
       r.map do |res|
-        { id: res[:id], label: res[:term] }.with_indifferent_access
+        { id: res[:id], label: res[:term], uri: res.fetch(:uri, nil) }.compact.with_indifferent_access
       end
     end
 
     def all
       terms.map do |res|
-        { id: res[:id], label: res[:term], active: res.fetch(:active, true) }.with_indifferent_access
+        { id: res[:id], label: res[:term], active: res.fetch(:active, true), uri: res.fetch(:uri, nil) }
+          .compact.with_indifferent_access
       end
     end
 

data/lib/qa/version.rb

@@ -1,3 +1,3 @@
 module Qa
-  VERSION = "5.5.2".freeze
+  VERSION = "5.8.1".freeze
 end