ecfr 1.0.0

data/lib/ecfr/ofr_profile_service/status.rb

@@ -0,0 +1,7 @@
+module Ecfr
+  module OfrProfileService
+    class Status < Base
+      include DefaultStatusSetup
+    end
+  end
+end

data/lib/ecfr/parallel_client.rb

@@ -0,0 +1,33 @@
+module Ecfr
+  module ParallelClient
+    module ClassMethods
+      def parallel_client(base_url:, client_options: {})
+        client(
+          base_url: base_url,
+          client_options: client_options.merge({adapter: :typhoeus})
+        )
+      end
+
+      # currently only handles expected cases when calling -renderer
+      def parallel_get(requests, client)
+        client.in_parallel do
+          requests.each do |request|
+            request.response = client.get(request.path, request.args) do |req|
+              Ecfr.config.request_hook.call(req)
+            end
+          end
+        end
+
+        requests
+      end
+    end
+
+    def self.included(base)
+      # only include parallel client if the appropriate adapter is present
+
+      Gem::Specification.find_by_name("faraday-typhoeus")
+      base.extend(ClassMethods)
+    rescue Gem::LoadError
+    end
+  end
+end

data/lib/ecfr/prince_xml_service/base.rb

@@ -0,0 +1,17 @@
+module Ecfr
+  module PrinceXmlService
+    class Base < Ecfr::Base
+      require_relative "pdf"
+
+      SERVICE_PATH = ""
+
+      def self.base_url
+        Ecfr.config.prince_xml_service_url
+      end
+
+      def self.service_name
+        "PrinceXML Service"
+      end
+    end
+  end
+end

data/lib/ecfr/prince_xml_service/pdf.rb

@@ -0,0 +1,31 @@
+module Ecfr
+  module PrinceXmlService
+    class Pdf < Base
+      class PdfGenerationFailure < StandardError; end
+
+      PDF_PATH = ""
+
+      def self.client(client_options = {}, &block)
+        client_options[:timeout] = Ecfr.config.prince_xml_service_pdf_timeout
+        super(client_options: client_options, &block)
+      end
+
+      def self.html_to_pdf(string, output_path, sha)
+        response = post(PDF_PATH, {html: string})
+
+        if response.status != 200 || response.body.blank?
+          raise PdfGenerationFailure.new(response.body)
+        else
+          directory = File.dirname(output_path)
+          FileUtils.mkdir_p(directory) unless File.directory?(directory)
+
+          # re Encoding::UndefinedConversionError ("\xE2" from ASCII-8BIT to UTF-8)
+          # faraday force_encoding https://github.com/lostisland/faraday/issues/139
+          File.write(output_path, response.body.force_encoding("utf-8"))
+
+          File.write(File.join(directory, "#{sha}.digest"), output_path)
+        end
+      end
+    end
+  end
+end

data/lib/ecfr/renderer_service/base.rb

@@ -0,0 +1,31 @@
+module Ecfr
+  module RendererService
+    class Base < Ecfr::Base
+      require_relative "status"
+
+      require_relative "content"
+      require_relative "diff"
+      require_relative "origin"
+
+      SERVICE_PATH = "/api/renderer"
+
+      def self.base_url
+        Ecfr.config.renderer_service_url || Ecfr.config.base_url
+      end
+
+      def self.service_name
+        "Renderer Service"
+      end
+
+      # used by Content and Diff subclasses
+      HTML_PATH = "v1/content"
+
+      # content retrieval doesn't make use of the .perform worflow
+      # and so we need to add service path here.
+      def self.content_path(date, title_number, view_mode: "enhanced")
+        "#{SERVICE_PATH}/#{HTML_PATH}/#{view_mode}/#{date}/title-#{title_number}"
+      end
+      private_class_method :content_path
+    end
+  end
+end

data/lib/ecfr/renderer_service/content.rb

@@ -0,0 +1,34 @@
+module Ecfr
+  module RendererService
+    class Content < Base
+      attribute :html,
+        desc: "HTML document"
+
+      def self.find(date, hierarchy, options = {}, client_options: {})
+        hierarchy = hierarchy.dup
+
+        title = hierarchy.delete(:title)
+        view_mode = options.delete(:view_mode)
+
+        complete = hierarchy.delete(:complete)
+        options[:skip_ancestry_checks] = 1 if complete
+
+        new(
+          {
+            html: get(
+              content_path(date, title, view_mode: view_mode),
+              hierarchy.merge(options),
+              client_options
+            ).body
+          }.stringify_keys
+        )
+      end
+
+      def self.url_for(date, title_number, view_mode = "enhanced", params = {})
+        path = content_path(date, title_number, view_mode: view_mode)
+
+        client.build_url(path, params).to_s
+      end
+    end
+  end
+end

data/lib/ecfr/renderer_service/diff.rb

@@ -0,0 +1,31 @@
+module Ecfr
+  module RendererService
+    class Diff < Base
+      class Undiffable < StandardError; end
+      class DiffTooLarge < Undiffable; end
+
+      attribute :html,
+        desc: "HTML document with inline changes"
+
+      def self.compare(old_date:, new_date:, hierarchy: {}, options: {})
+        hierarchy = hierarchy.dup
+
+        complete = hierarchy.delete(:complete)
+        options[:skip_ancestry_checks] = 1 if complete
+
+        title = hierarchy.delete(:title)
+        view_mode = options.delete(:view_mode) || :enhanced
+        params = hierarchy.merge(options).merge(compare: old_date)
+
+        new(
+          {
+            html: get(
+              content_path(new_date, title, view_mode: view_mode),
+              params
+            ).body
+          }.stringify_keys
+        )
+      end
+    end
+  end
+end

data/lib/ecfr/renderer_service/origin.rb

@@ -0,0 +1,56 @@
+module Ecfr
+  module RendererService
+    #
+    # The Origin API endpoint returns metadata about Source and
+    # Authority for the requested hierachy. This metadata is
+    # provided for each part in the requested hierarchy as well as
+    # any subpart and section/appendix if there are any specific
+    # to those levels.
+    #
+    class Origin < Base
+      result_key :origins
+
+      attribute :identifier,
+        desc: "the identifier portion of the level (ex. '121')"
+      attribute :label_level,
+        desc: "the full identifier and label (ex. 'Part 121')"
+      attribute :level,
+        desc: "the level being represented (ex. 'part')"
+      attribute :link,
+        desc: "the path portion of a link to the content for the hierarchy provided"
+      attribute :title,
+        desc: "the description of the level"
+
+      attribute :authority,
+        type: Array(:string),
+        desc: "the Authority content for the level"
+      attribute :source,
+        type: Array(:string),
+        desc: "the Source content for the level"
+
+      attribute :current,
+        type: :boolean,
+        desc: "whether this is the hierarchy level requested (instead of an ancestor or descendant)"
+
+      attribute :hierarchy,
+        type: Ecfr::Common::Hierarchy
+
+      ORIGIN_PATH = "v1/origin"
+
+      def self.find(date, title_number, params = {})
+        supported_params = (Ecfr::Constants::Hierarchy::HIERARCHY_LEVELS[1, 8] + [:build_id]).map(&:to_sym)
+
+        perform(
+          :get,
+          origin_path(date, title_number),
+          params: params.slice(*supported_params)
+        )
+      end
+
+      def self.origin_path(date, title_number)
+        "#{ORIGIN_PATH}/#{date}/title-#{title_number}"
+      end
+      private_class_method :origin_path
+    end
+  end
+end

data/lib/ecfr/renderer_service/status.rb

@@ -0,0 +1,7 @@
+module Ecfr
+  module RendererService
+    class Status < Base
+      include DefaultStatusSetup
+    end
+  end
+end

data/lib/ecfr/request_representation.rb

@@ -0,0 +1,12 @@
+module Ecfr
+  class RequestRepresentation
+    attr_reader :args, :options, :path
+    attr_accessor :response
+
+    def initialize(path:, args:, options: {})
+      @args = args
+      @options = options
+      @path = path
+    end
+  end
+end

data/lib/ecfr/search_service/api_documentation.rb

@@ -0,0 +1,7 @@
+module Ecfr
+  module SearchService
+    class ApiDocumentation < Base
+      include DefaultDocumentationSetup
+    end
+  end
+end

data/lib/ecfr/search_service/base.rb

@@ -0,0 +1,23 @@
+module Ecfr
+  module SearchService
+    class Base < Ecfr::Base
+      require_relative "api_documentation"
+      require_relative "status"
+
+      require_relative "content_version"
+      require_relative "facet_base"
+      require_relative "date_facet"
+      require_relative "title_facet"
+
+      SERVICE_PATH = "/api/search"
+
+      def self.base_url
+        Ecfr.config.search_service_url || Ecfr.config.base_url
+      end
+
+      def self.service_name
+        "Search Service"
+      end
+    end
+  end
+end

data/lib/ecfr/search_service/content_version/count.rb

@@ -0,0 +1,33 @@
+module Ecfr
+  module SearchService
+    class ContentVersion
+      class Count < Base
+        metadata_key :meta
+
+        metadata :description,
+          desc: "description of the search results"
+
+        metadata :total_count,
+          type: :integer,
+          desc: "total count of matching results"
+
+        COUNT_PATH = "v1/count"
+
+        #
+        # Retrieves count metadata about a search query
+        #
+        # @param [<Hash>] args see: {Ecfr::SearchService::ContentVersion::Result.find}
+        #
+        # @return [<Count>] search query count metadata
+        #
+        def self.find(args)
+          perform(
+            :get,
+            COUNT_PATH,
+            params: args
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ecfr/search_service/content_version/hierarchical_count.rb

@@ -0,0 +1,17 @@
+module Ecfr
+  module SearchService
+    class ContentVersion
+      class HierarchicalCount
+        include AttributeMethodDefinition
+        extend Extensible
+
+        attribute :relation,
+          desc: "currently will always return 'eq'"
+
+        attribute :value,
+          type: :integer,
+          desc: "total number of matching results"
+      end
+    end
+  end
+end

data/lib/ecfr/search_service/content_version/hierarchical_count_node.rb

@@ -0,0 +1,30 @@
+module Ecfr
+  module SearchService
+    class ContentVersion
+      class HierarchicalCountNode
+        include AttributeMethodDefinition
+        extend Extensible
+
+        attribute :heading,
+          desc: "the descriptive portion of the CFR level"
+        attribute :hierarchy,
+          desc: "the shortened identifier portion of the CFR level"
+        attribute :hierarchy_heading,
+          desc: "the full identifier portion of the CFR level"
+        attribute :level,
+          desc: "current hierarchy level"
+
+        attribute :count,
+          type: :integer,
+          desc: "number of results this hierarchy level contains"
+        attribute :max_score,
+          type: :integer,
+          desc: "the max score of any result this hierarchy level contains"
+
+        attribute :children,
+          type: Array(HierarchicalCountNode),
+          desc: "An array of counts data for the next level down in the hierarchy"
+      end
+    end
+  end
+end

data/lib/ecfr/search_service/content_version/hierarchichal_result.rb

@@ -0,0 +1,42 @@
+module Ecfr
+  module SearchService
+    class ContentVersion
+      class HierarchicalResult < Ecfr::SearchService::ContentVersion
+        require_relative "hierarchical_count"
+        require_relative "hierarchical_count_node"
+
+        attribute :count,
+          type: HierarchicalCount
+
+        attribute :max_score,
+          type: :float,
+          desc: "maximum score for all results"
+
+        attribute :shown_count,
+          type: :integer,
+          desc: "number of results returned"
+
+        attribute :children,
+          type: Array(HierarchicalCountNode),
+          desc: "recursive array of results nested in their hierarchy"
+
+        HIERARCHICAL_COUNTS_PATH = "v1/counts/hierarchy"
+
+        #
+        # Retrieves results of search query as a hierarchical structure
+        #
+        # @param [<Hash>] args see: {Ecfr::SearchService::ContentVersion::Result.find}
+        #
+        # @return [<HierarchicalResult>]
+        #
+        def self.find(args)
+          perform(
+            :get,
+            HIERARCHICAL_COUNTS_PATH,
+            params: args
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ecfr/search_service/content_version/result.rb

@@ -0,0 +1,110 @@
+module Ecfr
+  module SearchService
+    class ContentVersion
+      class Result < Ecfr::SearchService::ContentVersion
+        extend Ecfr::Constants::ChangeTypes
+
+        result_key :results
+
+        attribute :full_text_excerpt,
+          desc: "excerpt of text where matching keywords were found"
+        attribute :type,
+          desc: "the content type returned - either *Appendix* or *Section*"
+
+        attribute :score,
+          type: :float,
+          desc: "numerical representation of ranking within results"
+
+        attribute :structure_index,
+          type: :integer,
+          desc: "index of where content was found in relation to other content within the title - used for sorting"
+
+        attribute :change_types,
+          type: Array(:symbol),
+          desc: "array of change types that corresponds to the keys in {KNOWN_CHANGE_TYPES}"
+
+        attribute :reserved,
+          type: :boolean,
+          desc: "whether the result represents a portion of the CFR that is Reserved"
+        attribute :removed,
+          type: :boolean,
+          desc: "whether the result represents a part of the CFR that has been removed"
+
+        attribute :ends_on,
+          type: :date,
+          desc: "the last date this version of the content appeared in the eCFR"
+        attribute :starts_on,
+          type: :date,
+          desc: "the first date this version of the content appeared in the eCFR"
+
+        attribute :headings,
+          type: Ecfr::Common::Hierarchy,
+          desc: "the descriptive portion of the CFR level"
+        attribute :hierarchy,
+          type: Ecfr::Common::Hierarchy,
+          desc: "the shortened identifier portion of the CFR level"
+        attribute :hierarchy_headings,
+          type: Ecfr::Common::Hierarchy,
+          desc: "the full identifier portion of the CFR level"
+
+        metadata_key :meta
+
+        metadata :description,
+          desc: "description of the search results"
+
+        metadata :current_page,
+          type: :integer,
+          desc: "current page of results"
+        metadata :total_count,
+          type: :integer,
+          desc: "total count of matching results across all pages"
+        metadata :total_pages,
+          type: :integer,
+          desc: "total number of pages in the search results"
+
+        metadata :max_score,
+          type: :float,
+          desc: "the maximum score of any match in the search"
+
+        # returned when pagingate_by=date option is provided
+        # as part of the search query
+        metadata :min_date,
+          type: :date,
+          desc: "the minimum date of all returned results"
+        # returned when pagingate_by=date option is provided
+        # as part of the search query
+        metadata :max_date,
+          type: :date,
+          desc: "the maximum date of all returned results"
+
+        RESULTS_PATH = "v1/results"
+
+        #
+        # Retrieve results of search query
+        #
+        # @param [<Hash>] args supported search parameters; supported params:
+        # @option args [String] :date ISO date or 'current'
+        # @option args [String] :last_modified_after ISO date
+        # @option args [String] :last_modified_before ISO date
+        # @option args [String] :last_modified_on_or_after ISO date
+        # @option args [String] :last_modified_on_or_before ISO date
+        # @option args [String] :order relevance, hierarchy, newest_first, oldest_first
+        # @option args [Integer] :page page of search results to return
+        # @option args [Integer] :per_page number of results per page
+        # @option args [String] :paginate_by one of "results" or "date"
+        #   if "date" then one of the last_modified_* options is required
+        # @option args [String] :query search terms
+        #
+        # @return [[<Result>]] an array of results with metadata
+        #
+        def self.find(args)
+          perform(
+            :get,
+            RESULTS_PATH,
+            params: args.compact
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ecfr/search_service/content_version/suggestion.rb

@@ -0,0 +1,76 @@
+module Ecfr
+  module SearchService
+    class ContentVersion
+      class Suggestion < Ecfr::SearchService::ContentVersion
+        result_key :suggestions
+
+        attribute :highlight,
+          desc: "text containing '<mark>' tags the denote where the query was
+            found by the search engine - only type: 'autocomplete'"
+        # attribute :summary,
+        #   desc: "description of the search - only type: 'cfr_reference'"
+        attribute :type,
+          desc: "the type of suggestion, currently 'cfr_reference' or 'autocomplete'"
+
+        attribute :reserved,
+          type: :boolean,
+          desc: "whether the result represents a portion of the CFR that is Reserved"
+
+        attribute :removed,
+          type: :date,
+          desc: "the date that this portion of the CFR that was removed"
+
+        attribute :structure_index,
+          type: :integer,
+          desc: "an integer representing the location of the suggestion in the
+            source xml for it's corresponding title. Useful for sorting. Only
+            type: 'autocomplete'"
+
+        attribute :headings,
+          type: Ecfr::Common::Hierarchy,
+          desc: "the descriptive portion of the CFR level"
+        attribute :hierarchy,
+          type: Ecfr::Common::Hierarchy,
+          desc: "the shortened identifier portion of the CFR level"
+        attribute :hierarchy_headings,
+          type: Ecfr::Common::Hierarchy,
+          desc: "the full identifier portion of the CFR level"
+
+        metadata_key :meta
+
+        metadata :global_search_results,
+          type: :integer,
+          desc: "total number of matching full text search results"
+        metadata :narrowed_search_results,
+          type: :integer,
+          desc: "number of search results that match the current hierarchy"
+
+        metadata :narrowed_hierarchy,
+          type: Ecfr::Common::Hierarchy,
+          desc: "the hierarchy that the narrowed_search_results have been limited to"
+
+        SUGGESTIONS_PATH = "v1/suggestions"
+
+        #
+        # Retreive suggestions for the given search args
+        #
+        # @param [<Hash>] args see: {Ecfr::SearchService::ContentVersion::Result.find}
+        #   @option Boolean autocomplete Adding autocomplete=true to the request
+        #     will return suggestions of type 'autocomplete'
+        #
+        # @return [<Suggestion>] by default suggestions will be of type
+        #   'cfr_reference' and are useful for refining full text search requests.
+        #   When autocomplete=true has been added to the request then suggestions
+        #   will be of type 'autocomplete' and are useful for typeahead style searches
+        #
+        def self.find(args)
+          perform(
+            :get,
+            SUGGESTIONS_PATH,
+            params: args.except(:order, :page, :per_page).stringify_keys
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ecfr/search_service/content_version/summary.rb

@@ -0,0 +1,27 @@
+module Ecfr
+  module SearchService
+    class ContentVersion
+      class Summary < Ecfr::SearchService::ContentVersion
+        metadata_key :meta
+
+        metadata :description
+
+        SUMMARY_PATH = "v1/summary"
+
+        #
+        # <Description>
+        #
+        # @param [<Hash>] args search arguments - everthing except
+        #   :hierarchy and :query will be removed
+        #
+        # @return [<Summary>]
+        #
+        def self.find(args)
+          valid_args = args.slice(:hierarchy, :query)
+
+          perform(:get, SUMMARY_PATH, params: valid_args)
+        end
+      end
+    end
+  end
+end