5. Add FHIR Exception Handling

    /** No patient was found for the requested ICN. */
    PATIENT_NOT_FOUND("No patient was found for the requested ICN"),
    /** A downstream service failed or couldn't be reached. */
    DOWNSTREAM_UNAVAILABLE("%s is unavailable, try again later");

package gov.va.mobile.fhirstarter.v1.exception;

import ca.uhn.fhir.rest.server.exceptions.BaseServerResponseException;
import org.hl7.fhir.r4.model.OperationOutcome;

import java.io.Serial;

/**
 * Thrown when a downstream service, such as the Mobile MVI Service, fails or can't be reached.
 *
 * <p>HAPI FHIR returns this exception as an HTTP 503 Service Unavailable response with the {@link OperationOutcome}
 * created here as the response body. The client sees which service is unavailable, but not the downstream error
 * itself; the original exception is kept as the cause for logging.
 *
 * @since 1.0
 */
public class DownstreamServiceException extends BaseServerResponseException {

    @Serial
    private static final long serialVersionUID = 1L;

    /**
     * HTTP status 503 Service Unavailable, which tells clients they may try again later.
     */
    private static final int SERVICE_UNAVAILABLE = 503;

    /**
     * Creates the exception for the given downstream service.
     *
     * @param serviceName the name of the downstream service, which is shown to the client
     * @param cause the exception thrown when calling the downstream service
     */
    public DownstreamServiceException(final String serviceName, final Throwable cause) {
        this(ErrorMessage.DOWNSTREAM_UNAVAILABLE.format(serviceName), cause, new OperationOutcome());
    }

    /**
     * Creates the exception, adding an issue with the message to the {@link OperationOutcome} returned to the client.
     *
     * @param message the error message
     * @param cause the exception thrown when calling the downstream service
     * @param outcome the operation outcome returned to the client
     */
    private DownstreamServiceException(final String message, final Throwable cause, final OperationOutcome outcome) {
        super(SERVICE_UNAVAILABLE, message, cause, outcome);
        outcome.addIssue()
               .setSeverity(OperationOutcome.IssueSeverity.ERROR)
               .setCode(OperationOutcome.IssueType.TRANSIENT)
               .setDiagnostics(message);
    }
}

package gov.va.mobile.fhirstarter.v1.client;

import gov.va.mobile.boot.restclient.RestClientManager;
import gov.va.mobile.fhirstarter.v1.exception.DownstreamServiceException;
import gov.va.mobile.mvi.v1.model.Person;
import gov.va.mobile.security.HeaderNames;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
import org.springframework.web.client.HttpClientErrorException;
import org.springframework.web.client.HttpServerErrorException;
import org.springframework.web.client.ResourceAccessException;
import org.springframework.web.client.RestClient;

import java.util.Optional;
import java.util.function.Supplier;

/**
 * Client for the Mobile MVI Service, which looks up patients in the VA Master Veteran Index (MVI).
 *
 * <p>The REST client is configured by the {@code va.mobile.restclient.registration.mvi.*} properties. Local
 * deployments call the WireMock stubs in {@code kubernetes/components/dev/wiremock-data/mvi} instead of the real
 * service.
 *
 * @since 1.0
 */
@Slf4j
@Component
public class MviClient {

    /**
     * Registration ID of the Mobile MVI Service REST client ({@code va.mobile.restclient.registration.mvi.*}).
     */
    public static final String REGISTRATION_ID = "mvi";

    /**
     * Name of the service, as shown to clients when it is unavailable.
     */
    private static final String SERVICE_NAME = "The Mobile MVI Service";

    /**
     * REST client for the Mobile MVI Service, created by the Mobile Framework from the registration properties.
     */
    private final RestClient restClient;

    /**
     * Creates the client.
     *
     * @param restClientManager provides the REST clients of the registrations in the service properties
     */
    public MviClient(final RestClientManager restClientManager) {
        this.restClient = restClientManager.getClient(REGISTRATION_ID);
    }

    /**
     * Returns the demographics of the patient with the given ICN.
     *
     * <p>The caller's JWT is passed on, because the Mobile MVI Service authorizes every request.
     *
     * @param icn the ICN of the patient
     * @param jwt the JWT of the caller
     * @return the demographics of the patient, or empty if MVI has no record of the patient
     * @throws DownstreamServiceException if the Mobile MVI Service fails or can't be reached (HTTP 503)
     */
    public Optional<Person> getPerson(final String icn, final String jwt) {
        return send(() -> restClient.get()
                                    .uri("/patients/ICN/{icn}/mvi/person", icn)
                                    .header(HeaderNames.VAMF_JWT_HEADER, jwt)
                                    .retrieve()
                                    .body(Person.class));
    }

    /**
     * Sends a request to the Mobile MVI Service and translates its failures.
     *
     * @param request the request, which returns the response body
     * @param <T> the type of the response body
     * @return the response body, or empty if MVI has no record of the patient
     * @throws DownstreamServiceException if the Mobile MVI Service fails or can't be reached (HTTP 503)
     */
    private <T> Optional<T> send(final Supplier<T> request) {
        try {
            // The Mobile MVI Service answers 204 No Content when MVI has no record, which results in a null body
            return Optional.ofNullable(request.get());
        } catch (final HttpClientErrorException.NotFound e) {
            log.debug("The Mobile MVI Service has no record of the requested patient");
            return Optional.empty();
        } catch (final HttpServerErrorException | ResourceAccessException e) {
            // Log the type of failure only: messages and response bodies can contain patient identifiers
            final String failure = e.getClass().getSimpleName();
            log.warn("The Mobile MVI Service request failed: {}", failure);
            throw new DownstreamServiceException(SERVICE_NAME, e);
        }
    }
}

{
  "request": {
    "method": "GET",
    "urlPath": "/mvi/v1/patients/ICN/10108V420871/mvi/person"
  },
  "response": {
    "status": 500,
    "body": "Internal Server Error"
  }
}

{
  "request": {
    "method": "GET",
    "urlPath": "/mvi/v1/patients/ICN/10110V004877/mvi/person"
  },
  "response": {
    "fault": "CONNECTION_RESET_BY_PEER"
  }
}

- name: mvi-wiremock-mappings
  behavior: create
  files:
  - wiremock-data/mvi/version.json
  - wiremock-data/mvi/person-10115V737384.json
  - wiremock-data/mvi/person-10132V467385.json
  - wiremock-data/mvi/person-1012845331V153043.json
  - wiremock-data/mvi/person-10108V420871.json
  - wiremock-data/mvi/person-10110V004877.json

curl -s -H "x-vamf-jwt: $STAFF_JWT" 'http://localhost:8080/fhirstarter/v1/fhir/Patient/10108V420871' | jq

./mvnw clean install -Pwith-skaffold

git add .
git commit -m "Translate Mobile MVI Service failures into HTTP 503"
git push