feat(sidecars): enable DB-Backup and Meilisearch features with required connection settings

Author: hendrikebbers

README.md

@@ -41,7 +41,9 @@ come from Maven Central):
 
 ## Quick Start
 
-The simplest way to enable every feature is to import `FullSpringServiceConfig`:
+The simplest way to wire the platform is to import `FullSpringServiceConfig` (this wires every
+feature except the opt-in sidecar features — Search and DB-Backup — which you enable explicitly, see
+below):
 
 ```java
 @SpringBootApplication
@@ -58,6 +60,30 @@ for example `SecurityConfig`, `TenantConfig`, `TagConfig`, `WebhookConfig`, `Set
 `ApiKeyConfig`. Multi-tenancy can also be enabled declaratively via the `@EnableTenant`
 meta-annotation.
 
+### Optional sidecar features (opt-in)
+
+The two features that talk to an external sidecar — **Search** (Meilisearch) and **DB-Backup** — are
+**disabled by default**, even when you import `FullSpringServiceConfig`. Importing the config does not
+activate them; you enable each explicitly. When a feature is enabled, its host is **required** and a
+missing/blank host **fails startup** (no silent `localhost` fallback):
+
+```properties
+# Search (Meilisearch) — off by default
+openelements.meilisearch.enabled=true
+openelements.meilisearch.host=https://meilisearch.internal:7700   # required when enabled
+openelements.meilisearch.master-key=${MEILI_MASTER_KEY}
+openelements.meilisearch.index-prefix=                            # optional, default ""
+
+# DB-Backup sidecar — off by default
+openelements.db-backup.enabled=true
+openelements.db-backup.base-url=https://db-backup.internal:8081   # required when enabled
+openelements.db-backup.api-token=${DB_BACKUP_API_TOKEN}          # required for authenticated calls
+```
+
+If a feature stays disabled, none of its beans are created and no connection settings are needed.
+Secrets (`master-key`, `api-token`) must come from environment variables or secret management, never
+from committed configuration.
+
 ## Features
 
 - **JWT / OAuth2 Resource Server** — Standard Spring Security JWT validation with `roles`-claim
@@ -116,14 +142,19 @@ meta-annotation.
 - **Lifecycle Events** — `OnObjectCreate`, `OnObjectUpdate` and `OnObjectDelete` are published
   synchronously inside the originating transaction; consumers opt into post-commit behaviour
   with `@TransactionalEventListener`.
-- **Search** — Meilisearch-backed full-text search via a thin `RestClient` wrapper
-  (`MeilisearchClient`). At startup the lib exchanges the master key for a scoped runtime key,
-  applies declarative per-index settings, and runs a full reindex: the application contributes one
-  `SearchIndexBootstrapStep` bean per index (streaming already-mapped documents) and an optional
-  `IndexSettings` / `ScopedKeySpec` bean. The lib never sees domain types. `Highlighter` turns
-  Meilisearch's `_formatted` output into HTML-safe highlighted fragments. An unreachable sidecar is
-  skipped with a warning, so the feature is inert until Meilisearch is available. Connection settings
-  bind from `openelements.meilisearch.*`.
+- **Search** *(opt-in, off by default)* — Meilisearch-backed full-text search via a thin `RestClient`
+  wrapper (`MeilisearchClient`). Enabled with `openelements.meilisearch.enabled=true`; `host` is then
+  required. At startup the lib exchanges the master key for a scoped runtime key, applies declarative
+  per-index settings, and runs a full reindex: the application contributes one `SearchIndexBootstrapStep`
+  bean per index (streaming already-mapped documents) and an optional `IndexSettings` / `ScopedKeySpec`
+  bean. The lib never sees domain types. `Highlighter` turns Meilisearch's `_formatted` output into
+  HTML-safe highlighted fragments. Once enabled, an unreachable sidecar is skipped with a warning, so
+  the feature is inert until Meilisearch is available. Connection settings bind from
+  `openelements.meilisearch.*` (see *Optional sidecar features*).
+- **DB-Backup client** *(opt-in, off by default)* — thin `RestClient` wrapper (`DbBackupClient`) for the
+  db-backup-service sidecar: trigger backups, poll job status, list and stream backup artefacts.
+  Enabled with `openelements.db-backup.enabled=true`; `base-url` is then required. Connection settings
+  bind from `openelements.db-backup.*` (see *Optional sidecar features*).
 
 For per-package overviews, see the `package-info.java` files under
 `src/main/java/com/openelements/spring/base/`.

src/main/java/com/openelements/spring/base/services/dbbackup/DbBackupConfig.java

@@ -1,5 +1,6 @@
 package com.openelements.spring.base.services.dbbackup;
 
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
 import org.springframework.context.annotation.ComponentScan;
 import org.springframework.context.annotation.Configuration;
@@ -16,10 +17,14 @@
  * {@code @ComponentScan} reliably picks up plain configurations but excludes auto-configurations,
  * so the properties are always registered alongside the client.
  *
- * <p>The feature is inert until the consuming application configures
- * {@code openelements.db-backup.base-url} and {@code openelements.db-backup.api-token}.
+ * <p>The feature is <strong>opt-in and disabled by default</strong>: none of these beans are created
+ * unless {@code openelements.db-backup.enabled=true}. This avoids forcing a db-backup configuration
+ * on consumers that do not use the sidecar. When enabled, {@code openelements.db-backup.base-url} is
+ * required (see {@link DbBackupProperties}) — a missing base URL fails startup rather than defaulting
+ * to {@code localhost}.
  */
 @Configuration(proxyBeanMethods = false)
+@ConditionalOnProperty(prefix = "openelements.db-backup", name = "enabled", havingValue = "true")
 @ComponentScan(basePackageClasses = DbBackupConfig.class)
 @EnableConfigurationProperties(DbBackupProperties.class)
 public class DbBackupConfig {}

src/main/java/com/openelements/spring/base/services/dbbackup/DbBackupProperties.java

@@ -1,33 +1,40 @@
 package com.openelements.spring.base.services.dbbackup;
 
+import jakarta.validation.constraints.NotBlank;
 import java.time.Duration;
 import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.validation.annotation.Validated;
 
 /**
  * Connection settings for the <a
  * href="https://github.com/OpenElementsLabs/db-backup-service">db-backup-service</a> sidecar. Bound
  * from {@code openelements.db-backup.*} application properties.
  *
+ * <p>The db-backup feature is <strong>opt-in</strong>: it is disabled by default and only activates
+ * when {@code openelements.db-backup.enabled=true} (see {@link DbBackupConfig}). When the feature is
+ * enabled, {@code baseUrl} is <strong>required</strong> — there is no default. A blank or missing
+ * {@code baseUrl} fails context startup with a binding/validation error rather than silently
+ * pointing at {@code localhost}, so a misconfiguration surfaces immediately instead of at first use.
+ *
  * <p>The sidecar exposes two unauthenticated probes ({@code /health}, {@code /info}) and a set of
  * authenticated backup endpoints under {@code /api/v1/backups/*} that require a Bearer token
  * matching the sidecar's {@code API_TOKEN}. The token must be provided through environment
  * variables or secret management — never committed to source control.
  *
- * @param baseUrl the sidecar root URL (scheme + host + port, no trailing path). Defaults to
- *     {@code http://localhost:8081}.
+ * @param baseUrl the sidecar root URL (scheme + host + port, no trailing path). Required when the
+ *     feature is enabled; no default.
  * @param apiToken the bearer token the sidecar accepts on its authenticated endpoints. May be
  *     {@code null} if only the unauthenticated probes are used; the client throws at the point of
  *     use when an authenticated call is made without a token.
  * @param requestTimeout per-request socket / read timeout. Defaults to 30 seconds because the
  *     download endpoints stream gzip blobs that can take a while.
  */
+@Validated
 @ConfigurationProperties("openelements.db-backup")
-public record DbBackupProperties(String baseUrl, String apiToken, Duration requestTimeout) {
+public record DbBackupProperties(
+    @NotBlank String baseUrl, String apiToken, Duration requestTimeout) {
 
   public DbBackupProperties {
-    if (baseUrl == null || baseUrl.isBlank()) {
-      baseUrl = "http://localhost:8081";
-    }
     if (requestTimeout == null) {
       requestTimeout = Duration.ofSeconds(30);
     }

src/main/java/com/openelements/spring/base/services/search/MeilisearchProperties.java

@@ -1,25 +1,31 @@
 package com.openelements.spring.base.services.search;
 
+import jakarta.validation.constraints.NotBlank;
 import java.time.Duration;
 import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.validation.annotation.Validated;
 
 /**
  * Connection settings for the Meilisearch sidecar. Bound from {@code openelements.meilisearch.*}
  * application properties.
  *
+ * <p>The search feature is <strong>opt-in</strong>: it is disabled by default and only activates
+ * when {@code openelements.meilisearch.enabled=true} (see {@link SearchConfig}). When the feature is
+ * enabled, {@code host} is <strong>required</strong> — there is no default. A blank or missing host
+ * fails context startup with a binding/validation error rather than silently pointing at
+ * {@code localhost}, so a misconfiguration surfaces immediately instead of at first use.
+ *
  * <p>This type is app-agnostic: it carries only the connection data and the index-prefix resolution
  * helper. By default no prefix is applied; an application that hosts several logical datasets in
  * one Meilisearch instance can set {@code openelements.meilisearch.index-prefix} to namespace its
  * indexes. The concrete index names live in the application, not here.
  */
+@Validated
 @ConfigurationProperties("openelements.meilisearch")
 public record MeilisearchProperties(
-    String host, String masterKey, String indexPrefix, Duration requestTimeout) {
+    @NotBlank String host, String masterKey, String indexPrefix, Duration requestTimeout) {
 
   public MeilisearchProperties {
-    if (host == null || host.isBlank()) {
-      host = "http://localhost:7700";
-    }
     if (indexPrefix == null) {
       indexPrefix = "";
     }

src/main/java/com/openelements/spring/base/services/search/SearchConfig.java

@@ -1,5 +1,6 @@
 package com.openelements.spring.base.services.search;
 
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
 import org.springframework.boot.context.properties.EnableConfigurationProperties;
 import org.springframework.context.annotation.ComponentScan;
 import org.springframework.context.annotation.Configuration;
@@ -20,13 +21,20 @@
  * (which excludes {@code @AutoConfiguration} classes), so the properties are always registered
  * alongside the components.
  *
- * <p>The feature is inert unless a Meilisearch sidecar is reachable: when it is not, the startup
- * runners log a warning and flip readiness to ready without indexing. The consuming application
- * supplies what the lib indexes — an optional {@link ScopedKeySpec} bean, one {@link IndexSettings}
- * bean per index, and one {@link SearchIndexBootstrapStep} bean per index — plus, for asynchronous
- * bootstrap, {@code @EnableAsync} and a {@code searchIndexExecutor} bean.
+ * <p>The feature is <strong>opt-in and disabled by default</strong>: none of these beans are
+ * created unless {@code openelements.meilisearch.enabled=true}. This avoids forcing a Meilisearch
+ * configuration on consumers that do not use search. When enabled, {@code
+ * openelements.meilisearch.host} is required (see {@link MeilisearchProperties}) — a missing host
+ * fails startup rather than defaulting to {@code localhost}.
+ *
+ * <p>Once enabled, the feature is still inert unless a Meilisearch sidecar is reachable: when it is
+ * not, the startup runners log a warning and flip readiness to ready without indexing. The consuming
+ * application supplies what the lib indexes — an optional {@link ScopedKeySpec} bean, one {@link
+ * IndexSettings} bean per index, and one {@link SearchIndexBootstrapStep} bean per index — plus, for
+ * asynchronous bootstrap, {@code @EnableAsync} and a {@code searchIndexExecutor} bean.
  */
 @Configuration(proxyBeanMethods = false)
+@ConditionalOnProperty(prefix = "openelements.meilisearch", name = "enabled", havingValue = "true")
 @ComponentScan(basePackageClasses = SearchConfig.class)
 @EnableConfigurationProperties(MeilisearchProperties.class)
 public class SearchConfig {}

src/test/java/com/openelements/spring/base/services/search/MeilisearchPropertiesBindingTest.java

@@ -1,6 +1,7 @@
 package com.openelements.spring.base.services.search;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
 
 import java.util.Map;
 import org.junit.jupiter.api.DisplayName;
@@ -16,9 +17,10 @@
  *
  * <p>The {@code @ConfigurationProperties} prefix contract: the {@code openelements.meilisearch.*}
  * prefix populates the record fields, while the pre-rename {@code
- * openelements.search.meilisearch.*} prefix is silently ignored and the record's compact-
- * constructor defaults take over. The legacy-prefix case acts as a regression guard — if a future
- * change reintroduces the longer prefix it must do so deliberately, not by accident.
+ * openelements.search.meilisearch.*} prefix is silently ignored — leaving {@code host} unset
+ * ({@code null}), since the record no longer defaults it. The legacy-prefix case acts as a
+ * regression guard — if a future change reintroduces the longer prefix it must do so deliberately,
+ * not by accident.
  *
  * <h2>How it is tested</h2>
  *
@@ -46,16 +48,15 @@ void renamedPrefixIsHonored() {
 
   /**
    * Regression guard: the legacy {@code openelements.search.meilisearch.*} prefix must not bind.
-   * Verified indirectly by asserting the record's compact-constructor default ({@code
-   * http://localhost:7700}) is returned even though the input map carries a value under the
-   * legacy prefix.
+   * Verified by asserting {@code host} stays {@code null} — the legacy-prefix value is ignored and
+   * the record no longer supplies a default host.
    */
   @Test
   @DisplayName(
-      "The legacy openelements.search.meilisearch.* prefix is ignored — the compact-constructor default wins.")
+      "The legacy openelements.search.meilisearch.* prefix is ignored — host stays unset (null).")
   void legacyPrefixIsNoLongerHonored() {
     final MeilisearchProperties props =
         bind(Map.of("openelements.search.meilisearch.host", "http://example:7700"));
-    assertEquals("http://localhost:7700", props.host());
+    assertNull(props.host());
   }
 }

src/test/resources/application-testcontainers.properties

@@ -10,6 +10,18 @@ spring.main.allow-bean-definition-overriding=true
 # Disable OAuth2 for tests - we handle auth manually
 spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.security.oauth2.resource.servlet.OAuth2ResourceServerAutoConfiguration
 
+# TestApplication uses a broad scanBasePackages over com.openelements.spring.base, so the library's
+# @Component clients (DbBackupClient, MeilisearchClient) are picked up directly — independent of the
+# now-conditional feature configs. Provide the required connection settings so their *Properties
+# beans bind. The sidecars are not reachable in tests; the clients/runners degrade gracefully.
+# both features are opt-in (off by default); enable them so the broad-scanned clients get their
+# *Properties beans, and provide the now-required hosts:
+openelements.db-backup.enabled=true
+openelements.db-backup.base-url=http://localhost:8081
+# search is opt-in (off by default) — enable it for the full-scan test context and give it a host:
+openelements.meilisearch.enabled=true
+openelements.meilisearch.host=http://localhost:7700
+
 # Concurrency tests use Propagation.REQUIRES_NEW for user provisioning, which holds two
 # connections per thread (suspended outer + inner). Default HikariCP pool of 10 deadlocks
 # under 10-thread concurrency tests — give tests enough headroom.