ecfr 1.0.0

data/lib/ecfr/versioner_service/structure.rb

@@ -0,0 +1,120 @@
+module Ecfr
+  module VersionerService
+    class Structure < Base
+      STRUCTURE_PATH = "v1/structure"
+
+      #
+      # Retrieves the structure content for given date and hierarchy
+      #
+      # @param [<Date, String, 'current'>] date ISO date string or 'current'
+      # @param [<Integer, String>] title_number CFR title number
+      # @param [<Hash>] options
+      # @option options [String] format (json) the format that should be returned
+      #
+      # @return [<Structure>] a structure representation based on the format requested
+      #
+      def self.find(date, title_number, options = {})
+        default_options = {format: "json"}
+        options = default_options.merge(options.symbolize_keys)
+
+        format = options.delete(:format)
+
+        perform(
+          :get,
+          structure_path(date, title_number, format),
+          params: options.except(:section, :appendix),
+          perform_options: {
+            init_data: {format: format},
+            parse_response: false
+          }
+        )
+      end
+
+      #
+      # Provides a url to the structure content for given date and hierarchy
+      #
+      # @param [<Date, String, 'current'>] date ISO date string or 'current'
+      # @param [<Integer, String>] title_number CFR title number
+      # @param [<Hash>] options <description>
+      # @option options [String] format (json) the format that should be returned
+      #
+      # @return [<String>] URL to retreive structure content for given date and hierarchy
+      #
+      def self.url_for(date, title_number, options = {})
+        default_options = {format: "json"}
+        options = default_options.merge(options.symbolize_keys)
+
+        format = options.delete(:format)
+        path = [self::SERVICE_PATH, structure_path(date, title_number, format)].join("/")
+
+        client.build_url(path, options).to_s
+      end
+
+      def self.structure_path(date, title_number, format = "json")
+        "#{STRUCTURE_PATH}/#{date}/title-#{title_number}.#{format}"
+      end
+      private_class_method :structure_path
+
+      # @!attribute data [Hash, Nokogiri::XML::Document]
+      attr_reader :data
+
+      def initialize(data, options = {format: "json"})
+        data = data.body if data.is_a?(Faraday::Response)
+
+        format = options[:format]
+        skip_cache = false
+
+        # we're going to load a response from sideloaded cache
+        if data.is_a?(Hash) && format != "sideloaded"
+          format = "sideloaded"
+          skip_cache = true
+        end
+
+        if format == "json"
+          @data = JSON.parse(data).with_indifferent_access
+        elsif format == "xml"
+          @data = Nokogiri::XML::Document.parse(data)
+        elsif format == "sideloaded"
+          @data = data.with_indifferent_access
+
+          if Ecfr.config.cache_responses && !skip_cache
+            # cache sideloaded response seperately so that a non sideloaded
+            # call to structure can take advantage of cache
+            cache_key = determine_cache_key(options[:referrer].request_data)
+
+            # the client expects to be dealing with response objects, in a
+            # sideload scenario we need to cache a response like object
+            RequestStore[cache_key] = OpenStruct.new(
+              body: data,
+              status: options[:referrer].response_status
+            )
+          end
+        end
+      end
+
+      private
+
+      #
+      # Returns a cache key that would be the same as if this class
+      # wasn't being sideloaded. Currently this only supports
+      # sideloading from the Ancestors endpoint.
+      #
+      # @param [<Hash>] request_data contains information about the
+      #   original ancestor request data
+      #
+      # @return [<String>] cache_key
+      #
+      def determine_cache_key(request_data)
+        split = request_data[:path].split("/")
+        date = split[-2]
+        title_number = split[-1].split("-")[1]
+
+        path = "#{self.class::SERVICE_PATH}/#{self.class.send(:structure_path, date, title_number)}"
+
+        params = request_data[:params].except(:structure, :metadata)
+
+        self.class.cache_key(request_data[:method], path, params)
+      end
+    end
+  end
+end

data/lib/ecfr/versioner_service/title.rb

@@ -0,0 +1,78 @@
+module Ecfr
+  module VersionerService
+    #
+    # The titles API endpoint provides information about the status
+    # of each title and the overall system processing status.
+    #
+    # At most times the up_to_date_as_of date will be the same for
+    # all titles. Only when the system import is in process (each
+    # evening) or if reprocessing is being performed will these dates
+    # differ.
+    #
+    # If any title is currently importing or being reprocessed the
+    # processing_in_progress attribute will be set.
+    #
+    # The lastest_amended_on indicates the last time the Title
+    # has a substantive change occur. The latest_issue_date is the
+    # most recent date that we received the title for processing.
+    # These two attributes will generally only differ when we
+    # receive non-sunstantive updates (changes to fix minor spelling,
+    # punctuation, etc.).
+    #
+    class Title < Base
+      result_key :titles
+
+      attribute :name,
+        desc: "name of Title"
+
+      attribute :number,
+        type: :integer,
+        desc: "Title number"
+
+      attribute :processing_in_progress,
+        type: :boolean,
+        desc: "whether the Title is currently being processed"
+      attribute :reserved,
+        type: :boolean,
+        desc: "whether the Title is Reserved"
+
+      attribute :latest_amended_on,
+        type: :date,
+        desc: "the most recent date that the Title has been amended on"
+      attribute :latest_issue_date,
+        type: :date,
+        desc: "the most recent issue of the Title"
+      attribute :up_to_date_as_of,
+        type: :date,
+        desc: "the date through which the Title considered curent"
+
+      metadata_key :meta
+
+      metadata :date,
+        type: :date,
+        desc: "the max up to date value of all Titles"
+      metadata :import_in_progress,
+        type: :boolean,
+        desc: "whether any Title is undergoing processing"
+
+      TITLES_PATH = "v1/titles"
+
+      #
+      # Retreive the list of all Titles
+      #
+      # @param [<Hash>] options
+      # @option options [String] :build_id internal use only - used
+      #   to retreive data about a specific build
+      #
+      # @return [<Title>] array of Titles with data
+      #
+      def self.all(options = {})
+        perform(
+          :get,
+          TITLES_PATH,
+          params: options.compact
+        )
+      end
+    end
+  end
+end

data/lib/ecfr/versioner_service/xml_content.rb

@@ -0,0 +1,59 @@
+module Ecfr
+  module VersionerService
+    #
+    # The XML endpoint will return the full XML available
+    # for a given date and hierarchy.
+    #
+    # This is used primarily by our internal import processes
+    # and to provide links to XML from the web UI.
+    #
+    class XmlContent < Base
+      attribute :xml,
+        desc: "XML document"
+
+      XML_PATH = "v1/full"
+
+      #
+      # Retreive the XML for a given date and hierarchy
+      #
+      # @param [<Date, String, 'current'>] date ISO string or 'current'
+      # @param [<Integer, String>] title_number the title of interest
+      # @param [<Hash>] options a hash of hierarchy levels for the content desired - see attributes defined in {Ecfr::Common::Hierarchy} for acceptable keys
+      # @option options [<String>] build_id internal use only - a specific build id
+      #
+      # @return [<XML>] XML for the full title or pared down to the requested hierarchy
+      #
+      def self.find(date, title_number, options = {})
+        new(
+          {
+            xml: get(
+              xml_content_path(date, title_number),
+              options
+            ).body
+          }.stringify_keys
+        )
+      end
+
+      #
+      # Provides a url to the XML content for a given set of parameters
+      #
+      # @param [<Date, String, 'current'>] date ISO string or 'current'
+      # @param [<Integer, String>] title_number the title of interest
+      # @param [<Hash>] options a hash of hierarchy levels for the content desired - see attributes defined in {Ecfr:Common::Hierarchy} for acceptable keys
+      # @option options [<String>] build_id internal use only - a specific build id
+      #
+      # @return [<String>] URL to retreive XML content for the given parameters
+      #
+      def self.url_for(date, title_number, options = {})
+        path = xml_content_path(date, title_number)
+
+        client.build_url(path, options).to_s
+      end
+
+      def self.xml_content_path(date, title_number)
+        "#{SERVICE_PATH}/#{XML_PATH}/#{date}/title-#{title_number}.xml"
+      end
+      private_class_method :xml_content_path
+    end
+  end
+end

data/lib/ecfr.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "active_model"
+require "active_model/type"
+
+require "active_support"
+require "active_support/core_ext/class/attribute"
+require "active_support/core_ext/hash"
+require "active_support/core_ext/module/delegation"
+require "active_support/core_ext/string"
+
+require "faraday"
+require "faraday/net_http_persistent"
+require_relative "ecfr/faraday/user_agent/middleware"
+
+# NOTE: faraday-typhoeus must be installed by consuming
+# applications
+begin
+  Gem::Specification.find_by_name("faraday-typhoeus")
+  require "faraday/typhoeus"
+rescue Gem::LoadError
+end
+
+# NOTE: nokogiri must be installed by consuming
+# applications
+begin
+  Gem::Specification.find_by_name("nokogiri")
+  require "nokogiri"
+rescue Gem::LoadError
+end
+
+# NOTE: request_store must be installed by consuming
+# applications
+begin
+  Gem::Specification.find_by_name("request_store")
+  require "request_store"
+rescue Gem::LoadError
+end
+
+module Ecfr
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  def self.configure
+    yield(config)
+    config.validate!
+  end
+
+  def self.services
+    [
+      Ecfr::AdminService,
+      Ecfr::DiffService,
+      Ecfr::OfrProfileService,
+      Ecfr::PrinceXmlService,
+      Ecfr::RendererService,
+      Ecfr::SearchService,
+      Ecfr::SubscriptionsService,
+      Ecfr::VersionerService
+    ]
+  end
+end
+
+# order important
+require_relative "ecfr/version"
+require_relative "ecfr/configuration"
+require_relative "ecfr/constants"
+require_relative "ecfr/extensible"
+
+require_relative "ecfr/attribute_caster"
+require_relative "ecfr/attribute_method_definition"
+require_relative "ecfr/facet_attribute_method_definition"
+
+require_relative "ecfr/common/hierarchy"
+require_relative "ecfr/default_documentation_setup"
+require_relative "ecfr/default_status_setup"
+require_relative "ecfr/parallel_client"
+
+require_relative "ecfr/client"
+require_relative "ecfr/base"
+require_relative "ecfr/request_representation"
+
+require_relative "ecfr/admin_service/base"
+require_relative "ecfr/diff_service/base"
+require_relative "ecfr/ofr_profile_service/base"
+require_relative "ecfr/prince_xml_service/base"
+require_relative "ecfr/renderer_service/base"
+require_relative "ecfr/search_service/base"
+require_relative "ecfr/subscriptions_service/base"
+require_relative "ecfr/versioner_service/base"

data/lib/yard/attribute_handler.rb

@@ -0,0 +1,87 @@
+class AttributeHandler < YARD::Handlers::Ruby::AttributeHandler
+  handles method_call(:attribute)
+  namespace_only
+
+  def process
+    params = statement.parameters(false).dup
+    options = params.pop if params.last.type == :list
+
+    validated_attribute_names(params).each do |name|
+      namespace.attributes[scope][name] ||= SymbolHash[:read => nil, :write => nil]
+
+      object = MethodObject.new(namespace, name, scope)
+      object.file = statement.file
+      object.source = statement.source
+      register(object)
+
+      if options.first.jump(:label).source == "type:"
+        return_type = options.first.jump(:const).source
+      end
+
+      return_type = "String"
+      desc = ""
+
+      options.each do |option|
+        if option.jump(:label).source == "desc:"
+          desc = option.jump(:string_content).source
+        end
+
+        if option.jump(:label).source == "type:"
+          if node_exists?(option, [:var_ref, :const])
+            return_type = option.source.sub(/^type: /, "")
+          elsif node_exists?(option, [:assoc, :symbol_literal])
+            return_type = walk(option, [:assoc, :symbol_literal, :ident]).source.capitalize
+          end
+
+          if node_exists?(option, [:arg_paren])
+            return_type = "[#{return_type.sub(/\AArray\(/,"").sub(/\)\z/, "")}]"
+          end
+        end
+      end
+
+      object.docstring = desc.gsub(/\n/, " ") if desc
+
+      # tags must be added after the docstring
+      object.add_tag(
+        YARD::Tags::Tag.new(:return, nil, return_type)
+      )
+
+      # Register the object explicitly
+      namespace.attributes[scope][name][:read] = object
+    end
+  end
+
+  #
+  # Checks whether a node exists at the given jumps
+  #
+  # @param [<AstNode>] ast_node A YARD::Parser::Ruby::AstNode
+  # @param [[<Symbol>]] jumps array of AST node types that should match
+  #
+  # @return [<Type>] <description>
+  #
+  def node_exists?(ast_node, jumps)
+    jumped = walk(ast_node, jumps)
+    !!jumped
+  end
+
+  #
+  # Recusively `jump`s the AstNode node to find a node that
+  # matches all provided jumps. Returns nil if node is
+  # not found.
+  #
+  # In constast `jump` will return any node that matches any
+  # of the provided jumps and return the original node if there
+  # are no matches.
+  #
+  # @param [<AstNode>] ast_node A YARD::Parser::Ruby::AstNode
+  # @param [[<Symbol>]] jumps through array of AST node types to walk
+  #
+  # @return [<AstNode, nil>] the requested node or nil
+  #
+  def walk(ast_node, jumps)
+    jumps = Array(jumps)
+    node = jumps.inject(ast_node) { |o, j| o.jump(j) }
+
+    return node if node != ast_node
+  end
+end

data/lib/yard/metadata_handler.rb

@@ -0,0 +1,87 @@
+class MetadataHandler < YARD::Handlers::Ruby::AttributeHandler
+  handles method_call(:metadata)
+  namespace_only
+
+  def process
+    params = statement.parameters(false).dup
+    options = params.pop if params.last.type == :list
+
+    validated_attribute_names(params).each do |name|
+      namespace.attributes[scope][name] ||= SymbolHash[:read => nil, :write => nil]
+
+      object = MethodObject.new(namespace, name, scope)
+      object.file = statement.file
+      object.source = statement.source
+      register(object)
+
+      if options.first.jump(:label).source == "type:"
+        return_type = options.first.jump(:const).source
+      end
+
+      return_type = "String"
+      desc = ""
+
+      options.each do |option|
+        if option.jump(:label).source == "desc:"
+          desc = option.jump(:string_content).source
+        end
+
+        if option.jump(:label).source == "type:"
+          if node_exists?(option, [:var_ref, :const])
+            return_type = option.source.sub(/^type: /, "")
+          elsif node_exists?(option, [:assoc, :symbol_literal])
+            return_type = walk(option, [:assoc, :symbol_literal, :ident]).source.capitalize
+          end
+
+          if node_exists?(option, [:arg_paren])
+            return_type = "[#{return_type.sub(/\AArray\(/,"").sub(/\)\z/, "")}]"
+          end
+        end
+      end
+
+      object.docstring = desc if desc
+
+      # tags must be added after the docstring
+      object.add_tag(
+        YARD::Tags::Tag.new(:return, nil, return_type)
+      )
+
+      # Register the object explicitly
+      namespace.attributes[scope][name][:read] = object
+    end
+  end
+
+  #
+  # Checks whether a node exists at the given jumps
+  #
+  # @param [<AstNode>] ast_node A YARD::Parser::Ruby::AstNode
+  # @param [[<Symbol>]] jumps array of AST node types that should match
+  #
+  # @return [<Type>] <description>
+  #
+  def node_exists?(ast_node, jumps)
+    jumped = walk(ast_node, jumps)
+    !!jumped
+  end
+
+  #
+  # Recusively `jump`s the AstNode node to find a node that
+  # matches all provided jumps. Returns nil if node is
+  # not found.
+  #
+  # In constast `jump` will return any node that matches any
+  # of the provided jumps and return the original node if there
+  # are no matches.
+  #
+  # @param [<AstNode>] ast_node A YARD::Parser::Ruby::AstNode
+  # @param [[<Symbol>]] jumps through array of AST node types to walk
+  #
+  # @return [<AstNode, nil>] the requested node or nil
+  #
+  def walk(ast_node, jumps)
+    jumps = Array(jumps)
+    node = jumps.inject(ast_node) { |o, j| o.jump(j) }
+
+    return node if node != ast_node
+  end
+end