inferno_core 1.4.2 → 1.4.3

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