feat: add quarkus-morphium extension as optional module (review only)

CHANGELOG.md

@@ -15,6 +15,74 @@ Each of `--auth` and `--ssl`, independently, made a multi-node PoppyDB replica s
 
 ### Added
 
+#### Driver: automated failover test via wire-rewriting proxy, replaces manual `FailoverReproTest`
+`FailoverReproTest` reproduced the 6.2.6 failover regressions but required a hand-built local
+replica set and process kills (`kill -9`, SIGSTOP) run by hand — it was tagged `manual` and never
+ran in CI. `DriverFailoverProxyTest` reproduces the same client-visible failure modes — clean
+stepdown, hard kill, and the critical frozen-socket case (TCP connection alive but silent, the one
+a driver can't distinguish from a slow server without a timeout) — plus read/write/messaging
+recovery, through a reusable wire-level fault-injection proxy that sits between the driver and a
+real replica set instead of killing processes. Tagged `wire-failover`, it runs automatically
+against both MongoDB and PoppyDB replica sets in the normal test matrix. `FailoverReproTest` is
+removed.
+
+#### `morphium-jakarta-data` — optional Jakarta Data 1.0 runtime module
+A new optional module, `morphium-jakarta-data`, brings a [Jakarta Data 1.0](https://jakarta.ee/specifications/data/1.0/)
+provider implementation on top of Morphium's existing query engine: `@Repository`-based
+`CrudRepository`/`MorphiumRepository` interfaces with query derivation from method names
+(`findByCategory`, `countByStatus`, `deleteByX`, `And`/`Or`/`Between`/`In`/`Like`/`OrderBy`
+and the rest of the standard keyword set), JDQL via `@Query` (including `GROUP BY`/`HAVING`
+aggregates compiled into a Morphium aggregation pipeline), `@Find`/`@Delete` with explicit
+`@By` parameter binding, offset pagination (`Page<T>`) and cursor/keyset pagination
+(`CursoredPage<T>`), and both static (`@OrderBy`) and dynamic (`Sort`/`Order`) sorting. The
+module depends on Morphium core and on `jakarta.data:jakarta.data-api`; the dependency
+direction is strictly one-way — core has no knowledge of Jakarta Data and no dependency on
+this module, so an application declaring only `de.caluga:morphium` does not get
+`jakarta.data-api` on its classpath and none of these annotations or types become available.
+Building the reactor with `-DskipExtensions` produces a core-only build (core + PoppyDB, no
+extension modules) exactly as before this change. `morphium-jakarta-data` is deliberately
+framework-agnostic — plain Java classes with zero dependencies on Quarkus, Spring, or any DI
+container — because it is meant to be consumed transitively by framework integrations, not
+added directly by most applications: `quarkus-morphium` (build-time Gizmo bytecode
+generation) and `spring-boot-morphium` (JDK dynamic proxies) build on top of this module and
+will follow in subsequent PRs. The code originates from
+[Bardioc1977/morphium-jakarta-data](https://github.com/Bardioc1977/morphium-jakarta-data),
+which is being archived now that its content has moved into the main Morphium repository.
+See [Jakarta Data](docs/jakarta-data.md).
+
+#### `quarkus-morphium` — optional Quarkus extension for CDI integration
+A new optional module, `quarkus-morphium`, integrates Morphium into
+[Quarkus](https://quarkus.io) applications: a CDI producer for `Morphium`, type-safe
+runtime configuration via `@ConfigMapping` (`quarkus.morphium.*`), declarative
+`@MorphiumTransactional` transactions with `MorphiumTransactionEvent` CDI events
+(graceful degradation on Azure CosmosDB, auto-detected), MicroProfile liveness/readiness/
+startup health checks via SmallRye Health, Dev Services (an automatically-started MongoDB
+container, optionally as a single-node replica set), a Dev UI card with live connection
+info, build-time Jakarta Data `@Repository` implementations generated via Gizmo bytecode
+(no runtime reflection, no dynamic proxies — see [Jakarta Data](docs/jakarta-data.md) for
+the underlying query-derivation, JDQL, and pagination feature set), GraalVM native-image
+support (automatic reflection registration for every `@Entity`/`@Embedded` class), default
+`MorphiumId` JSON serialization as its canonical 24-character hex string (both Jackson and
+JSON-B, in both directions), and a MongoDB-backed migration runner with a distributed lock.
+The module publishes three artifacts — `quarkus-morphium` (runtime), `quarkus-morphium-deployment`
+(build-time processing), and `quarkus-morphium-testing` (test support) — plus an
+`integration-tests` submodule that is built and run but never published. Like
+`morphium-jakarta-data`, the core has zero compile- or runtime dependency on this module;
+building the reactor with `-DskipExtensions` produces an unchanged core-only build. The
+integration tests spin up a real MongoDB via Testcontainers and therefore need a running
+Docker daemon — when Docker is unavailable, they detect this and skip themselves rather than
+failing the build. **groupId migration:** this extension previously published under
+`io.quarkiverse.morphium` as part of the Quarkiverse organization; because it does not
+actually live in the [Quarkiverse](https://quarkiverse.github.io) GitHub organization,
+Maven coordinates now follow Morphium's own groupId, `de.caluga:quarkus-morphium`, and
+version in lockstep with the Morphium reactor. **Existing users of
+`io.quarkiverse.morphium:quarkus-morphium:1.2.0` must update their dependency's groupId to
+`de.caluga` and its version to the Morphium version they adopt (currently `6.3.x`)** — no
+package renames, no API changes, only the Maven coordinates move. The code originates from
+[Bardioc1977/quarkus-morphium](https://github.com/Bardioc1977/quarkus-morphium), which is
+being archived now that its content has moved into the main Morphium repository. See
+[Quarkus Extension](docs/quarkus-extension.md).
+
 #### PoppyDB: `--users-file` — declarative user provisioning (bootstrap, upsert, version-gated)
 Builds on user replication: `--rootUser`/`--rootPassword` only ever provisioned one admin user,
 so any real application user set still had to be created by hand (a shell script running

docs/developer-testing-guide.md

@@ -169,12 +169,14 @@ The `runtests.sh` script provides a convenient wrapper around Maven with additio
 --rerunfailed       # Rerun only previously failed tests
 ```
 
-Available tags: `core`, `messaging`, `driver`, `inmemory`, `aggregation`, `cache`, `admin`, `performance`, `encryption`, `jms`, `geo`, `util`, `external`, `manual`, `failover`
+Available tags: `core`, `messaging`, `driver`, `inmemory`, `aggregation`, `cache`, `admin`, `performance`, `encryption`, `jms`, `geo`, `util`, `external`, `manual`, `failover`, `wire-failover`
 
 Two tags have special semantics:
 
 - `external` — the test needs a real MongoDB (CI-safe). Excluded by default; enabled by `--external` / the `-Pexternal` Maven profile.
-- `manual` — the test kills processes or relies on a hardcoded local setup (e.g. `FailoverReproTest` controls a local replica set via `~/mongo`). **Never runs in CI**: excluded by default, by `-Pexternal` and by `runtests.sh`. Run explicitly via `mvn -pl morphium-core test -Dtest=<Class> -Dtest.excludeTags=`. All real failover tests (StepDown/Shutdown/process kills) carry this tag; the remaining `failover` tag only marks tests to skip on PoppyDB phases.
+- `manual` — the test kills processes or relies on a hardcoded local setup. **Never runs in CI**: excluded by default, by `-Pexternal` and by `runtests.sh`. Run explicitly via `mvn -pl morphium-core test -Dtest=<Class> -Dtest.excludeTags=`. The remaining process-killing failover tests (`SingleConnectDriverFailoverTests`, `driver/pool/FailoverTests`) still carry this tag; the plain `failover` tag itself is also used as a catch-all to skip a handful of other tests on PoppyDB phases (pooled-driver tests that need a real MongoDB, `SortingTest`'s slow bulk-write case).
+
+`wire-failover` is different: it marks `DriverFailoverProxyTest`, which reproduces failover behaviour (clean stepdown, hard kill, frozen socket, and the resulting read/write/messaging recovery) through a reusable wire-level fault-injection proxy instead of controlling a real replica set process. It needs no hardcoded local setup and kills nothing, so it **does run in the normal matrix** — against both MongoDB and PoppyDB replica sets — and is not excluded by `runtests.sh` or any Maven profile.
 
 #### PoppyDB Options
 ```bash

docs/index.md

@@ -48,6 +48,21 @@ Morphium includes a complete in-memory MongoDB-compatible implementation for tes
 ## Reference
 - **[API Reference](./api-reference.md)** - Complete API documentation with examples
 
+## Extensions (Optional Modules)
+Morphium's core module (`de.caluga:morphium`) is fully self-contained and does not need
+any of the following. These are additional, opt-in modules built on top of the core:
+- **[Jakarta Data](./jakarta-data.md)** - Optional module implementing the Jakarta Data
+  1.0 specification on top of Morphium's query engine (repository pattern, `@Repository`)
+  - Query derivation from method names, JDQL (`@Query`), `@Find`/`@Delete` with `@By`
+  - Offset and cursor pagination (`Page<T>`, `CursoredPage<T>`), dynamic and static sorting
+  - Zero dependency from the core: build with `-DskipExtensions` for a core-only artifact;
+    framework integrations for Quarkus and Spring Boot build on top of this module
+- **[Quarkus Extension](./quarkus-extension.md)** - Optional module integrating Morphium into
+  Quarkus applications via a CDI producer, `@ConfigMapping`, `@MorphiumTransactional`, health
+  checks, Dev Services, Dev UI, and build-time Jakarta Data repository generation via Gizmo
+  - GraalVM native-image support and `MorphiumId` JSON (de)serialization out of the box
+  - Zero dependency from the core: build with `-DskipExtensions` for a core-only artifact
+
 Minimum requirements
 - Java 21+
 - MongoDB 5.0+