DongHyeonkaandClaude Opus 5
d57d2f62a0
Implements the mongodb-superpowers-package design: Stable Tasks 1-50 and Advanced Tasks 1-15. The design assumes 19 Stable + 12 Advanced Gradle projects under modules/mongodb*. This repository's fail-closed registry declares exactly 19 leaf identities, so those modules become package boundaries inside the registered leaf :adapter:outbound:persistence-mongo, with the design's module dependency table enforced by ten ArchUnit rules. The mapping and every deviation are recorded in docs/mongodb/repository-adaptation.md. Contract highlights, all enforced by tests rather than convention: - Transaction body retry and commit retry are separate loops. A new session per body attempt; commit-only retry on an unknown commit. The body is never replayed after a commit ambiguity, so a failover cannot become a duplicate. - MongoExecutionOutcome keeps both ambiguous outcomes distinct from success and failure, and MongoFailureContext records only the design-permitted fields. - Failure classification reads server error labels before numeric codes. - BSON representations come from a pinned manifest, never a library default, and a golden type-signature gate fails on any drift. - Index and validator changes go through the manifest and the admin plane; metadata ownership gates every drop. - Every Advanced capability refuses construction unless its flag is enabled. Verified against real servers, not only unit tests. Running the lanes for the first time exposed four defects that a green `check` had hidden: - Four release lanes passed while executing zero tests; the gate now counts executed tests per lane and fails on zero. - The "single replica set" fixture was a standalone, because Testcontainers 2.x needs withReplicaSet(); its test only asserted a connection string. - The three-node fixture was three independent clusters, so no election could occur, and awaitNewPrimary() compared against the post-stop primary. - The migration lease checked modifiedCount, so a same-millisecond refresh read as a lost lease. scripts/verify-mongodb-platform.sh now reports: 9 lanes, 0 skipped, 0 failed, every evidence category produced. scripts/verify-mongodb-advanced.sh reports NOT PROMOTABLE: actual-topology evidence (real sharded cluster, real KMS, real target deployment) is unobtainable here, so it is named rather than assumed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
92 lines
5.8 KiB
Markdown
92 lines
5.8 KiB
Markdown
# MongoDB Platform — Support Matrix
|
|
|
|
Design §4. This file records what the platform is *certified* on, not what it happens to run on.
|
|
A configuration absent from this table is unsupported until someone runs the gate against it and
|
|
adds a row.
|
|
|
|
## 1. Runtime baseline
|
|
|
|
| Component | Version | Policy |
|
|
|---|---|---|
|
|
| Java | 21 | Repository runtime baseline. |
|
|
| Spring Boot | 4.0.0 | BOM-managed. Individual driver overrides are forbidden. |
|
|
| Spring Data MongoDB | 5.0.0 | Repository and `MongoTemplate` integration. Version comes from the Boot BOM. |
|
|
| MongoDB Java Driver | 5.6.1 | BOM-managed. Never pinned directly in the module. |
|
|
| Reactor | 3.8.0 | Reactive execution path. |
|
|
| Micrometer | 1.16.0 | Driver-native observability. |
|
|
| Testcontainers | 2.0.2 | Replica-set, failover, migration and compatibility lanes. |
|
|
|
|
The design's baseline is Spring Boot 4.1.x / Spring Data MongoDB 5.1.x. This repository is on
|
|
4.0.0 / 5.0.0, so the platform targets only the API surface common to both. See
|
|
[repository-adaptation.md](repository-adaptation.md) §3.
|
|
|
|
## 2. Server versions
|
|
|
|
| Lane | Version | Pinned image | Gradle task |
|
|
|---|---|---|---|
|
|
| Primary certification | MongoDB 8.0 | `mongo:8.0.16` | `mongoReplicaSetTest`, `mongoFailoverTest` |
|
|
| Compatibility | MongoDB 7.0 | `mongo:7.0.28` | `mongoCompatibilityTest` |
|
|
| Network fault injection | — | `ghcr.io/shopify/toxiproxy:2.12.0` | `mongoFailoverTest` |
|
|
|
|
Images are pinned, never `latest`: a mutable tag means the certification result describes whatever
|
|
was pulled that morning, not the version in the row. Override with
|
|
`-PmongoPrimaryImage=…` / `-PmongoCompatibilityImage=…` when testing a new patch level, and update
|
|
the row once the gate passes.
|
|
|
|
`MongoVersionMatrix.standard()` is the machine-readable form of this table; a version outside it
|
|
fails `certifies()`.
|
|
|
|
## 3. Topologies
|
|
|
|
| Topology | Status | What is certified | What is not |
|
|
|---|---|---|---|
|
|
| Standalone | **Smoke only** | Basic CRUD and mapping. | Not a production profile and never counts as Stable release evidence (D-03). Transactions, retryable writes and change streams are refused at startup by `MongoStartupValidator`. |
|
|
| Single-node replica set | **Local default** (D-02) | Transactions, retryable writes, change streams — the same semantics as production. | Elections. A single-node set never holds one, so failover behaviour is untested here. |
|
|
| 3-node replica set | **Stable production gate** | Everything above plus primary failover, unknown-commit handling and change-stream resume across an election. | Shard routing. |
|
|
| Sharded cluster | **Advanced gate** | Shard-key routing classification, scatter-gather refusal, `admin` plane operations. | Not included in the Stable gate. |
|
|
| Atlas / provider-managed | **Per-capability gate** | Search, vector search and encryption against the actual target deployment. | Atlas Local in a container is a pull-request convenience, explicitly **not** release evidence (`MongoAtlasCapabilityContractSuite.Environment`). |
|
|
|
|
## 4. Stable API and client generations
|
|
|
|
| Plane | Stable API | Purpose |
|
|
|---|---|---|
|
|
| D1 Standard document persistence | V1, `apiStrict=true` | Repositories, typed queries, atomic updates, optimistic revision. |
|
|
| D2 Advanced document operations | V1, `apiStrict=true` | `MongoTemplate`, transactions, bulk, aggregation, keyset cursors, change streams. |
|
|
| D3 Explicit Mongo capability | Not strict | Native BSON, time series, search/vector, CSFLE/QE, shard-aware operations — each behind a registered capability. |
|
|
| D4 Admin plane | Not strict | Collection, validator, index, migration, shard and repair commands. Separate credential, separate client. |
|
|
|
|
D3 is not a raw-client escape. Every call passes capability registration → database profile →
|
|
collection allowlist → operation name → timeout → consistency profile → result limit → trace →
|
|
redaction → command category → D4 refusal, in that order.
|
|
|
|
## 5. Validation actions
|
|
|
|
Stable validation actions are `error` and `warn`. `errorAndLog` is **not** part of the Stable
|
|
contract on 7.0 or 8.0 and `MongoValidatorDescriptor` refuses it.
|
|
|
|
## 6. Explicitly unsupported
|
|
|
|
Per design §3.4, none of the following is provided, and adding one is a design change rather than a
|
|
feature request:
|
|
|
|
- A generic `CommonMongoRepository<T, ID>`.
|
|
- Arbitrary runtime `runCommand`.
|
|
- Automatic index creation in production.
|
|
- A Standalone production contract.
|
|
- TTL as an exact business scheduler or as the only access control.
|
|
- Publishing raw change events as external business integration events.
|
|
- GridFS as the source of truth for new files.
|
|
- Java fully-qualified class names as a long-lived BSON schema.
|
|
- Unbounded skip pagination, unbounded aggregation pipelines, unbounded regex, unbounded results.
|
|
|
|
## 7. Capability tiers
|
|
|
|
| Tier | Capabilities | Enablement |
|
|
|---|---|---|
|
|
| Stable | Mapping, imperative/reactive execution, atomic update, optimistic lock, transactions, consistency profiles, retry/translation, query and aggregation guardrails, schema/index manifests, keyset pagination, bulk partial results, change streams, TTL contract, GeoJSON, security, observability | On when `ca-skeleton.persistence-mongo.enabled=true`. |
|
|
| Advanced | Sharding-aware query, time series, CSFLE, Queryable Encryption (equality/range), change-stream→messaging bridge, shared-collection multi-tenancy | Each behind `ca-skeleton.persistence-mongo.advanced.<capability>.enabled`. |
|
|
| Experimental | Search, vector search, hybrid search, database-per-tenant, collection-per-tenant, reshard orchestration, provider-specific features | Same flag mechanism; promotion additionally requires the evidence in [ADR-MONGO-ADV-001](../adr/ADR-MONGO-ADV-001-capability-promotion.md). |
|
|
|
|
`MongoAdvancedCapabilityFlags.propertyFor(capability)` is the authoritative property name for any
|
|
capability; the table above is its prose form.
|