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>
5.8 KiB
5.8 KiB
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 §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. |
MongoAdvancedCapabilityFlags.propertyFor(capability) is the authoritative property name for any
capability; the table above is its prose form.