Enforce production database boundaries (#16)

Author: lMysticl

.github/workflows/ci.yml

@@ -41,5 +41,14 @@ jobs:
       - name: Build and test
         run: ./mvnw --batch-mode --no-transfer-progress clean verify
 
+      - name: Confirm real database contract ran
+        run: |
+          report="target/surefire-reports/TEST-com.aggregation.service.integration.RealDatabasesIntegrationTest.xml"
+          test -f "$report"
+          grep -q 'tests="1"' "$report"
+          grep -q 'errors="0"' "$report"
+          grep -q 'skipped="0"' "$report"
+          grep -q 'failures="0"' "$report"
+
       - name: Build Docker image
         run: docker build --tag user-aggregation-service:ci .

CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project are documented in this file.
 
 ## Unreleased
 
+### Added
+
+- Paginated `/api/v2/users` contract with explicit source provenance
+- Ports and adapters for independent PostgreSQL and MongoDB persistence models
+- ArchUnit dependency rules and real PostgreSQL/MongoDB Testcontainers coverage
+- Driver-level timeouts and per-source query metrics
+- MIT License
+
+### Changed
+
+- Bounded v1 reads without changing the existing JSON response fields
+- Standard HTTP failures now preserve their `400`, `404`, `405`, and `415` statuses
+- User identities are now unambiguous by source and source-local ID
+
 ## 1.0.0 - 2026-07-28
 
 ### Added

CONTRIBUTING.md

@@ -3,7 +3,8 @@
 ## Development requirements
 
 - JDK 21
-- Docker with MongoDB available on `localhost:27017`
+- Docker Engine for the real PostgreSQL and MongoDB contract test
+- MongoDB available on `localhost:27017` for the lightweight integration tests
 
 Run the full local quality gate before opening a pull request:
 
@@ -18,6 +19,7 @@ On Windows, use `.\mvnw.cmd` for Maven commands.
 
 - Keep REST paths and successful response fields backward compatible.
 - Add or update tests for validation, caching, failure handling, persistence, or ordering changes.
+- Preserve the ports-and-adapters dependency rules enforced by ArchUnit.
 - Keep database changes in a new Flyway migration; never rewrite an applied migration.
 - Do not commit credentials, `.env`, database files, logs, or generated build output.
 - Document externally visible changes in `CHANGELOG.md`.

README.md

@@ -13,6 +13,8 @@ This is a portfolio service with production-oriented failure, validation, migrat
 - Concurrent PostgreSQL and MongoDB aggregation on a dedicated bounded executor
 - A provenance-aware, paginated v2 API with deterministic cross-source ordering
 - Deterministic `503 Service Unavailable` responses when either source fails or times out
+- JDBC query, connection-pool, and MongoDB driver timeouts derived from bounded configuration
+- Per-source query duration metrics tagged by source and outcome
 - Caffeine query caching with write-triggered invalidation
 - Request validation and explicit `201 Created`, `400`, `409`, and `503` API contracts
 - Flyway-managed relational schema migrations
@@ -72,7 +74,8 @@ docker compose down --volumes
 | Dependency | Version | Notes |
 | --- | --- | --- |
 | JDK | 21 | The Maven compiler release and CI runtime |
-| MongoDB | 6 or newer | Required at `localhost:27017` by the integration tests |
+| Docker | Current Docker Engine | Runs the real PostgreSQL and MongoDB contract test |
+| MongoDB | 6 or newer | Required at `localhost:27017` by the lightweight integration tests |
 | Maven | Wrapper-provided | A separate Maven installation is not required |
 
 Start a disposable MongoDB for local tests:
@@ -94,6 +97,7 @@ PowerShell:
 ```
 
 GitHub Actions runs the same command on Java 21 with a MongoDB service and separately verifies that the Docker image builds.
+It also fails if the Testcontainers contract test against real PostgreSQL and MongoDB is skipped.
 
 Tagged releases publish the executable JAR, SHA-256 checksum, CycloneDX SBOM,
 and GitHub build-provenance attestation.
@@ -123,6 +127,7 @@ The default relational database is in-memory H2. Omit the `demo` profile to star
 | `AGGREGATION_PRIMARY_JDBC_PASSWORD` | empty | Relational password |
 | `AGGREGATION_MONGODB_URI` | `mongodb://localhost:27017/users` | MongoDB connection string |
 | `AGGREGATION_QUERY_TIMEOUT` | `2s` | Maximum wait for each source query |
+| `AGGREGATION_CONNECTION_TIMEOUT_MS` | `2000` | Maximum wait for a pooled JDBC connection |
 | `AGGREGATION_EXECUTOR_CORE_POOL_SIZE` | `4` | Core aggregation worker count |
 | `AGGREGATION_EXECUTOR_MAX_POOL_SIZE` | `8` | Maximum aggregation worker count |
 | `AGGREGATION_EXECUTOR_QUEUE_CAPACITY` | `100` | Bounded pending-query capacity |
@@ -189,6 +194,11 @@ HTTP adapters: /api/users and /api/v2/users
        JPA entity + Flyway    Mongo document
 ```
 
+The core dependency direction is enforced by ArchUnit. Application/domain code
+cannot depend on controllers, HTTP DTOs, or persistence adapters. CI additionally
+starts disposable PostgreSQL and MongoDB containers and verifies the real Flyway,
+JPA, MongoDB, and aggregation contract together.
+
 ## Operations
 
 | Concern | Entry point |
@@ -199,6 +209,8 @@ HTTP adapters: /api/users and /api/v2/users
 | Local image health | Docker health check against `/actuator/health` |
 
 Health details are not exposed to unauthenticated callers. Logs contain source failures and server-side correlation IDs, but API errors do not expose exception messages.
+After a source query, `/actuator/metrics/user.aggregation.source.query` exposes
+duration and count with bounded `source` and `outcome` tags.
 
 ## Current boundaries
 
@@ -213,7 +225,9 @@ See [SECURITY.md](SECURITY.md) for supported versions and private vulnerability
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md). Pull requests must pass Java tests, the real MongoDB integration tests, the package build, and the Docker image build.
+See [CONTRIBUTING.md](CONTRIBUTING.md). Pull requests must pass Java tests, the
+real PostgreSQL and MongoDB Testcontainers contract, architecture rules, the
+package build, and the Docker image build.
 
 ## License
 

pom.xml

@@ -23,6 +23,7 @@
 
 	<properties>
 		<java.version>21</java.version>
+		<archunit.version>1.4.2</archunit.version>
 		<springdoc.version>2.8.17</springdoc.version>
 	</properties>
 
@@ -62,6 +63,27 @@
 			<artifactId>spring-boot-starter-test</artifactId>
 			<scope>test</scope>
 		</dependency>
+		<dependency>
+			<groupId>org.testcontainers</groupId>
+			<artifactId>junit-jupiter</artifactId>
+			<scope>test</scope>
+		</dependency>
+		<dependency>
+			<groupId>org.testcontainers</groupId>
+			<artifactId>postgresql</artifactId>
+			<scope>test</scope>
+		</dependency>
+		<dependency>
+			<groupId>org.testcontainers</groupId>
+			<artifactId>mongodb</artifactId>
+			<scope>test</scope>
+		</dependency>
+		<dependency>
+			<groupId>com.tngtech.archunit</groupId>
+			<artifactId>archunit-junit5</artifactId>
+			<version>${archunit.version}</version>
+			<scope>test</scope>
+		</dependency>
 		<dependency>
 			<groupId>org.springdoc</groupId>
 			<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>

src/main/java/com/aggregation/service/adapter/metrics/MicrometerUserSourceMetrics.java

@@ -0,0 +1,33 @@
+package com.aggregation.service.adapter.metrics;
+
+import com.aggregation.service.application.port.UserSourceMetrics;
+import com.aggregation.service.domain.UserSource;
+import io.micrometer.core.instrument.MeterRegistry;
+import io.micrometer.core.instrument.Timer;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Component;
+
+import java.util.concurrent.atomic.AtomicBoolean;
+
+@Component
+@RequiredArgsConstructor
+public class MicrometerUserSourceMetrics implements UserSourceMetrics {
+    public static final String QUERY_METRIC = "user.aggregation.source.query";
+
+    private final MeterRegistry meterRegistry;
+
+    @Override
+    public QueryTimer start(UserSource source) {
+        Timer.Sample sample = Timer.start(meterRegistry);
+        AtomicBoolean stopped = new AtomicBoolean();
+        return outcome -> {
+            if (stopped.compareAndSet(false, true)) {
+                sample.stop(Timer.builder(QUERY_METRIC)
+                        .description("User source query duration")
+                        .tag("source", source.apiValue())
+                        .tag("outcome", outcome.tagValue())
+                        .register(meterRegistry));
+            }
+        };
+    }
+}

src/main/java/com/aggregation/service/application/UserAggregationService.java

@@ -1,6 +1,7 @@
 package com.aggregation.service.application;
 
 import com.aggregation.service.application.port.UserReadSource;
+import com.aggregation.service.application.port.UserSourceMetrics;
 import com.aggregation.service.application.port.UserWriter;
 import com.aggregation.service.config.properties.AggregationProperties;
 import com.aggregation.service.domain.AggregatedUser;
@@ -22,6 +23,7 @@
 import java.util.concurrent.Executor;
 import java.util.concurrent.RejectedExecutionException;
 import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
 import java.util.function.Supplier;
 
 @Service
@@ -43,12 +45,14 @@ public class UserAggregationService {
     private final List<UserReadSource> readSources;
     private final Map<UserSource, UserReadSource> readSourceByType;
     private final UserWriter userWriter;
+    private final UserSourceMetrics sourceMetrics;
     private final Executor aggregationExecutor;
     private final long queryTimeoutMillis;
 
     public UserAggregationService(
             List<UserReadSource> readSources,
             UserWriter userWriter,
+            UserSourceMetrics sourceMetrics,
             @Qualifier("aggregationExecutor") Executor aggregationExecutor,
             AggregationProperties properties) {
         this.readSources = readSources.stream()
@@ -57,6 +61,7 @@ public UserAggregationService(
         this.readSourceByType = indexReadSources(this.readSources);
         requireReadSource(UserSource.POSTGRESQL);
         this.userWriter = userWriter;
+        this.sourceMetrics = sourceMetrics;
         this.aggregationExecutor = aggregationExecutor;
         this.queryTimeoutMillis = properties.getQueryTimeout().toMillis();
     }
@@ -153,16 +158,21 @@ private List<AggregatedUser> aggregate(UserSearchCriteria criteria, int limit) {
     private CompletableFuture<List<AggregatedUser>> querySource(
             UserSource source,
             Supplier<List<AggregatedUser>> query) {
+        UserSourceMetrics.QueryTimer timer = sourceMetrics.start(source);
         try {
             return CompletableFuture
                     .supplyAsync(query, aggregationExecutor)
                     .orTimeout(queryTimeoutMillis, TimeUnit.MILLISECONDS)
                     .handle((users, error) -> {
                         if (error == null) {
+                            timer.stop(UserSourceMetrics.Outcome.SUCCESS);
                             return List.copyOf(users);
                         }
 
                         Throwable cause = unwrap(error);
+                        timer.stop(cause instanceof TimeoutException
+                                ? UserSourceMetrics.Outcome.TIMEOUT
+                                : UserSourceMetrics.Outcome.FAILURE);
                         log.error(
                                 "{} user query failed: {}",
                                 source.displayName(),
@@ -173,6 +183,7 @@ private CompletableFuture<List<AggregatedUser>> querySource(
                         );
                     });
         } catch (RejectedExecutionException exception) {
+            timer.stop(UserSourceMetrics.Outcome.REJECTED);
             log.error("{} user query rejected: executor saturated", source.displayName());
             return CompletableFuture.failedFuture(
                     new SourceUnavailableException(source.displayName(), exception)

src/main/java/com/aggregation/service/application/port/UserSourceMetrics.java

@@ -0,0 +1,35 @@
+package com.aggregation.service.application.port;
+
+import com.aggregation.service.domain.UserSource;
+
+public interface UserSourceMetrics {
+
+    QueryTimer start(UserSource source);
+
+    enum Outcome {
+        SUCCESS("success"),
+        FAILURE("failure"),
+        TIMEOUT("timeout"),
+        REJECTED("rejected");
+
+        private final String tagValue;
+
+        Outcome(String tagValue) {
+            this.tagValue = tagValue;
+        }
+
+        public String tagValue() {
+            return tagValue;
+        }
+    }
+
+    @FunctionalInterface
+    interface QueryTimer {
+        void stop(Outcome outcome);
+    }
+
+    static UserSourceMetrics noop() {
+        return source -> outcome -> {
+        };
+    }
+}

src/main/java/com/aggregation/service/config/DatabaseTimeoutConfiguration.java

@@ -0,0 +1,46 @@
+package com.aggregation.service.config;
+
+import com.aggregation.service.config.properties.AggregationProperties;
+import org.springframework.boot.autoconfigure.mongo.MongoClientSettingsBuilderCustomizer;
+import org.springframework.boot.autoconfigure.orm.jpa.HibernatePropertiesCustomizer;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import java.time.Duration;
+import java.util.concurrent.TimeUnit;
+
+@Configuration(proxyBeanMethods = false)
+public class DatabaseTimeoutConfiguration {
+
+    @Bean
+    HibernatePropertiesCustomizer jdbcQueryTimeout(AggregationProperties properties) {
+        int timeoutMillis = Math.toIntExact(
+                properties.getQueryTimeout().toMillis()
+        );
+        return hibernateProperties -> hibernateProperties.put(
+                "jakarta.persistence.query.timeout",
+                timeoutMillis
+        );
+    }
+
+    @Bean
+    MongoClientSettingsBuilderCustomizer mongoDriverTimeouts(
+            AggregationProperties properties) {
+        Duration timeout = properties.getQueryTimeout();
+        return builder -> builder
+                .applyToClusterSettings(settings -> settings
+                        .serverSelectionTimeout(
+                                timeout.toMillis(),
+                                TimeUnit.MILLISECONDS
+                        ))
+                .applyToSocketSettings(settings -> settings
+                        .connectTimeout(
+                                timeout.toMillis(),
+                                TimeUnit.MILLISECONDS
+                        )
+                        .readTimeout(
+                                timeout.toMillis(),
+                                TimeUnit.MILLISECONDS
+                        ));
+    }
+}

src/main/java/com/aggregation/service/config/properties/AggregationProperties.java

@@ -1,6 +1,7 @@
 package com.aggregation.service.config.properties;
 
 import jakarta.validation.Valid;
+import jakarta.validation.constraints.AssertTrue;
 import jakarta.validation.constraints.Min;
 import jakarta.validation.constraints.NotNull;
 import lombok.Getter;
@@ -22,6 +23,14 @@ public class AggregationProperties {
     @Valid
     private ExecutorProperties executor = new ExecutorProperties();
 
+    @AssertTrue(message = "query-timeout must be between 1ms and 2147483647ms")
+    public boolean isQueryTimeoutValid() {
+        return queryTimeout != null
+                && !queryTimeout.isZero()
+                && !queryTimeout.isNegative()
+                && queryTimeout.toMillis() <= Integer.MAX_VALUE;
+    }
+
     @Getter
     @Setter
     public static class ExecutorProperties {