issue #2965 - document known limitation for custom base urls

and add a test to OriginalRequestRewriteServerTest for the exact
examples used in the docs

Signed-off-by: Lee Surprenant <lmsurpre@us.ibm.com>

docs/src/pages/guides/FHIRServerUsersGuide.md

@@ -2049,7 +2049,7 @@ This section contains reference information about each of the configuration prop
 |`fhirServer/core/maxPageSize`|integer|Sets the maximum page size for search and history request results. If a user-specified `_count` parameter value exceeds the maximum page size, then a warning is logged and the maximum page size will be used.|
 |`fhirServer/core/maxPageIncludeCount`|integer|Sets the maximum number of 'include' resources allowed per page for search and history request results. If the number of 'include' resources returned for a page of results from a search or history request will exceed the maximum number of 'include' resources allowed per page, then an error will be returned in the request results.|
 |`fhirServer/core/capabilitiesUrl`|string|The URL that is embedded in the default Capabilities statement|
-|`fhirServer/core/externalBaseUrl`|string|The base URL that is embedded in the Search bundle response, as of version 4.9.0.|
+|`fhirServer/core/externalBaseUrl`|string|The base URL that is embedded in the Search bundle response, as of version 4.9.0. Note that the base URL must not include a path segment that matches any FHIR resource type name (case-sensitive). For example, "https://example.com" or "https://example.com/my/patient/api" are fine, but "https://example.com/my/Patient/api" is not.|
 |`fhirServer/validation/failFast`|boolean|Indicates whether validation should fail fast on create and update interactions|
 |`fhirServer/term/capabilitiesUrl`|string|The URL that is embedded in the Terminology Capabilities statement using `mode=terminology`|
 |`fhirServer/term/disableCaching`|boolean|Indicates whether caching is disabled for the FHIR terminology module, this includes caching in `CodeSystemSupport`, `ValueSetSupport`, `GraphTermServiceProvider`, and `RemoteTermServiceProvider`|
@@ -2720,7 +2720,7 @@ IBM FHIR Server Supports the following custom HTTP Headers:
 |------------------|----------------------------|
 |`X-FHIR-TENANT-ID`|Specifies which tenant config should be used for the request. Default is `default`. The header name can be overridden via config property `fhirServer/core/tenantIdHeaderName`.|
 |`X-FHIR-DSID`|Specifies which datastore config should be used for the request. Default is `default`. The header name can be overridden via config property `fhirServer/core/dataSourceIdHeaderName`.|
-|`X-FHIR-FORWARDED-URL`|The original (user-facing) request URL; used for constructing absolute URLs within the server response. Only enabled when explicitly configured in the default fhir-server-config.json. If either the config property or the header itself is missing, the server will use the actual request URL. The header name can be overridden via config property `fhirServer/core/originalRequestUriHeaderName`. Note, `fhirServer/core/externalBaseUrl` overrides the `X-FHIR-FORWARDED-URL` and is used to construct the absolute URL.|
+|`X-FHIR-FORWARDED-URL`|The original (user-facing) request URL; used for constructing absolute URLs within the server response. Only enabled when explicitly configured in the default fhir-server-config.json. If either the config property or the header itself is missing, the server will use the actual request URL. The header name can be overridden via config property `fhirServer/core/originalRequestUriHeaderName`. Note that `fhirServer/core/externalBaseUrl` overrides the `X-FHIR-FORWARDED-URL` and is used to construct the absolute URL. Also note that the base URL's value must not include a path segment that matches any FHIR resource type name (case-sensitive). For example, "https://example.com" or "https://example.com/my/patient/api" are fine, but "https://example.com/my/Patient/api" is not.|
 |`X-FHIR-UPDATE-IF-MODIFIED`|When set to true, for update and patch requests, the server will perform a resource comparison and only perform the update if the contents of the resource have changed. For all other values, the update will be executed as normal.|
 
 # 6 Related topics

fhir-persistence/src/main/java/com/ibm/fhir/persistence/FHIRPersistence.java

@@ -12,7 +12,6 @@
 
 import com.ibm.fhir.model.resource.OperationOutcome;
 import com.ibm.fhir.model.resource.Resource;
-import com.ibm.fhir.model.type.Instant;
 import com.ibm.fhir.persistence.context.FHIRPersistenceContext;
 import com.ibm.fhir.persistence.erase.EraseDTO;
 import com.ibm.fhir.persistence.exception.FHIRPersistenceException;
@@ -28,7 +27,7 @@ public interface FHIRPersistence {
 
     /**
      * Stores a new FHIR Resource in the datastore. Id assignment handled by the implementation.
-     * This method has been deprecated. Instead, generate the logical id first and use the 
+     * This method has been deprecated. Instead, generate the logical id first and use the
      * createWithMeta(context, resource) call instead.
      * @param context the FHIRPersistenceContext instance associated with the current request
      * @param resource the FHIR Resource instance to be created in the datastore
@@ -38,7 +37,7 @@ public interface FHIRPersistence {
      */
     @Deprecated
     <T extends Resource> SingleResourceResult<T> create(FHIRPersistenceContext context, T resource) throws FHIRPersistenceException;
-    
+
     /**
      * Stores a new FHIR Resource in the datastore. The resource is not modified before it is stored. It
      * must therefore already include correct Meta fields. Should be used instead of
@@ -142,7 +141,7 @@ default <T extends Resource> SingleResourceResult<T> delete(FHIRPersistenceConte
      * @throws FHIRPersistenceException
      */
     MultiResourceResult<Resource> search(FHIRPersistenceContext context, Class<? extends Resource> resourceType) throws FHIRPersistenceException;
-    
+
     /**
      * Returns true iff the persistence layer implementation supports transactions.
      */
@@ -167,7 +166,7 @@ default <T extends Resource> SingleResourceResult<T> delete(FHIRPersistenceConte
     default boolean isDeleteSupported() {
         return false;
     }
-    
+
     /**
      * Returns true iff the persistence layer implementation supports update/create and it has been
      * configured in the persistence config.

fhir-server-test/src/test/java/com/ibm/fhir/server/test/OriginalRequestRewriteServerTest.java

@@ -97,4 +97,42 @@ public void testWholeSystemSearch_BaseUrlRewrite() throws Exception {
         assertTrue(responseBundle.getEntry().stream().allMatch(e -> e.getFullUrl().getValue().startsWith(ORIGINAL_URI + "/Patient")),
                 "All search response bundle entry fullUrls start with the passed in uri");
     }
+
+    /**
+     * Create a Patient and ensure the Location header reflects the OriginalRequestUri
+     */
+    @Test
+    public void testCreatePatientWithCustomBaseUrls() throws Exception {
+        WebTarget target = getWebTarget();
+        String customBaseUrl;
+        Patient patient = TestUtil.getMinimalResource(Patient.class);
+        Entity<Patient> entity = Entity.entity(patient, FHIRMediaType.APPLICATION_FHIR_JSON);
+        Response response;
+
+        // Build a new Patient and then call the 'create' API.
+        customBaseUrl = "https://example.com";
+        response = target.path("Patient").request()
+                .header("X-FHIR-Forwarded-URL", customBaseUrl + "/Patient")
+                .post(entity, Response.class);
+        assertResponse(response, Response.Status.CREATED.getStatusCode());
+        assertTrue(response.getLocation().toString().startsWith(customBaseUrl),
+                response.getLocation().toString() + " should begin with " + customBaseUrl);
+
+        customBaseUrl = "https://example.com/my/patient/api";
+        response = target.path("Patient").request()
+                .header("X-FHIR-Forwarded-URL", customBaseUrl + "/Patient")
+                .post(entity, Response.class);
+        assertResponse(response, Response.Status.CREATED.getStatusCode());
+        assertTrue(response.getLocation().toString().startsWith(customBaseUrl),
+                response.getLocation().toString() + " should begin with " + customBaseUrl);
+
+        customBaseUrl = "https://example.com/my/Patient/api";
+        response = target.path("Patient").request()
+                .header("X-FHIR-Forwarded-URL", customBaseUrl + "/Patient")
+                .post(entity, Response.class);
+        assertResponse(response, Response.Status.CREATED.getStatusCode());
+        assertFalse(response.getLocation().toString().startsWith(customBaseUrl),
+                response.getLocation().toString() + " doesn't begin with " + customBaseUrl
+                + " because of a documented limitation");
+    }
 }