inferno_core 1.4.2 → 1.4.4

data/lib/inferno/dsl/must_support_metadata_extractor.rb

@@ -24,16 +24,49 @@ module Inferno
         self.requirement_extension_url = requirement_extension_url
       end
 
+      # @return [String] the canonical URL of the profile
+      def profile_url
+        profile.url
+      end
+
+      # @return [String] the human-readable name of the profile, eg for display purposes.
+      #   Collapses any runs of repeated whitespace, since profile titles occasionally have them.
+      def profile_name
+        profile.title&.squeeze(' ')
+      end
+
+      # @return [String] the version of the profile itself (distinct from the IG's own version)
+      def profile_version
+        profile.version
+      end
+
       # Retrieval method for the must support metadata
       # @return [Hash]
       def must_supports
         @must_supports ||= {
           extensions: must_support_extensions,
           slices: must_support_slices,
-          elements: must_support_elements
+          elements: must_support_elements,
+          recursive_elements: recursive_element_segments
         }
       end
 
+      # Names of path segments that are self-referential, ie, they may repeat at
+      # arbitrary depth. FHIR marks this with a `contentReference` back to an
+      # ancestor element instead of re-declaring the element's children, eg,
+      # Questionnaire.item.item has a contentReference of "#Questionnaire.item".
+      # A MustSupport flag on an element under such a segment (eg Questionnaire.item.text)
+      # should be considered met if it's populated at any depth of nesting
+      # (item.text, item.item.text, item.item.item.text, ...), not just the literal depth
+      # at which the flag is declared. NOTE: does not currently handle sliced recursive elements.
+      # @return [Array<String>]
+      def recursive_element_segments
+        profile_elements
+          .select { |element| element.contentReference.present? }
+          .map { |element| element.id.split('.').last }
+          .uniq
+      end
+
       def by_requirement_extension_only?(element)
         requirement_extension_url && !element.mustSupport &&
           element.extension.any? do |extension|
@@ -53,6 +86,7 @@ module Inferno
         must_support_extension_elements.map do |element|
           {
             id: element.id,
+            slice_name: extension_slice_name(element.id),
             path: element.path.gsub("#{resource}.", ''),
             url: canonical_url_without_version(element.type.first.profile.first),
             modifier_extension: element.path.end_with?('modifierExtension')
@@ -62,6 +96,15 @@ module Inferno
         end
       end
 
+      # The name of the deepest slice in a FHIR ElementDefinition id, eg "us-core-race" for
+      # "Patient.extension:us-core-race" or "ombCategory" for
+      # "Patient.extension:us-core-race.extension:ombCategory".
+      # @param element_id [String]
+      # @return [String, nil]
+      def extension_slice_name(element_id)
+        element_id.split('.').reverse.find { |segment| segment.include?(':') }&.split(':', 2)&.last
+      end
+
       def canonical_url_without_version(url)
         url&.split('|')&.first
       end

data/lib/inferno/dsl/profile_metadata.rb

@@ -0,0 +1,113 @@
+module Inferno
+  module DSL
+    # A ProfileMetadata object is a small, inheritable data holder for generated metadata about a
+    # profile or a group of tests -- most notably the Must Support metadata consumed by
+    # {MustSupportAssessment#missing_must_support_elements} and
+    # {Assertions#assert_must_support_elements_present} via their `metadata:` argument, alongside
+    # whatever other generated metadata a test kit needs to carry around (searches, bindings,
+    # references, etc).
+    #
+    # It exists so that test kits don't need to reach for `OpenStruct` (which accepts any attribute
+    # silently, making typos and generator/consumer drift hard to catch) or hand-roll their own
+    # version of this exact pattern.
+    #
+    # Test kits define a subclass and declare whatever attributes they need with `.attribute`.
+    # `must_supports` is always available, since it's the attribute Inferno's Must Support logic
+    # reads:
+    #
+    #   class GroupMetadata < Inferno::DSL::ProfileMetadata
+    #     attribute :searches
+    #     attribute :bindings
+    #   end
+    #
+    #   metadata = GroupMetadata.from_file('path/to/generated/metadata.yml')
+    #   metadata.must_supports #=> { elements: [...], extensions: [...], slices: [...] }
+    #
+    # @see MustSupportAssessment#missing_must_support_elements
+    class ProfileMetadata
+      class << self
+        # The full list of attribute names declared on this class and its ancestors.
+        # @return [Array<Symbol>]
+        def attribute_names
+          @attribute_names ||= superclass.respond_to?(:attribute_names) ? superclass.attribute_names.dup : []
+        end
+
+        # Declare an attribute that instances of this class (and subclasses) may be initialized with.
+        # @param name [Symbol]
+        # @return [void]
+        def attribute(name)
+          name = name.to_sym
+          attribute_names << name unless attribute_names.include?(name)
+          attr_accessor name
+        end
+
+        # Build an instance from a YAML file, eg one written by a metadata generator.
+        # @param path [String, Pathname]
+        # @return [ProfileMetadata]
+        def from_file(path)
+          new(YAML.load_file(path, aliases: true))
+        end
+      end
+
+      # Profile identity, mirroring fields read directly off the FHIR StructureDefinition
+      # (`resource` is the resource type the profile constrains, ie `profile.type`).
+      attribute :resource
+      attribute :profile_url
+      attribute :profile_name
+      attribute :profile_version
+
+      attribute :must_supports
+
+      # @param metadata [Hash] a hash of attribute name/value pairs. Keys not declared with
+      #   `.attribute` raise an error, so that a mismatch between a metadata generator and this
+      #   class's declared attributes is caught immediately rather than silently ignored.
+      def initialize(metadata = {})
+        metadata.each do |key, value|
+          key = key.to_sym
+          raise "Unknown #{self.class} attribute: #{key}" unless self.class.attribute_names.include?(key)
+
+          public_send(:"#{key}=", value)
+        end
+
+        self.must_supports ||= {}
+      end
+
+      # @return [Hash] the declared attributes and their current values, omitting unset (nil) ones
+      def to_hash
+        self.class.attribute_names.each_with_object({}) do |name, hash|
+          value = public_send(name)
+          hash[name] = value unless value.nil?
+        end
+      end
+
+      # Every Must Support element, slice, and extension in `must_supports`, each represented as a
+      # single string and sorted alphabetically. Unlike the list returned by a missing-elements
+      # check, this includes everything that's expected to be supported, not just what's absent
+      # from a particular set of resources.
+      #
+      # Elements are represented as their `path`, with the matched `fixed_value` appended after a
+      # colon where present (eg `"code.coding.code:45473-6"`). Slices and extensions are
+      # represented as their `path`, with their `slice_name` appended after a colon where present
+      # (eg `"category:us-core"`, `"extension:us-core-race"`).
+      # @return [Array<String>]
+      def must_support_strings
+        element_strings =
+          Array.wrap(must_supports[:elements]).map do |element|
+            must_support_string(element[:path], element[:fixed_value])
+          end
+        slice_strings =
+          Array.wrap(must_supports[:slices]).map { |slice| must_support_string(slice[:path], slice[:slice_name]) }
+        extension_strings =
+          Array.wrap(must_supports[:extensions]).map { |ext| must_support_string(ext[:path], ext[:slice_name]) }
+
+        (element_strings + slice_strings + extension_strings).sort
+      end
+
+      private
+
+      def must_support_string(path, suffix)
+        suffix.present? ? "#{path}:#{suffix}" : path
+      end
+    end
+  end
+end

data/lib/inferno/dsl/resume_test_route.rb

@@ -84,7 +84,10 @@ module Inferno
 
         test_run = find_test_run(test_run_identifier)
 
-        halt 500, "Unable to find test run with identifier '#{test_run_identifier}'." if test_run.nil?
+        if test_run.nil?
+          halt 500, "Unable to find test run with identifier '#{test_run_identifier}' " \
+                    "on request to '#{request.url}'."
+        end
 
         test_runs_repo.mark_as_no_longer_waiting(test_run.id)
 

data/lib/inferno/dsl/suite_endpoint.rb

@@ -1,5 +1,6 @@
 require 'hanami/controller'
 require 'rack/request'
+require 'fhir_models'
 require_relative '../ext/rack'
 
 module Inferno
@@ -15,6 +16,8 @@ module Inferno
     #         request.headers['authorization']&.delete_prefix('Bearer ')
     #       end
     #
+    #       error_response_format :operation_outcome
+    #
     #       # Return a json FHIR Patient resource
     #       def make_response
     #         response.status = 200
@@ -57,9 +60,47 @@ module Inferno
     #         end
     #       end
     #     end
+    #
     class SuiteEndpoint < Hanami::Action
       attr_reader :req, :res
 
+      # The built-in options for `error_response_format`
+      ERROR_RESPONSE_FORMATS = [:text, :operation_outcome].freeze
+
+      class << self
+        # Select one of Inferno's standard response formats to be returned
+        # whenever Inferno has to render an error response of its own due
+        # to problems finding the target session or an unhandled exception.
+        # You can override {#no_session_response} to customize the response
+        # in the no-session case.
+        #
+        # * `:text` (default): a `500` response with a plain text message
+        # * `:operation_outcome`: a `500` response with a FHIR
+        #   `OperationOutcome` serialized as `application/fhir+json`
+        #
+        # @param format [Symbol] `:text` or `:operation_outcome`
+        # @return [void]
+        #
+        # @example
+        #   class MyEndpoint < Inferno::DSL::SuiteEndpoint
+        #     error_response_format :operation_outcome
+        #   end
+        def error_response_format(format)
+          unless ERROR_RESPONSE_FORMATS.include?(format)
+            raise ArgumentError,
+                  "Unknown error_response_format `#{format.inspect}`. " \
+                  "Must be one of #{ERROR_RESPONSE_FORMATS.join(', ')}."
+          end
+
+          @error_response_format_value = format
+        end
+
+        # @private
+        def error_response_format_value
+          @error_response_format_value ||= :text
+        end
+      end
+
       # @!group Overrides These methods should be overridden by subclasses to
       #   define the behavior of the endpoint
 
@@ -78,6 +119,22 @@ module Inferno
         nil
       end
 
+      # Override this method to provide a short narrative description of
+      # where the test run identifier is expected to be found in an
+      # incoming request. When provided, this description is appended to
+      # the {#no_session_message} to help implementers debug requests that
+      # don't match a waiting test run.
+      #
+      # @return [String]
+      #
+      # @example
+      #   def test_run_identifier_location_description
+      #     "the 'code' query parameter"
+      #   end
+      def test_run_identifier_location_description
+        ''
+      end
+
       # Override this method to build the response.
       #
       # @return [Void]
@@ -128,6 +185,26 @@ module Inferno
         true
       end
 
+      # Override this method to fully customize the response returned when no
+      # waiting test run/session can be found for the incoming request. Set
+      # `response.status` and `response.body` (and `response.content_type`, if
+      # needed) — Inferno halts the request with those values. By default,
+      # this renders one of Inferno's standard responses based on the format
+      # selected with `error_response_format` (a plain text `500` response if
+      # none was selected).
+      #
+      # @return [Void]
+      #
+      # @example
+      #   def no_session_response
+      #     response.status = 404
+      #     response.format = :json
+      #     response.body = { error: 'no matching session' }.to_json
+      #   end
+      def no_session_response
+        error_response(no_session_message, code: 'not-found')
+      end
+
       # @!endgroup
 
       # @private
@@ -192,7 +269,7 @@ module Inferno
       def test_run
         @test_run ||=
           test_runs_repo.find_latest_waiting_by_identifier(find_test_run_identifier).tap do |test_run|
-            halt 500, "Unable to find test run with identifier '#{test_run_identifier}'." if test_run.nil?
+            render_error_and_halt { no_session_response } if test_run.nil?
           end
       end
 
@@ -216,11 +293,86 @@ module Inferno
         @logger ||= Application['logger']
       end
 
+      # @private
+      def log_error(error, url: request.url)
+        session_prefix = @test_run ? " session=#{@test_run.test_session_id}" : ''
+        logger.error("[#{url}]#{session_prefix} #{error.full_message}")
+      end
+
       # @private
       def find_test_run_identifier
-        @test_run_identifier ||= test_run_identifier
+        return @test_run_identifier if defined?(@test_run_identifier) # handle memoization in the nil case
+
+        @test_run_identifier = test_run_identifier
       rescue StandardError => e
-        halt 500, "Unable to determine test run identifier:\n#{e.full_message}"
+        log_error(e)
+        render_error_and_halt do
+          error_response(
+            'An error occurred while determining the test run identifier for this request.',
+            code: 'exception',
+            diagnostics: e.full_message
+          )
+        end
+      end
+
+      # @private
+      def no_session_message
+        base_message = "Unable to find test run for request to '#{request.url}'"
+        location = test_run_identifier_location_description
+        identifier = find_test_run_identifier
+
+        if identifier.blank?
+          detail = location.present? ? " in #{location}" : ''
+          "#{base_message}: no identifier found#{detail}."
+        else
+          detail = location.present? ? ", found in #{location}," : ''
+          "#{base_message}: identifier '#{identifier}'#{detail} is not associated with a waiting session."
+        end
+      end
+
+      # @private
+      # Yields to build the response, then halts with whatever ended up in
+      # `response.status`/`response.body`. Centralizing the halt here means
+      # overrides of the response-building hooks (e.g. #no_session_response)
+      # never need to remember to call `halt` themselves.
+      def render_error_and_halt
+        yield
+        halt response.status, response.body.join
+      end
+
+      # @private
+      # `message` is a short, human-readable summary (goes in the
+      # OperationOutcome issue's `details.text`, or stands alone as the whole
+      # plain text body). `diagnostics`, if given, is technical detail — e.g.
+      # an exception's full backtrace — that goes in the issue's
+      # `diagnostics` element, or is appended to the plain text body.
+      def error_response(message, code:, diagnostics: nil)
+        case self.class.error_response_format_value
+        when :operation_outcome
+          operation_outcome_error_response(message, code:, diagnostics:)
+        else
+          text_error_response(message, diagnostics:)
+        end
+      end
+
+      # @private
+      def text_error_response(message, diagnostics: nil)
+        response.status = 500
+        response.body = diagnostics ? "#{message}\n#{diagnostics}" : message
+      end
+
+      # @private
+      def operation_outcome_error_response(message, code:, diagnostics: nil)
+        issue = FHIR::OperationOutcome::Issue.new(
+          severity: 'fatal',
+          code:,
+          details: FHIR::CodeableConcept.new(text: message)
+        )
+        issue.diagnostics = diagnostics if diagnostics
+
+        response.status = 500
+        response.content_type = 'application/fhir+json'
+        response.body = FHIR::OperationOutcome.new(issue: [issue]).to_json
       end
 
       # @private
@@ -272,12 +424,18 @@ module Inferno
 
         make_response
       rescue StandardError => e
-        halt 500, e.full_message
+        log_error(e)
+        render_error_and_halt do
+          error_response(
+            'An error occurred while processing this request.',
+            code: 'exception',
+            diagnostics: e.full_message
+          )
+        end
       end
 
       # @private
       def add_persistence_callback # rubocop:disable Metrics/CyclomaticComplexity
-        logger = Application['logger']
         env = req.env
         env['rack.after_reply'] ||= []
         env['rack.after_reply'] << proc do
@@ -332,7 +490,7 @@ module Inferno
             )
           end
         rescue StandardError => e
-          logger.error(e.full_message)
+          log_error(e, url:)
         end
       end
     end

data/lib/inferno/dsl.rb

@@ -7,6 +7,7 @@ require_relative 'dsl/fhir_resource_navigation'
 require_relative 'dsl/fhir_resource_validation'
 require_relative 'dsl/fhirpath_evaluation'
 require_relative 'dsl/http_client'
+require_relative 'dsl/profile_metadata'
 require_relative 'dsl/must_support_assessment'
 require_relative 'dsl/results'
 require_relative 'dsl/runnable'

data/lib/inferno/entities/ig.rb

@@ -27,7 +27,14 @@ module Inferno
         @examples = []
       end
 
-      def self.from_file(ig_path)
+      # @param ig_path [String] path to either a `.tgz` IG package or a directory containing an
+      #        unpacked one
+      # @param standalone_resources_directory [String] optional path to a directory of loose
+      #        `*.json` FHIR resource files to merge in alongside the IG, eg author-maintained
+      #        resources (extra examples under 'package/example', local overrides) that aren't
+      #        part of the IG package itself. Primarily useful for test kit generator scripts.
+      # @return [IG]
+      def self.from_file(ig_path, standalone_resources_directory: nil)
         raise "#{ig_path} does not exist" unless File.exist?(ig_path)
 
         # fhir_models by default logs the entire content of non-FHIR files
@@ -35,13 +42,18 @@ module Inferno
         original_logger = FHIR.logger
         FHIR.logger = Logger.new('/dev/null')
 
-        if File.directory?(ig_path)
-          from_directory(ig_path)
-        elsif ig_path.end_with? '.tgz'
-          from_tgz(ig_path)
-        else
-          raise "Unable to load #{ig_path} as it does not appear to be a directory or a .tgz file"
-        end
+        ig =
+          if File.directory?(ig_path)
+            from_directory(ig_path)
+          elsif ig_path.end_with? '.tgz'
+            from_tgz(ig_path)
+          else
+            raise "Unable to load #{ig_path} as it does not appear to be a directory or a .tgz file"
+          end
+
+        ig.merge_standalone_resources(standalone_resources_directory) if standalone_resources_directory
+
+        ig
       ensure
         FHIR.logger = original_logger if defined? original_logger
       end
@@ -122,6 +134,37 @@ module Inferno
         end
       end
 
+      # Merge in loose FHIR resource files from a directory that isn't part of the IG package
+      # itself, eg author-maintained resources (extra examples, local SearchParameter overrides,
+      # etc) that a test kit generator keeps alongside a downloaded package. Files that aren't
+      # valid FHIR resources are skipped. Does nothing if the directory doesn't exist.
+      #
+      # Files are classified the same way as within an IG package: those under a `package/example`
+      # subdirectory are added to {#examples}, everything else (including files directly in
+      # `directory`) is added to {#resources_by_type}.
+      # @param directory [String] path to a directory of loose `*.json` FHIR resource files,
+      #        optionally nested under a `package/example` subdirectory
+      # @return [self]
+      def merge_standalone_resources(directory)
+        return self unless File.directory?(directory)
+
+        base_path = Pathname.new(directory)
+        Dir.glob(File.join(directory, '**', '*.json')).each do |file_path|
+          relative_path = Pathname.new(file_path).relative_path_from(base_path).to_s
+
+          begin
+            resource = FHIR::Json.from_json(File.read(file_path))
+            next if resource.nil?
+          rescue StandardError
+            next
+          end
+
+          handle_resource(resource, relative_path)
+        end
+
+        self
+      end
+
       def self.extract_package_id(ig_resource)
         "#{ig_resource.id}##{ig_resource.version || 'current'}"
       end