Add configurable filesystem binary storage (fix #860)

README.md

@@ -49,6 +49,21 @@ docker run -p 8080:8080 -e hapi.fhir.default_encoding=xml hapiproject/hapi:lates
 
 HAPI looks in the environment variables for properties in the [application.yaml](https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/resources/application.yaml) file for defaults.
 
+### Binary storage configuration
+
+To stream large `Binary` payloads to disk instead of the database, configure the starter with filesystem storage properties:
+
+```
+hapi:
+  fhir:
+    binary_storage_enabled: true
+    binary_storage_mode: FILESYSTEM
+    binary_storage_filesystem_base_directory: /binstore
+    # inline_resource_storage_below_size: 131072   # optional override
+```
+
+When `binary_storage_mode` is set to `FILESYSTEM` and `inline_resource_storage_below_size` is omitted, the starter automatically applies a 102400 byte (100 KB) inline threshold so smaller payloads remain in the database. Ensure the directory you point to is writable by the process (for Docker builds, mount it into the container with appropriate permissions).
+
 ### Configuration via overridden application.yaml file and using Docker
 
 You can customize HAPI by telling HAPI to look for the configuration file in a different location, e.g.:

src/main/java/ca/uhn/fhir/jpa/starter/AppProperties.java

@@ -61,7 +61,15 @@ public class AppProperties {
 	private Boolean filter_search_enabled = true;
 	private Boolean graphql_enabled = false;
 	private Boolean binary_storage_enabled = false;
-	private Integer inline_resource_storage_below_size = 0;
+
+	public enum BinaryStorageMode {
+		DATABASE,
+		FILESYSTEM
+	}
+
+	private BinaryStorageMode binary_storage_mode = BinaryStorageMode.DATABASE;
+	private String binary_storage_filesystem_base_directory;
+	private Integer inline_resource_storage_below_size;
 	private Boolean bulk_export_enabled = false;
 	private Boolean bulk_import_enabled = false;
 	private Boolean default_pretty_print = true;
@@ -483,6 +491,22 @@ public void setBinary_storage_enabled(Boolean binary_storage_enabled) {
 		this.binary_storage_enabled = binary_storage_enabled;
 	}
 
+	public BinaryStorageMode getBinary_storage_mode() {
+		return binary_storage_mode;
+	}
+
+	public void setBinary_storage_mode(BinaryStorageMode binary_storage_mode) {
+		this.binary_storage_mode = binary_storage_mode;
+	}
+
+	public String getBinary_storage_filesystem_base_directory() {
+		return binary_storage_filesystem_base_directory;
+	}
+
+	public void setBinary_storage_filesystem_base_directory(String binary_storage_filesystem_base_directory) {
+		this.binary_storage_filesystem_base_directory = binary_storage_filesystem_base_directory;
+	}
+
 	public Integer getInline_resource_storage_below_size() {
 		return inline_resource_storage_below_size;
 	}

src/main/java/ca/uhn/fhir/jpa/starter/common/FhirServerConfigCommon.java

@@ -1,8 +1,8 @@
 package ca.uhn.fhir.jpa.starter.common;
 
 import ca.uhn.fhir.jpa.api.config.JpaStorageSettings;
-import ca.uhn.fhir.jpa.binary.api.IBinaryStorageSvc;
 import ca.uhn.fhir.jpa.binstore.DatabaseBinaryContentStorageSvcImpl;
+import ca.uhn.fhir.jpa.binstore.FilesystemBinaryStorageSvcImpl;
 import ca.uhn.fhir.jpa.config.HibernatePropertiesProvider;
 import ca.uhn.fhir.jpa.model.config.PartitionSettings;
 import ca.uhn.fhir.jpa.model.config.PartitionSettings.CrossPartitionReferenceMode;
@@ -19,10 +19,12 @@
 import org.hl7.fhir.r4.model.Bundle.BundleType;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 import org.springframework.boot.env.YamlPropertySourceLoader;
 import org.springframework.context.annotation.*;
 import org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean;
 import org.springframework.transaction.annotation.EnableTransactionManagement;
+import org.springframework.util.Assert;
 
 import java.util.HashSet;
 import java.util.stream.Collectors;
@@ -38,6 +40,7 @@
 public class FhirServerConfigCommon {
 
 	private static final Logger ourLog = LoggerFactory.getLogger(FhirServerConfigCommon.class);
+	private static final int DEFAULT_FILESYSTEM_INLINE_THRESHOLD = 102_400;
 
 	public FhirServerConfigCommon(AppProperties appProperties) {
 		ourLog.info(
@@ -222,8 +225,9 @@ public JpaStorageSettings jpaStorageSettings(AppProperties appProperties) {
 			jpaStorageSettings.setLastNEnabled(true);
 		}
 
-		if (appProperties.getInline_resource_storage_below_size() != 0) {
-			jpaStorageSettings.setInlineResourceTextBelowSize(appProperties.getInline_resource_storage_below_size());
+		Integer inlineResourceThreshold = resolveInlineResourceThreshold(appProperties);
+		if (inlineResourceThreshold != null && inlineResourceThreshold != 0) {
+			jpaStorageSettings.setInlineResourceTextBelowSize(inlineResourceThreshold);
 		}
 
 		jpaStorageSettings.setStoreResourceInHSearchIndex(appProperties.getStore_resource_in_lucene_index_enabled());
@@ -339,16 +343,50 @@ public HibernatePropertiesProvider jpaStarterDialectProvider(
 		return new JpaHibernatePropertiesProvider(myEntityManagerFactory);
 	}
 
-	@Lazy
 	@Bean
-	public IBinaryStorageSvc binaryStorageSvc(AppProperties appProperties) {
-		DatabaseBinaryContentStorageSvcImpl binaryStorageSvc = new DatabaseBinaryContentStorageSvcImpl();
+	@ConditionalOnProperty(prefix = "hapi.fhir", name = "binary_storage_mode", havingValue = "FILESYSTEM")
+	public FilesystemBinaryStorageSvcImpl filesystemBinaryStorageSvc(AppProperties appProperties) {
+		String baseDirectory = appProperties.getBinary_storage_filesystem_base_directory();
+		Assert.hasText(
+				baseDirectory,
+				"binary_storage_filesystem_base_directory must be provided when binary_storage_mode=FILESYSTEM");
+
+		FilesystemBinaryStorageSvcImpl filesystemSvc = new FilesystemBinaryStorageSvcImpl(baseDirectory);
+		Integer inlineResourceThreshold = resolveInlineResourceThreshold(appProperties);
+		int minimumBinarySize =
+				inlineResourceThreshold == null ? DEFAULT_FILESYSTEM_INLINE_THRESHOLD : inlineResourceThreshold;
+		filesystemSvc.setMinimumBinarySize(minimumBinarySize);
+
+		Integer maxBinarySize = appProperties.getMax_binary_size();
+		if (maxBinarySize != null) {
+			filesystemSvc.setMaximumBinarySize(maxBinarySize.longValue());
+		}
+
+		return filesystemSvc;
+	}
 
-		if (appProperties.getMax_binary_size() != null) {
-			binaryStorageSvc.setMaximumBinarySize(appProperties.getMax_binary_size());
+	@Bean
+	@ConditionalOnProperty(
+			prefix = "hapi.fhir",
+			name = "binary_storage_mode",
+			havingValue = "DATABASE",
+			matchIfMissing = true)
+	public DatabaseBinaryContentStorageSvcImpl databaseBinaryStorageSvc(AppProperties appProperties) {
+		DatabaseBinaryContentStorageSvcImpl databaseSvc = new DatabaseBinaryContentStorageSvcImpl();
+		Integer maxBinarySize = appProperties.getMax_binary_size();
+		if (maxBinarySize != null) {
+			databaseSvc.setMaximumBinarySize(maxBinarySize.longValue());
 		}
+		return databaseSvc;
+	}
 
-		return binaryStorageSvc;
+	private Integer resolveInlineResourceThreshold(AppProperties appProperties) {
+		Integer inlineResourceThreshold = appProperties.getInline_resource_storage_below_size();
+		if (inlineResourceThreshold == null
+				&& appProperties.getBinary_storage_mode() == AppProperties.BinaryStorageMode.FILESYSTEM) {
+			return DEFAULT_FILESYSTEM_INLINE_THRESHOLD;
+		}
+		return inlineResourceThreshold;
 	}
 
 	@Bean

src/main/resources/application.yaml

@@ -381,6 +381,14 @@ hapi:
     # max_page_size: 200
     # retain_cached_searches_mins: 60
     # reuse_cached_search_results_millis: 60000
+    #    validation:
+    #      requests_enabled: true
+    #      responses_enabled: true
+    #    binary_storage_enabled: true
+    #    binary_storage_mode: FILESYSTEM
+    #    binary_storage_filesystem_base_directory: /binstore
+    # When binary_storage_mode is FILESYSTEM and this value is not set,
+    # the starter defaults to 102400 bytes so smaller binaries stay inline.
     inline_resource_storage_below_size: 4000
 
     # -------------------------------------------------------------------------------

src/test/java/ca/uhn/fhir/jpa/starter/common/FhirServerConfigCommonBinaryStorageTest.java

@@ -0,0 +1,96 @@
+package ca.uhn.fhir.jpa.starter.common;
+
+import ca.uhn.fhir.jpa.binstore.DatabaseBinaryContentStorageSvcImpl;
+import ca.uhn.fhir.jpa.binstore.FilesystemBinaryStorageSvcImpl;
+import ca.uhn.fhir.jpa.binary.api.IBinaryStorageSvc;
+import ca.uhn.fhir.jpa.starter.AppProperties;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.io.TempDir;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+class FhirServerConfigCommonBinaryStorageTest {
+
+	@TempDir
+	Path tempDir;
+
+	private FhirServerConfigCommon newConfig() {
+		return new FhirServerConfigCommon(new AppProperties());
+	}
+
+	@Test
+	void defaultsToDatabaseImplementation() {
+		AppProperties props = new AppProperties();
+
+		IBinaryStorageSvc svc = binaryStorageSvc(props);
+
+		assertThat(svc).isInstanceOf(DatabaseBinaryContentStorageSvcImpl.class);
+	}
+
+	@Test
+	void filesystemModeUsesDefaultMinimumWhenUnspecified() throws Exception {
+		AppProperties props = new AppProperties();
+		props.setBinary_storage_mode(AppProperties.BinaryStorageMode.FILESYSTEM);
+		Path baseDir = tempDir.resolve("fs-default");
+		Files.createDirectories(baseDir);
+		props.setBinary_storage_filesystem_base_directory(baseDir.toString());
+
+		FilesystemBinaryStorageSvcImpl svc = filesystemBinaryStorageSvc(props);
+
+		assertThat(svc.getMinimumBinarySize()).isEqualTo(102_400);
+	}
+
+	@Test
+	void filesystemModeHonoursExplicitMinimum() throws Exception {
+		AppProperties props = new AppProperties();
+		props.setBinary_storage_mode(AppProperties.BinaryStorageMode.FILESYSTEM);
+		props.setInline_resource_storage_below_size(4096);
+		Path baseDir = tempDir.resolve("fs-min-explicit");
+		Files.createDirectories(baseDir);
+		props.setBinary_storage_filesystem_base_directory(baseDir.toString());
+
+		FilesystemBinaryStorageSvcImpl svc = filesystemBinaryStorageSvc(props);
+
+		assertThat(svc.getMinimumBinarySize()).isEqualTo(4096);
+	}
+
+	@Test
+	void filesystemModeSupportsZeroMinimumWhenExplicit() throws Exception {
+		AppProperties props = new AppProperties();
+		props.setBinary_storage_mode(AppProperties.BinaryStorageMode.FILESYSTEM);
+		props.setInline_resource_storage_below_size(0);
+		Path baseDir = tempDir.resolve("fs-zero");
+		Files.createDirectories(baseDir);
+		props.setBinary_storage_filesystem_base_directory(baseDir.toString());
+
+		FilesystemBinaryStorageSvcImpl svc = filesystemBinaryStorageSvc(props);
+
+		assertThat(svc.getMinimumBinarySize()).isZero();
+	}
+
+	@Test
+	void filesystemModeRequiresBaseDirectory() {
+		AppProperties props = new AppProperties();
+		props.setBinary_storage_mode(AppProperties.BinaryStorageMode.FILESYSTEM);
+
+		assertThatThrownBy(() -> filesystemBinaryStorageSvc(props))
+				.isInstanceOf(IllegalArgumentException.class)
+				.hasMessageContaining("binary_storage_filesystem_base_directory");
+	}
+
+	private IBinaryStorageSvc binaryStorageSvc(AppProperties props) {
+		FhirServerConfigCommon config = newConfig();
+		if (props.getBinary_storage_mode() == AppProperties.BinaryStorageMode.FILESYSTEM) {
+			return config.filesystemBinaryStorageSvc(props);
+		}
+		return config.databaseBinaryStorageSvc(props);
+	}
+
+	private FilesystemBinaryStorageSvcImpl filesystemBinaryStorageSvc(AppProperties props) {
+		return (FilesystemBinaryStorageSvcImpl) binaryStorageSvc(props);
+	}
+}