IServerInterceptor.java

/*
 * #%L
 * HAPI FHIR - Server Framework
 * %%
 * Copyright (C) 2014 - 2024 Smile CDR, Inc.
 * %%
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 * #L%
 */
package ca.uhn.fhir.rest.server.interceptor;

import ca.uhn.fhir.interceptor.api.Hook;
import ca.uhn.fhir.interceptor.api.Pointcut;
import ca.uhn.fhir.model.api.TagList;
import ca.uhn.fhir.model.base.resource.BaseOperationOutcome;
import ca.uhn.fhir.rest.annotation.Read;
import ca.uhn.fhir.rest.annotation.Search;
import ca.uhn.fhir.rest.api.RestOperationTypeEnum;
import ca.uhn.fhir.rest.api.server.RequestDetails;
import ca.uhn.fhir.rest.api.server.ResponseDetails;
import ca.uhn.fhir.rest.server.exceptions.AuthenticationException;
import ca.uhn.fhir.rest.server.exceptions.BaseServerResponseException;
import ca.uhn.fhir.rest.server.servlet.ServletRequestDetails;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.hl7.fhir.instance.model.api.IBaseResource;

import java.io.IOException;

/**
 * Provides methods to intercept requests and responses. Note that implementations of this interface may wish to use
 * {@link InterceptorAdapter} in order to not need to implement every method.
 * <p>
 * <b>See:</b> See the <a href="https://hapifhir.io/hapi-fhir/docs/interceptors/">server
 * interceptor documentation</a> for more information on how to use this class.
 * </p>
 * Note that unless otherwise stated, it is possible to throw any subclass of
 * {@link BaseServerResponseException} from any interceptor method.
 */
public interface IServerInterceptor {

	/**
	 * This method is called upon any exception being thrown within the server's request processing code. This includes
	 * any exceptions thrown within resource provider methods (e.g. {@link Search} and {@link Read} methods) as well as
	 * any runtime exceptions thrown by the server itself. This also includes any {@link AuthenticationException}s
	 * thrown.
	 * <p>
	 * Implementations of this method may choose to ignore/log/count/etc exceptions, and return <code>true</code>. In
	 * this case, processing will continue, and the server will automatically generate an {@link BaseOperationOutcome
	 * OperationOutcome}. Implementations may also choose to provide their own response to the client. In this case, they
	 * should return <code>false</code>, to indicate that they have handled the request and processing should stop.
	 * </p>
	 *
	 * @param theRequestDetails  A bean containing details about the request that is about to be processed, including details such as the
	 *                           resource type and logical ID (if any) and other FHIR-specific aspects of the request which have been
	 *                           pulled out of the {@link jakarta.servlet.http.HttpServletRequest servlet request}. Note that the bean
	 *                           properties are not all guaranteed to be populated, depending on how early during processing the
	 *                           exception occurred.
	 * @param theServletRequest  The incoming request
	 * @param theServletResponse The response. Note that interceptors may choose to provide a response (i.e. by calling
	 *                           {@link jakarta.servlet.http.HttpServletResponse#getWriter()}) but in that case it is important to return
	 *                           <code>false</code> to indicate that the server itself should not also provide a response.
	 * @return Return <code>true</code> if processing should continue normally. This is generally the right thing to do.
	 * If your interceptor is providing a response rather than letting HAPI handle the response normally, you
	 * must return <code>false</code>. In this case, no further processing will occur and no further interceptors
	 * will be called.
	 * @throws ServletException If this exception is thrown, it will be re-thrown up to the container for handling.
	 * @throws IOException      If this exception is thrown, it will be re-thrown up to the container for handling.
	 */
	@Hook(Pointcut.SERVER_HANDLE_EXCEPTION)
	boolean handleException(
			RequestDetails theRequestDetails,
			BaseServerResponseException theException,
			HttpServletRequest theServletRequest,
			HttpServletResponse theServletResponse)
			throws ServletException, IOException;

	/**
	 * This method is called just before the actual implementing server method is invoked.
	 *
	 * @param theRequestDetails A bean containing details about the request that is about to be processed, including details such as the
	 *                          resource type and logical ID (if any) and other FHIR-specific aspects of the request which have been
	 *                          pulled out of the {@link HttpServletRequest servlet request}.
	 * @param theRequest        The incoming request
	 * @param theResponse       The response. Note that interceptors may choose to provide a response (i.e. by calling
	 *                          {@link HttpServletResponse#getWriter()}) but in that case it is important to return <code>false</code>
	 *                          to indicate that the server itself should not also provide a response.
	 * @return Return <code>true</code> if processing should continue normally. This is generally the right thing to do.
	 * If your interceptor is providing a response rather than letting HAPI handle the response normally, you
	 * must return <code>false</code>. In this case, no further processing will occur and no further interceptors
	 * will be called.
	 * @throws AuthenticationException This exception may be thrown to indicate that the interceptor has detected an unauthorized access
	 *                                 attempt. If thrown, processing will stop and an HTTP 401 will be returned to the client.
	 */
	@Hook(Pointcut.SERVER_INCOMING_REQUEST_POST_PROCESSED)
	boolean incomingRequestPostProcessed(
			RequestDetails theRequestDetails, HttpServletRequest theRequest, HttpServletResponse theResponse)
			throws AuthenticationException;

	/**
	 * Invoked before an incoming request is processed. Note that this method is called
	 * after the server has begin preparing the response to the incoming client request.
	 * As such, it is not able to supply a response to the incoming request in the way that
	 * {@link #incomingRequestPostProcessed(RequestDetails, HttpServletRequest, HttpServletResponse)}
	 * are.
	 * <p>
	 * This method may however throw a subclass of {@link BaseServerResponseException}, and processing
	 * will be aborted with an appropriate error returned to the client.
	 * </p>
	 *
	 * @param theOperation        The type of operation that the FHIR server has determined that the client is trying to invoke
	 * @param theProcessedRequest An object which will be populated with the details which were extracted from the raw request by the
	 *                            server, e.g. the FHIR operation type and the parsed resource body (if any).
	 */
	@Hook(Pointcut.SERVER_INCOMING_REQUEST_PRE_HANDLED)
	void incomingRequestPreHandled(RestOperationTypeEnum theOperation, RequestDetails theProcessedRequest);

	/**
	 * This method is called before any other processing takes place for each incoming request. It may be used to provide
	 * alternate handling for some requests, or to screen requests before they are handled, etc.
	 * <p>
	 * Note that any exceptions thrown by this method will not be trapped by HAPI (they will be passed up to the server)
	 * </p>
	 *
	 * @param theRequest  The incoming request
	 * @param theResponse The response. Note that interceptors may choose to provide a response (i.e. by calling
	 *                    {@link HttpServletResponse#getWriter()}) but in that case it is important to return <code>false</code>
	 *                    to indicate that the server itself should not also provide a response.
	 * @return Return <code>true</code> if processing should continue normally. This is generally the right thing to do.
	 * If your interceptor is providing a response rather than letting HAPI handle the response normally, you
	 * must return <code>false</code>. In this case, no further processing will occur and no further interceptors
	 * will be called.
	 */
	@Hook(Pointcut.SERVER_INCOMING_REQUEST_PRE_PROCESSED)
	boolean incomingRequestPreProcessed(HttpServletRequest theRequest, HttpServletResponse theResponse);

	/**
	 * Use {@link #outgoingResponse(RequestDetails, IBaseResource, HttpServletRequest, HttpServletResponse)} instead
	 *
	 * @deprecated As of HAPI FHIR 3.2.0, this method is deprecated and will be removed in a future version of HAPI FHIR.
	 */
	@Deprecated
	@Hook(Pointcut.SERVER_OUTGOING_RESPONSE)
	boolean outgoingResponse(RequestDetails theRequestDetails);

	/**
	 * Use {@link #outgoingResponse(RequestDetails, IBaseResource, HttpServletRequest, HttpServletResponse)} instead
	 *
	 * @deprecated As of HAPI FHIR 3.2.0, this method is deprecated and will be removed in a future version of HAPI FHIR.
	 */
	@Deprecated
	@Hook(Pointcut.SERVER_OUTGOING_RESPONSE)
	boolean outgoingResponse(
			RequestDetails theRequestDetails,
			HttpServletRequest theServletRequest,
			HttpServletResponse theServletResponse)
			throws AuthenticationException;

	/**
	 * Use {@link #outgoingResponse(RequestDetails, IBaseResource, HttpServletRequest, HttpServletResponse)} instead
	 *
	 * @deprecated As of HAPI FHIR 3.2.0, this method is deprecated and will be removed in a future version of HAPI FHIR.
	 */
	@Deprecated
	@Hook(Pointcut.SERVER_OUTGOING_RESPONSE)
	boolean outgoingResponse(RequestDetails theRequestDetails, IBaseResource theResponseObject);

	/**
	 * This method is called after the server implementation method has been called, but before any attempt to stream the
	 * response back to the client.
	 *
	 * @param theRequestDetails  A bean containing details about the request that is about to be processed, including details such as the
	 *                           resource type and logical ID (if any) and other FHIR-specific aspects of the request which have been
	 *                           pulled out of the {@link HttpServletRequest servlet request}.
	 * @param theResponseObject  The actual object which is being streamed to the client as a response. This may be
	 *                           <code>null</code> if the response does not include a resource.
	 * @param theServletRequest  The incoming request
	 * @param theServletResponse The response. Note that interceptors may choose to provide a response (i.e. by calling
	 *                           {@link HttpServletResponse#getWriter()}) but in that case it is important to return <code>false</code>
	 *                           to indicate that the server itself should not also provide a response.
	 * @return Return <code>true</code> if processing should continue normally. This is generally the right thing to do.
	 * If your interceptor is providing a response rather than letting HAPI handle the response normally, you
	 * must return <code>false</code>. In this case, no further processing will occur and no further interceptors
	 * will be called.
	 * @throws AuthenticationException This exception may be thrown to indicate that the interceptor has detected an unauthorized access
	 *                                 attempt. If thrown, processing will stop and an HTTP 401 will be returned to the client.
	 * @deprecated As of HAPI FHIR 3.3.0, this method has been deprecated in
	 * favour of {@link #outgoingResponse(RequestDetails, ResponseDetails, HttpServletRequest, HttpServletResponse)}
	 * and will be removed in a future version of HAPI FHIR.
	 */
	@Deprecated
	@Hook(Pointcut.SERVER_OUTGOING_RESPONSE)
	boolean outgoingResponse(
			RequestDetails theRequestDetails,
			IBaseResource theResponseObject,
			HttpServletRequest theServletRequest,
			HttpServletResponse theServletResponse)
			throws AuthenticationException;

	/**
	 * This method is called after the server implementation method has been called, but before any attempt to stream the
	 * response back to the client.
	 *
	 * @param theRequestDetails  A bean containing details about the request that is about to be processed, including details such as the
	 *                           resource type and logical ID (if any) and other FHIR-specific aspects of the request which have been
	 *                           pulled out of the {@link HttpServletRequest servlet request}.
	 * @param theResponseDetails This object contains details about the response, including
	 *                           the actual payload that will be returned
	 * @param theServletRequest  The incoming request
	 * @param theServletResponse The response. Note that interceptors may choose to provide a response (i.e. by calling
	 *                           {@link HttpServletResponse#getWriter()}) but in that case it is important to return <code>false</code>
	 *                           to indicate that the server itself should not also provide a response.
	 * @return Return <code>true</code> if processing should continue normally. This is generally the right thing to do.
	 * If your interceptor is providing a response rather than letting HAPI handle the response normally, you
	 * must return <code>false</code>. In this case, no further processing will occur and no further interceptors
	 * will be called.
	 * @throws AuthenticationException This exception may be thrown to indicate that the interceptor has detected an unauthorized access
	 *                                 attempt. If thrown, processing will stop and an HTTP 401 will be returned to the client.
	 */
	@Hook(Pointcut.SERVER_OUTGOING_RESPONSE)
	boolean outgoingResponse(
			RequestDetails theRequestDetails,
			ResponseDetails theResponseDetails,
			HttpServletRequest theServletRequest,
			HttpServletResponse theServletResponse)
			throws AuthenticationException;

	/**
	 * Use {@link #outgoingResponse(RequestDetails, IBaseResource, HttpServletRequest, HttpServletResponse)} instead
	 *
	 * @deprecated As of HAPI FHIR 3.2.0, this method is deprecated and will be removed in a future version of HAPI FHIR.
	 */
	@Deprecated
	boolean outgoingResponse(RequestDetails theRequestDetails, TagList theResponseObject);

	/**
	 * Use {@link #outgoingResponse(RequestDetails, IBaseResource, HttpServletRequest, HttpServletResponse)} instead
	 *
	 * @deprecated As of HAPI FHIR 3.2.0, this method is deprecated and will be removed in a future version of HAPI FHIR.
	 */
	@Deprecated
	boolean outgoingResponse(
			RequestDetails theRequestDetails,
			TagList theResponseObject,
			HttpServletRequest theServletRequest,
			HttpServletResponse theServletResponse)
			throws AuthenticationException;

	/**
	 * This method is called upon any exception being thrown within the server's request processing code. This includes
	 * any exceptions thrown within resource provider methods (e.g. {@link Search} and {@link Read} methods) as well as
	 * any runtime exceptions thrown by the server itself. This method is invoked for each interceptor (until one of them
	 * returns a non-<code>null</code> response or the end of the list is reached), after which
	 * {@link #handleException(RequestDetails, BaseServerResponseException, HttpServletRequest, HttpServletResponse)} is
	 * called for each interceptor.
	 * <p>
	 * This may be used to add an OperationOutcome to a response, or to convert between exception types for any reason.
	 * </p>
	 * <p>
	 * Implementations of this method may choose to ignore/log/count/etc exceptions, and return <code>null</code>. In
	 * this case, processing will continue, and the server will automatically generate an {@link BaseOperationOutcome
	 * OperationOutcome}. Implementations may also choose to provide their own response to the client. In this case, they
	 * should return a non-<code>null</code>, to indicate that they have handled the request and processing should stop.
	 * </p>
	 *
	 * @return Returns the new exception to use for processing, or <code>null</code> if this interceptor is not trying to
	 * modify the exception. For example, if this interceptor has nothing to do with exception processing, it
	 * should always return <code>null</code>. If this interceptor adds an OperationOutcome to the exception, it
	 * should return an exception.
	 */
	@Hook(Pointcut.SERVER_PRE_PROCESS_OUTGOING_EXCEPTION)
	BaseServerResponseException preProcessOutgoingException(
			RequestDetails theRequestDetails, Throwable theException, HttpServletRequest theServletRequest)
			throws ServletException;

	/**
	 * This method is called after all processing is completed for a request, but only if the
	 * request completes normally (i.e. no exception is thrown).
	 * <p>
	 * This method should not throw any exceptions. Any exception that is thrown by this
	 * method will be logged, but otherwise not acted upon.
	 * </p>
	 * <p>
	 * Note that this individual interceptors will have this method called in the reverse order from the order in
	 * which the interceptors were registered with the server.
	 * </p>
	 *
	 * @param theRequestDetails The request itself
	 */
	@Hook(Pointcut.SERVER_PROCESSING_COMPLETED_NORMALLY)
	void processingCompletedNormally(ServletRequestDetails theRequestDetails);
}