Merge pull request #514 from xstefank/WFLY-14869

WFLY-14869 Add support for MicroProfile LRA

transactions/WFLY-14869-microprofile-lra.adoc

@@ -0,0 +1,123 @@
+= Support for MicroProfile LRA
+:author:            Martin Stefanko
+:email:             [email protected]
+:toc:               left
+:icons:             font
+:idprefix:
+:idseparator:       -
+:keywords:          transaction, saga, lra, microprofile
+
+== Overview
+
+The goal of this RFE is providing the Galleon layers for WildFly feature pack which integrate the
+https://github.com/jbosstm/narayana/tree/master/rts/lra[Narayana implementation] of the
+https://github.com/eclipse/microprofile-lra[MicroProfile LRA specification].
+
+The MicroProfile LRA is a transaction processing pattern well suited for microservice development based on the saga
+pattern. The motivation of such processing is summarized in the
+https://github.com/eclipse/microprofile-lra/blob/1.0/README.adoc#motivation[MicroProfile Spec readme].
+
+
+== Issue Metadata
+
+=== Issue
+
+* https://issues.redhat.com/browse/WFLY-14869
+
+=== Related Issues
+
+* https://issues.redhat.com/browse/EAP7-1496
+
+=== Dev Contacts
+
+* mailto:[email protected][{author}]
+
+=== QE Contacts
+
+* mailto:[email protected][Fabio Burzigotti]
+
+=== Testing By
+
+* [x] Engineering
+* [ ] QE
+
+
+=== Affected Projects or Components
+
+* Transactions
+* WildFly
+
+=== Other Interested Projects
+
+* MicroProfile
+* Galleon
+* WildFly Operator
+
+=== Relevant Installation Types
+
+* [x] Traditional standalone server (unzipped or provisioned by Galleon)
+* [x] Managed domain
+* [ ] OpenShift s2i
+* [x] Bootable jar
+
+== Requirements
+
+=== Hard Requirements
+
+The feature will integrate the LRA specification into the WildFly feature pack as two new extensions (one for LRA coordinator and one for LRA participant) together with two new subsystems and Galleon layers accordingly.
+The Galleon layers will be available for provisioning.
+The provisioned layers will provide all functionality defined in LRA specification for users in WildFly.
+
+The integrations will consist of two separate subsystems - microprofile-lra-coordinator and microprofile-lra-participant) and two separate extensions - org.wildfly.extension.microprofile.lra-coordinator and org.wildfly.extension.microprofile.lra-participant.
+
+The first layer provides a capability of the LRA participant - bundling the Narayana client library capable
+to parse the annotations from LRA specification and work with JAX-RS and non-JAX-RS bindings.
+
+The second layer provides the capability of the LRA coordinator - a server which provides HTTP endpoints where
+applications may register as participants which the coordinator then calls back (via HTTP calls) when LRA finishes.
+
+The feature pack implementation will be placed amongst other MicroProfile WildFly subsystems under
+https://github.com/wildfly/wildfly/tree/main/microprofile[the WildFly GitHub repository].
+
+Both subsystems are optional to allow for exclusion during provisioning.
+
+The LRA layers will be dependent on the `transactions` subsystem. The LRA uses the same object store types
+as the JTA/JTS transaction uses, it requires the recovery manager thread to be running and requires transaction
+specifics like unique node-identifier per running application server (WildFly).
+
+As said before the LRA coordinator is based on the Narayana core (`transactions` subsystem within WildFly). The LRA records and JTA records share the same storage and recovery processing.
+
+=== Nice-to-Have Requirements
+
+Create a quickstart on LRA on how to use LRA with WildFly for https://github.com/wildfly/quickstart.
+
+LRA records could be listed under `/subsystem=transactions/log-store=log-store/lras=...`
+and the operations (e.g. a need for probing) will be consistent to what was developed for JTA transaction types
+under `/subsystem=transactions/log-store=log-store/transactions=...`. This is optional, because the LRA Coordinator REST interface already provides this information.
+
+=== Non-Requirements
+
+NONE
+
+== Test Plan
+
+1. Testing LRA functionality within WildFly including TCK and subsystem setup.
++
+The LRA functionality tests are part of the Narayana LRA codebase (https://github.com/jbosstm/narayana/tree/master/rts/lra/test/. Namely basic and crash tests in addition to TCK.
++
+2. The WildFly will be running with LRA TCK module.
++
+https://github.com/wildfly/wildfly/tree/main/testsuite/integration/microprofile-tck
++
+3. Basic integration tests which tests the Galleon layer provisioning.
++
+https://github.com/wildfly/wildfly/tree/main/testsuite/integration/microprofile
+
+
+== Community Documentation
+
+Description of the LRA configuration to be added in the documentation as part of the implementation PR.
+
+== Release Note Content
+
+WildFly introduces two new Galleon layers `microprofile-lra-participant` and `microprofile-lra-coordinator` for provisioning which provide the MicroProfile LRA specification integration into WildFly.