LRA

Overview

Distributed transactions for microservices are known as SAGA design patterns and are defined by the MicroProfile Long Running Actions specification. Unlike well known XA protocol, LRA is asynchronous and therefore much more scalable. Every LRA JAX-RS resource (participant) defines endpoints to be invoked when transaction needs to be completed or compensated.

Maven Coordinates

To enable Long Running Actions, add the following dependency to your project’s pom.xml (see Managing Dependencies).

<dependencies>
  <dependency>
    <groupId>io.helidon.microprofile.lra</groupId>
    <artifactId>helidon-microprofile-lra</artifactId>
  </dependency>
  <!-- Support for Narayana coordinator -->
  <dependency>
    <groupId>io.helidon.lra</groupId>
    <artifactId>helidon-lra-coordinator-narayana-client</artifactId>
  </dependency>
</dependencies>

Usage

The LRA transactions need to be coordinated over REST API by the LRA coordinator. Coordinator keeps track of all transactions and calls the @Compensate or @Complete endpoints for all participants involved in the particular transaction. LRA transaction is first started, then joined by participant. The participant reports the successful finish of the transaction by calling it complete. The coordinator then calls the JAX-RS complete endpoint that was registered during the join of each participant. As the completed or compensated participants don’t have to be on same instance, the whole architecture is highly scalable.

If an error occurs during the LRA transaction, the participant reports a cancellation of LRA to the coordinator. Coordinator calls compensate on all the joined participants.

When a participant joins the LRA with timeout defined @LRA(value = LRA.Type.REQUIRES_NEW, timeLimit = 5, timeUnit = ChronoUnit.MINUTES), the coordinator compensates if the timeout occurred before the close is reported by the participants.

API

Participant

The Participant, or Compensator, is an LRA resource with at least one of the JAX-RS(or non-JAX-RS) methods annotated with @Compensate or @AfterLRA.

@LRA

See the Javadoc.

Marks JAX-RS method which should run in LRA context and needs to be accompanied by at least minimal set of mandatory participant methods(Compensate or AfterLRA).

LRA options:

• value
  • REQUIRED join incoming LRA or create and join new
  • REQUIRES_NEW create and join new LRA
  • MANDATORY join incoming LRA or fail
  • SUPPORTS join incoming LRA or continue outside LRA context
  • NOT_SUPPORTED always continue outside LRA context
  • NEVER Fail with 412 if executed in LRA context
  • NESTED create and join new LRA nested in the incoming LRA context
• timeLimit max time limit before LRA gets cancelled automatically by coordinator
• timeUnit time unit if the timeLimit value
• end when false LRA is not closed after successful method execution
• cancelOn which HTTP response codes of the method causes LRA to cancel
• cancelOnFamily which family of HTTP response codes causes LRA to cancel

Method parameters:

• Header LRA_HTTP_CONTEXT_HEADER - ID of the LRA transaction

@PUT
@LRA(value = LRA.Type.REQUIRES_NEW,
     timeLimit = 500,
     timeUnit = ChronoUnit.MILLIS)
@Path("start-example")
public Response startLra(
        @HeaderParam(LRA_HTTP_CONTEXT_HEADER) URI lraId,
        String data) {
    return Response.ok().build();
}

@Compensate

See the Javadoc.

Compensate method is called by a coordinator when LRA is cancelled, usually by error during execution of method body of @LRA annotated method. If the method responds with 500 or 202, coordinator will eventually try the call again. If participant has @Status annotated method, coordinator retrieves the status to find out if retry should be done.

JAX-RS variant with supported LRA context values:

• Header LRA_HTTP_CONTEXT_HEADER - ID of the LRA transaction
• Header LRA_HTTP_PARENT_CONTEXT_HEADER - parent LRA ID in case of nested LRA

@PUT
@Path("/compensate")
@Compensate
public Response compensateWork(
        @HeaderParam(LRA_HTTP_CONTEXT_HEADER) URI lraId,
        @HeaderParam(LRA_HTTP_PARENT_CONTEXT_HEADER) URI parent) {
    return LRAResponse.compensated();
}

Non JAX-RS variant with supported LRA context values:

• URI with LRA ID

@Compensate
public void compensate(URI lraId) {
}

@Complete

See the Javadoc.

Complete method is called by coordinator when LRA is successfully closed. If the method responds with 500 or 202, coordinator will eventually try the call again. If participant has @Status annotated method, coordinator retrieves the status to find out if retry should be done.

JAX-RS variant with supported LRA context values:

• Header LRA_HTTP_CONTEXT_HEADER - ID of the LRA transaction
• Header LRA_HTTP_PARENT_CONTEXT_HEADER - parent LRA ID in case of nested LRA

@PUT
@Path("/complete")
@Complete
public Response complete(
        @HeaderParam(LRA_HTTP_CONTEXT_HEADER) URI lraId,
        @HeaderParam(LRA_HTTP_PARENT_CONTEXT_HEADER) URI parentLraId) {
    return LRAResponse.completed();
}

Non JAX-RS variant with supported LRA context values:

• URI with LRA ID

@Complete
public void complete(URI lraId) {
}

@Forget

See the Javadoc.

Complete and compensate methods can fail(500) or report that compensation/completion is in progress(202). In such case participant needs to be prepared to report its status over @Status annotated method to coordinator. When coordinator decides all the participants have finished, method annotated with @Forget is called.

JAX-RS variant with supported LRA context values:

• Header LRA_HTTP_CONTEXT_HEADER - ID of the LRA transaction
• Header LRA_HTTP_PARENT_CONTEXT_HEADER - parent LRA ID in case of nested LRA

@DELETE
@Path("/forget")
@Forget
public Response forget(
        @HeaderParam(LRA_HTTP_CONTEXT_HEADER) URI lraId,
        @HeaderParam(LRA_HTTP_PARENT_CONTEXT_HEADER) URI parent) {
    return Response.noContent().build();
}

Non JAX-RS variant with supported LRA context values:

• URI with LRA ID

@Forget
public void forget(URI lraId) {
}

@Leave

See the Javadoc.

Method annotated with @Leave called with LRA context(with header LRA_HTTP_CONTEXT_HEADER) informs coordinator that current participant is leaving the LRA. Method body is executed after leave signal is sent. As a result, participant methods complete and compensate won’t be called when the particular LRA ends.

• Header LRA_HTTP_CONTEXT_HEADER - ID of the LRA transaction

@PUT
@Path("/leave")
@Leave
public Response leaveLRA(
        @HeaderParam(LRA_HTTP_CONTEXT_HEADER) URI lraIdtoLeave) {
    return Response.ok().build();
}

@Status

See the Javadoc.

If the coordinator’s call to the participant’s method fails, then it will retry the call. If the participant is not idempotent, then it may need to report its state to coordinator by declaring method annotated with @Status for reporting if previous call did change participant status. Coordinator can call it and decide if compensate or complete retry is needed.

JAX-RS variant with supported LRA context values:

• Header LRA_HTTP_CONTEXT_HEADER - ID of the LRA transaction
• ParticipantStatus - Status of the participant reported to coordinator

@GET
@Path("/status")
@Status
public Response reportStatus(
        @HeaderParam(LRA_HTTP_CONTEXT_HEADER) URI lraId) {
    return Response.ok(ParticipantStatus.FailedToCompensate)
        .build();
}

Non JAX-RS variant with supported LRA context values:

• URI with LRA ID
• ParticipantStatus - Status of the participant reported to coordinator

@Status
public Response reportStatus(URI lraId) {
    return Response.ok(ParticipantStatus.FailedToCompensate)
        .build();
}

@AfterLRA

See the Javadoc.

Method annotated with @AfterLRA in the same class as the one with @LRA annotation gets invoked after particular LRA finishes.

JAX-RS variant with supported LRA context values:

• Header LRA_HTTP_ENDED_CONTEXT_HEADER - ID of the finished LRA transaction
• Header LRA_HTTP_PARENT_CONTEXT_HEADER - parent LRA ID in case of nested LRA
• LRAStatus - Final status of the LRA (Cancelled, Closed, FailedToCancel, FailedToClose)

@PUT
@Path("/finished")
@AfterLRA
public Response whenLRAFinishes(
        @HeaderParam(LRA_HTTP_ENDED_CONTEXT_HEADER) URI lraId,
        @HeaderParam(LRA_HTTP_PARENT_CONTEXT_HEADER) URI parentLraId,
        LRAStatus status) {
    return Response.ok().build();
}

Non JAX-RS variant with supported LRA context values:

• URI with finished LRA ID
• LRAStatus - Final status of the LRA (Cancelled, Closed, FailedToCancel, FailedToClose)

public void whenLRAFinishes(URI lraId, LRAStatus status) {
}

Configuration

Optional configuration options:

Example of LRA configuration:

mp.lra:
  coordinator.url: http://localhost:8070/lra-coordinator <1>
  propagation.active: true <2>
  participant.url: https://coordinator.visible.host:443/awesomeapp <3>

For more information continue to MicroProfile Long Running Actions specification.

Examples

The following example shows how a simple LRA participant starts and joins a transaction after calling the '/start-example' resource. When startExample method finishes successfully, close is reported to coordinator and /complete-example endpoint is called by coordinator to confirm successful closure of the LRA.

If an exception occurs during startExample method execution, coordinator receives cancel call and /compensate-example is called by coordinator to compensate for cancelled LRA transaction.

Example of simple LRA participant:

@PUT
@LRA(LRA.Type.REQUIRES_NEW)1
@Path("start-example")
public Response startExample(@HeaderParam(LRA_HTTP_CONTEXT_HEADER) URI lraId,2
                             String data) {
    if (data.contains("BOOM")) {
        throw new RuntimeException("BOOM 💥");3
    }

    LOGGER.info("Data " + data + " processed 🏭");
    return Response.ok().build();4
}

@PUT
@Complete5
@Path("complete-example")
public Response completeExample(@HeaderParam(LRA_HTTP_CONTEXT_HEADER) URI lraId) {
    LOGGER.log(Level.INFO, "LRA ID: {0} completed 🎉", lraId);
    return LRAResponse.completed();
}

@PUT
@Compensate6
@Path("compensate-example")
public Response compensateExample(@HeaderParam(LRA_HTTP_CONTEXT_HEADER) URI lraId) {
    LOGGER.log(Level.SEVERE, "LRA ID: {0} compensated 🦺", lraId);
    return LRAResponse.compensated();
}

Testing

Testing of JAX-RS resources with LRA can be challenging as LRA participant running in parallel with the test is needed.

Helidon provides test coordinator which can be started automatically with additional socket on a random port within your own Helidon application. You only need one extra test dependency to enable test coordinator in your @HelidonTest.

Dependency:

<dependency>
  <groupId>io.helidon.microprofile.lra</groupId>
  <artifactId>helidon-microprofile-lra-testing</artifactId>
  <scope>test</scope>
</dependency>

Considering that you have LRA enabled JAX-RS resource you want to test.

Example JAX-RS resource with LRA:

@ApplicationScoped
@Path("/test")
public class WithdrawResource {

    private final List<String> completedLras = new CopyOnWriteArrayList<>();
    private final List<String> cancelledLras = new CopyOnWriteArrayList<>();

    @PUT
    @Path("/withdraw")
    @LRA(LRA.Type.REQUIRES_NEW)
    public Response withdraw(
            @HeaderParam(LRA.LRA_HTTP_CONTEXT_HEADER) Optional<URI> lraId,
            String content) {
        if ("BOOM".equals(content)) {
            throw new IllegalArgumentException("BOOM");
        }
        return Response.ok().build();
    }

    @Complete
    public void complete(URI lraId) {
        completedLras.add(lraId.toString());
    }

    @Compensate
    public void rollback(URI lraId) {
        cancelledLras.add(lraId.toString());
    }

    public List<String> getCompletedLras() {
        return completedLras;
    }
}

Helidon test with enabled CDI discovery can look like this.

HelidonTest with LRA test support:

@HelidonTest
//@AddBean(WithdrawResource.class)1
@AddBean(TestLraCoordinator.class)2
public class LraTest {

    @Inject
    private WithdrawResource withdrawTestResource;

    @Inject
    private TestLraCoordinator coordinator;3

    @Inject
    private WebTarget target;

    @Test
    public void testLraComplete() {
        try (Response res = target
                .path("/test/withdraw")
                .request()
                .put(Entity.entity("test", MediaType.TEXT_PLAIN_TYPE))) {
            assertThat(res.getStatus(), is(200));
            String lraId = res.getHeaderString(LRA.LRA_HTTP_CONTEXT_HEADER);
            Lra lra = coordinator.lra(lraId);4
            assertThat(lra.status(), is(LRAStatus.Closed));5
            assertThat(withdrawTestResource.getCompletedLras(), contains(lraId));
        }
    }
}

LRA testing feature has the following default configuration:

• port: 0 - coordinator is started on random port(Helidon LRA participant is capable to discover test coordinator automatically)
• bind-address: localhost - bind address of the coordinator
• helidon.lra.coordinator.persistence: false - LRAs managed by test coordinator are not persisted
• helidon.lra.participant.use-build-time-index: false - Participant annotation inspection ignores Jandex index files created in build time, it helps to avoid issues with additional test resources

Testing LRA coordinator is started on additional named socket test-lra-coordinator configured with default index 500. Default index can be changed with system property helidon.lra.coordinator.test-socket.index.

Example: -Dhelidon.lra.coordinator.test-socket.index=20.

HelidonTest override LRA test feature default settings:

@HelidonTest
@AddBean(TestLraCoordinator.class)
@AddConfig(key = "server.sockets.500.port", value = "8070")1
@AddConfig(key = "server.sockets.500.host", value = "custom.bind.name")2
@AddConfig(key = "helidon.lra.coordinator.persistence", value = "true")3
@AddConfig(key = "helidon.lra.participant.use-build-time-index", value = "true")4
public class LraCustomConfigTest {
}

When CDI bean auto-discovery is not desired, LRA and Config CDI extensions needs to be added manually.

HelidonTest setup with disabled discovery:

@HelidonTest
@DisableDiscovery
@AddJaxRs
@AddBean(TestLraCoordinator.class)
@AddExtension(LraCdiExtension.class)
@AddExtension(ConfigCdiExtension.class)
@AddBean(WithdrawResource.class)
public class LraNoDiscoveryTest {
}

Coordinator

Coordinator is a service that tracks all LRA transactions and calls the compensate REST endpoints of the participants when the LRA transaction gets cancelled or completes (in case it gets closed). In addition, participant also keeps track of timeouts, retries participant calls, and assigns LRA ids.

Helidon LRA supports following coordinators:

• MicroTx LRA coordinator
• Helidon LRA coordinator
• Narayana coordinator.

MicroTx Coordinator

Oracle Transaction Manager for Microservices - MicroTx is an enterprise grade transaction manager for microservices, among other it manages LRA transactions and is compatible with Narayana LRA clients.

MicroTx LRA coordinator is compatible with Narayana clients when narayanaLraCompatibilityMode is on, you need to add another dependency to enable Narayana client:

Dependency needed for using Helidon LRA with Narayana compatible coordinator:

<dependency>
  <groupId>io.helidon.lra</groupId>
  <artifactId>helidon-lra-coordinator-narayana-client</artifactId>
</dependency>

Run MicroTx in Docker:

docker container run --name otmm -v "$(pwd)":/app/config \
-w /app/config -p 8080:8080/tcp --env CONFIG_FILE=tcs.yaml \
--add-host host.docker.internal:host-gateway -d tmm:<version>

To use MicroTx with Helidon LRA participant, narayanaLraCompatibilityMode needs to be enabled.

Configure MicroTx for development:

tmmAppName: tcs
tmmConfiguration:
  listenAddr: 0.0.0.0:8080
  internalAddr: http://host.docker.internal:8080
  externalUrl: http://lra-coordinator.acme.com:8080
  xaCoordinator:
    enabled: false
  lraCoordinator:
    enabled: true
  tccCoordinator:
    enabled: false
  storage:
    type: memory
  authentication:
    enabled: false
  authorization:
    enabled: false
  serveTLS:
    enabled: false
  narayanaLraCompatibilityMode:
    enabled: true1

Helidon Coordinator

Build and run Helidon LRA coordinator:

docker build -t helidon/lra-coordinator https://github.com/helidon-io/helidon.git#:lra/coordinator/server
docker run --name lra-coordinator --network="host" helidon/lra-coordinator

Helidon LRA coordinator is compatible with Narayana clients, you need to add a dependency for Narayana client:

Dependency needed for using Helidon LRA with Narayana compatible coordinator:

<dependency>
  <groupId>io.helidon.lra</groupId>
  <artifactId>helidon-lra-coordinator-narayana-client</artifactId>
</dependency>

Narayana

Narayana is a transaction manager supporting LRA. To use Narayana LRA coordinator with Helidon LRA client you need to add a dependency for Narayana client:

Dependency needed for using Helidon LRA with Narayana coordinator:

<dependency>
  <groupId>io.helidon.lra</groupId>
  <artifactId>helidon-lra-coordinator-narayana-client</artifactId>
</dependency>

The simplest way to run Narayana LRA coordinator locally:

Downloading and running Narayana LRA coordinator:

curl https://repo1.maven.org/maven2/org/jboss/narayana/rts/lra-coordinator-quarkus/5.11.1.Final/lra-coordinator-quarkus-5.11.1.Final-runner.jar \
-o narayana-coordinator.jar
java -Dquarkus.http.port=8070 -jar narayana-coordinator.jar

Narayana LRA coordinator is running by default under lra-coordinator context, with port 8070 defined in the snippet above you need to configure your Helidon LRA app as follows: mp.lra.coordinator.url=http://localhost:8070/lra-coordinator

Reference

• MicroProfile LRA GitHub Repository
• MicroProfile Long Running Actions specification
• MicroProfile LRA Javadoc
• Helidon LRA Client Javadoc
• MicroTx - Oracle Transaction Manager for Microservices