gmunozfe commented on code in PR #2120: URL: https://github.com/apache/incubator-kie-kogito-examples/pull/2120#discussion_r2256598054
########## serverless-workflow-examples/serverless-workflow-fault-tolerance/src/main/docker/Dockerfile.native: ########## @@ -0,0 +1,29 @@ +#### +# This Dockerfile is used in order to build a container that runs the Quarkus application in native (no JVM) mode. +# +# Before building the container image run: +# +# ./mvnw package -Dnative +# +# Then, build the image with: +# +# docker build -f src/main/docker/Dockerfile.native -t quarkus/serverless-workflow-fault-tolerance . +# +# Then run the container using: +# +# docker run -i --rm -p 8080:8080 quarkus/serverless-workflow-fault-tolerance +# +# The ` registry.access.redhat.com/ubi9/ubi-minimal:9.5` base image is based on UBI 9. +# To use UBI 8, switch to `quay.io/ubi8/ubi-minimal:8.10`. +### +FROM registry.access.redhat.com/ubi9/ubi-minimal:9.5 Review Comment: And here ########## serverless-workflow-examples/serverless-workflow-fault-tolerance/src/main/docker/Dockerfile.jvm: ########## @@ -0,0 +1,98 @@ +#### +# This Dockerfile is used in order to build a container that runs the Quarkus application in JVM mode +# +# Before building the container image run: +# +# ./mvnw package +# +# Then, build the image with: +# +# docker build -f src/main/docker/Dockerfile.jvm -t quarkus/serverless-workflow-fault-tolerance-jvm . +# +# Then run the container using: +# +# docker run -i --rm -p 8080:8080 quarkus/serverless-workflow-fault-tolerance-jvm +# +# If you want to include the debug port into your docker image +# you will have to expose the debug port (default 5005 being the default) like this : EXPOSE 8080 5005. +# Additionally you will have to set -e JAVA_DEBUG=true and -e JAVA_DEBUG_PORT=*:5005 +# when running the container +# +# Then run the container using : +# +# docker run -i --rm -p 8080:8080 quarkus/serverless-workflow-fault-tolerance-jvm +# +# This image uses the `run-java.sh` script to run the application. +# This scripts computes the command line to execute your Java application, and +# includes memory/GC tuning. +# You can configure the behavior using the following environment properties: +# - JAVA_OPTS: JVM options passed to the `java` command (example: "-verbose:class") - Be aware that this will override +# the default JVM options, use `JAVA_OPTS_APPEND` to append options +# - JAVA_OPTS_APPEND: User specified Java options to be appended to generated options +# in JAVA_OPTS (example: "-Dsome.property=foo") +# - JAVA_MAX_MEM_RATIO: Is used when no `-Xmx` option is given in JAVA_OPTS. This is +# used to calculate a default maximal heap memory based on a containers restriction. +# If used in a container without any memory constraints for the container then this +# option has no effect. If there is a memory constraint then `-Xmx` is set to a ratio +# of the container available memory as set here. The default is `50` which means 50% +# of the available memory is used as an upper boundary. You can skip this mechanism by +# setting this value to `0` in which case no `-Xmx` option is added. +# - JAVA_INITIAL_MEM_RATIO: Is used when no `-Xms` option is given in JAVA_OPTS. This +# is used to calculate a default initial heap memory based on the maximum heap memory. +# If used in a container without any memory constraints for the container then this +# option has no effect. If there is a memory constraint then `-Xms` is set to a ratio +# of the `-Xmx` memory as set here. The default is `25` which means 25% of the `-Xmx` +# is used as the initial heap size. You can skip this mechanism by setting this value +# to `0` in which case no `-Xms` option is added (example: "25") +# - JAVA_MAX_INITIAL_MEM: Is used when no `-Xms` option is given in JAVA_OPTS. +# This is used to calculate the maximum value of the initial heap memory. If used in +# a container without any memory constraints for the container then this option has +# no effect. If there is a memory constraint then `-Xms` is limited to the value set +# here. The default is 4096MB which means the calculated value of `-Xms` never will +# be greater than 4096MB. The value of this variable is expressed in MB (example: "4096") +# - JAVA_DIAGNOSTICS: Set this to get some diagnostics information to standard output +# when things are happening. This option, if set to true, will set +# `-XX:+UnlockDiagnosticVMOptions`. Disabled by default (example: "true"). +# - JAVA_DEBUG: If set remote debugging will be switched on. Disabled by default (example: +# true"). +# - JAVA_DEBUG_PORT: Port used for remote debugging. Defaults to 5005 (example: "8787"). +# - CONTAINER_CORE_LIMIT: A calculated core limit as described in +# https://www.kernel.org/doc/Documentation/scheduler/sched-bwc.txt. (example: "2") +# - CONTAINER_MAX_MEMORY: Memory limit given to the container (example: "1024"). +# - GC_MIN_HEAP_FREE_RATIO: Minimum percentage of heap free after GC to avoid expansion. +# (example: "20") +# - GC_MAX_HEAP_FREE_RATIO: Maximum percentage of heap free after GC to avoid shrinking. +# (example: "40") +# - GC_TIME_RATIO: Specifies the ratio of the time spent outside the garbage collection. +# (example: "4") +# - GC_ADAPTIVE_SIZE_POLICY_WEIGHT: The weighting given to the current GC time versus +# previous GC times. (example: "90") +# - GC_METASPACE_SIZE: The initial metaspace size. (example: "20") +# - GC_MAX_METASPACE_SIZE: The maximum metaspace size. (example: "100") +# - GC_CONTAINER_OPTIONS: Specify Java GC to use. The value of this variable should +# contain the necessary JRE command-line options to specify the required GC, which +# will override the default of `-XX:+UseParallelGC` (example: -XX:+UseG1GC). +# - HTTPS_PROXY: The location of the https proxy. (example: "[email protected]:8080") +# - HTTP_PROXY: The location of the http proxy. (example: "[email protected]:8080") +# - NO_PROXY: A comma separated lists of hosts, IP addresses or domains that can be +# accessed directly. (example: "foo.example.com,bar.example.com") +# +### +FROM registry.access.redhat.com/ubi9/openjdk-17:1.21 Review Comment: I think this is less flexible for community outside RHEL/openshift, perhaps Temurin distribution is more widely accepted, wdyt? ########## serverless-workflow-examples/serverless-workflow-fault-tolerance/Readme.md: ########## @@ -0,0 +1,235 @@ +# Kogito Serverless Workflow Fault Tolerance + +This example shows how to configure fault tolerance alternatives when you work with workflows. + +## Circuit Breaker Pattern + +Every REST call executed by a workflow can be configured to use the Circuit Breaker Pattern. + + + +The internals of the pattern configuration and execution are based on the [MicroProfile Fault Tolerance](https://github.com/eclipse/microprofile-fault-tolerance/) specification, +and the corresponding [Smallrye Fault Tolerance](https://github.com/smallrye/smallrye-fault-tolerance) implementation shipped with Quarkus. + +The following example shows how to configure the [call-echo](src/main/resources/call-echo.sw.yml) workflow to use the Circuit Breaker Pattern to execute the `circuitBreakerEcho` operation provided by the [external-service](src/main/resources/specs/external-service.yaml). + +### Build time configurations + + +To enable and configure the Circuit Breaker you must follow this procedure: + +1. Add the following maven dependency to your project: +```` +<dependency> + <groupId>io.quarkus</groupId> + <artifactId>quarkus-smallrye-fault-tolerance</artifactId> +</dependency> +```` + +2. Enable the Circuit Breaker + +When a workflow use REST calls, behind the scene, a set of classes are generated to support these invocations. Review Comment: typo: ```suggestion When a workflow uses REST calls, behind the scene, a set of classes are generated to support these invocations. ``` ########## serverless-workflow-examples/serverless-workflow-fault-tolerance/Readme.md: ########## @@ -0,0 +1,235 @@ +# Kogito Serverless Workflow Fault Tolerance + +This example shows how to configure fault tolerance alternatives when you work with workflows. + +## Circuit Breaker Pattern + +Every REST call executed by a workflow can be configured to use the Circuit Breaker Pattern. + + + +The internals of the pattern configuration and execution are based on the [MicroProfile Fault Tolerance](https://github.com/eclipse/microprofile-fault-tolerance/) specification, +and the corresponding [Smallrye Fault Tolerance](https://github.com/smallrye/smallrye-fault-tolerance) implementation shipped with Quarkus. + +The following example shows how to configure the [call-echo](src/main/resources/call-echo.sw.yml) workflow to use the Circuit Breaker Pattern to execute the `circuitBreakerEcho` operation provided by the [external-service](src/main/resources/specs/external-service.yaml). + +### Build time configurations + + +To enable and configure the Circuit Breaker you must follow this procedure: + +1. Add the following maven dependency to your project: +```` +<dependency> + <groupId>io.quarkus</groupId> + <artifactId>quarkus-smallrye-fault-tolerance</artifactId> +</dependency> +```` + +2. Enable the Circuit Breaker + +When a workflow use REST calls, behind the scene, a set of classes are generated to support these invocations. +In general, the generation is transparent, and you don't need to pay attention on it. + +However, to enable the Circuit Breaker, you must provide some configurations that are related to that generation, and impacts the generated code. + +The first step is to find the generated Java class name that is registered as the Microprofile Rest Client to access the external service. + +The following picture shows how this class name is calculated at code generation time: + + + +We recommend that you build the project and inspect the generated sources under the directory `target/generated-sources/open-api-stream/org/kie/kogito/openapi`: + + + + +When the Circuit Breaker is not configured, the generated signature for the Java method corresponding to the `circuitBreakerEcho` operation will look like this: + +```` [email protected](name="", openApiSpecId="external_service_yaml", operationId="circuitBreakerEcho", method="POST", path="/external-service/circuit-breaker") [email protected] [email protected]("/circuit-breaker") [email protected]({"text/plain"}) [email protected]({"application/json"}) [email protected]("circuitBreakerEcho") +public EchoResponse circuitBreakerEcho( + String body +); +```` + +Given the class name `org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi`, and the method `circuitBreakerEcho`, +to enable the Circuit Breaker, you must add the following entry in the `application.properties`: + +```` +org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho/CircuitBreaker/enabled=true +```` + +> **NOTE:** Every operation must be configured individually, and different operations might be located in different classes. + +After adding the configuration, the next build will generate the following signature: + +```` [email protected](name="", openApiSpecId="external_service_yaml", operationId="circuitBreakerEcho", method="POST", path="/external-service/circuit-breaker") [email protected] [email protected]("/circuit-breaker") [email protected]({"text/plain"}) [email protected]({"application/json"}) [email protected]("circuitBreakerEcho") [email protected] +public EchoResponse circuitBreakerEcho( + String body +); +```` + +If the `@org.eclipse.microprofile.faulttolerance.CircuitBreaker` annotation is present in the generated method signature, +it means that the configuration was set correct. + +If you don't see the annotation, we recommend that you navigate and look into the generated sources to find the correct class name, or any potential typo in the property name, etc. + +3. Configure other behavioural properties: + +The build time behavioural properties are used to define configurations like thresholds and delays, for more information [see](https://quarkus.io/version/3.20/guides/smallrye-fault-tolerance#configuration-reference). + +To set these properties you must use the prefix `quarkus.fault-tolerance."org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho"`. + +Below is the configuration used for the example: + +```` +# Build time property to add the Circuit Breaker capability to the corresponding generated class/method, by annotating +# it with the eclipse microprofile @org.eclipse.microprofile.faulttolerance.CircuitBreaker. +# This property doesn't follow the quarkus.fault-tolerance.xxx prefix, you must use this format. +org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho/CircuitBreaker/enabled=true + +# Configuration values for the sake of current example. Produces a quick circuit Open, and a long delayed transitioning +# to the Half Closed state. Don't consider this as suggested configurations for a production system. + +# Use a rolling window of 4 consecutive requests +quarkus.fault-tolerance."org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho".circuit-breaker.request-volume-threshold=4 +# With a ratio of .5, if 2 requests fail, the circuit is Opened. +quarkus.fault-tolerance."org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho".circuit-breaker.failure-ratio=0.5 + +# Wait 2 minutes before the Open circuit goes to the Half Open state. +quarkus.fault-tolerance."org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho".circuit-breaker.delay=2 +quarkus.fault-tolerance."org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho".circuit-breaker.delay-unit=minutes +```` + +### Executing the example + +#### Prerequisites + +You will need: +- Java 17+ installed +- Environment variable JAVA_HOME set accordingly +- Maven 3.9.6+ installed + +##### Executing in Quarkus Dev mode + +To see the Circuit Breaker behaviour, we recommend that you follow this procedure: + +1. Start the workflow: + +```` +mvn quarkus:dev +```` + +2. Execute the workflow to verify a regular execution (without errors): + +```` +curl -X 'POST' \ +'http://localhost:8080/call-echo' \ +-H 'accept: */*' \ +-H 'Content-Type: application/json' \ +-d '{ "echo" : "Hello!" }' +```` + +You will see an output like this: + +```` +{ + "id": "2de57de7-38f7-4a33-bb7e-670bedefbcf1", + "workflowdata": { + "echo": "Hello!", + "echoResult": { + "id": "cf3405af-c903-4a7f-86cc-d2287d383d36", + "echo": "Hello!", + "createdAt": "2025-08-04T12:03:35.705894795+02:00[Europe/Madrid]" + } + } +} +```` + +3. Configure the external service `circuitBreakerEcho` operation to fail using the following command:\ +The external-service was designed to fail intentionally upon configuration. + +```` +curl -X 'POST' \ + 'http://localhost:8080/external-service/admin' \ + -H 'accept: */*' \ + -H 'Content-Type: application/json' \ + -d '{ + "operation": "circuitBreakerEcho", + "enabled": false +}' +```` + +4. Execute the workflow again with the following command: + +```` +curl -X 'POST' \ +'http://localhost:8080/call-echo' \ +-H 'accept: */*' \ +-H 'Content-Type: application/json' \ +-d '{ "echo" : "Hello!" }' +```` + +This time you will see an output with the HTTP 500 error code. This means that the workflow has executed the regular +call to the external service `circuitBreakerEcho` operation, and has got the error. The circuit is in the `Closed` status. +```` +{ + "errorCode": "500", + "failedNodeId": "6", + "id": "5e731491-8850-44de-a3c5-a68fd2817af6", + "message": "HTTP 500 Internal Server Error" +} +```` + +5. Repeat 3 or more executions, and this time, you will start to see the following result: + +```` +{ + "failedNodeId": "6", + "id": "f3f12ca3-2a1e-4267-9d82-a0ee3d9acd80", + "message": "org.eclipse.microprofile.faulttolerance.exceptions.CircuitBreakerOpenException - org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi#circuitBreakerEcho circuit breaker is open" +} +```` + +This means that circuit has transitioned to the `Open` status, and thus, no call to external service is produced. +Instead, the fault tolerance layer is producing the error. + +6. Configure the external service `circuitBreakerEcho` operation to go back to normal execution with the following command: + +```` +curl -X 'POST' \ + 'http://localhost:8080/external-service/admin' \ + -H 'accept: */*' \ + -H 'Content-Type: application/json' \ + -d '{ + "operation": "circuitBreakerEcho", + "enabled": true +}' +```` + +This time, the external service will not fail if executed, however, if you repeat the workflow execution during the next 2 minutes, +you will continue getting the org.eclipse.microprofile.faulttolerance.exceptions.CircuitBreakerOpenException, since +the circuit will continues in the `Open` status because of the following configuration: Review Comment: typo ```suggestion the circuit will remain in the `Open` status because of the following configuration: ``` ########## serverless-workflow-examples/serverless-workflow-fault-tolerance/src/test/java/org/kie/kogito/examples/CallEchoIT.java: ########## @@ -0,0 +1,76 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.kie.kogito.examples; + +import io.quarkus.test.junit.QuarkusIntegrationTest; +import io.restassured.http.ContentType; +import io.restassured.path.json.JsonPath; +import io.restassured.response.ValidatableResponse; +import org.junit.jupiter.api.Test; + +import static io.restassured.RestAssured.given; +import static org.junit.jupiter.api.Assertions.assertTrue; + +@QuarkusIntegrationTest +class CallEchoIT { + + private static final String ACCESS_CIRCUIT_BREAKER_ECHO_ERROR = "HTTP 500 Internal Server Error"; + private static final String ACCESS_OPEN_CIRCUIT_ERROR = "org.eclipse.microprofile.faulttolerance.exceptions.CircuitBreakerOpenException"; + + @Test + void circuitBreakerEcho() { + // regular call, no failure. + prepareCircuitBreakerCall().statusCode(201); + + // program the circuitBreakerEcho operation to fail. + given() + .contentType(ContentType.JSON) + .accept(ContentType.JSON) + .body("{\"operation\" : \"circuitBreakerEcho\", \"enabled\" : false}").when() + .post("/external-service/admin") + .then() + .statusCode(200); + + // next 3 calls must fail with "HTTP 500 Internal Server Error" + assertCallEcoStartsWithMessage(ACCESS_CIRCUIT_BREAKER_ECHO_ERROR); + assertCallEcoStartsWithMessage(ACCESS_CIRCUIT_BREAKER_ECHO_ERROR); + assertCallEcoStartsWithMessage(ACCESS_CIRCUIT_BREAKER_ECHO_ERROR); + + // fourth call must fail due to the Open circuit. + assertCallEcoStartsWithMessage(ACCESS_OPEN_CIRCUIT_ERROR); + } + + private static void assertCallEcoStartsWithMessage(String prefix) { Review Comment: typo? ```suggestion private static void assertCallEchoStartsWithMessage(String prefix) { ``` ########## serverless-workflow-examples/serverless-workflow-fault-tolerance/src/test/java/org/kie/kogito/examples/CallEchoIT.java: ########## @@ -0,0 +1,76 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.kie.kogito.examples; + +import io.quarkus.test.junit.QuarkusIntegrationTest; +import io.restassured.http.ContentType; +import io.restassured.path.json.JsonPath; +import io.restassured.response.ValidatableResponse; +import org.junit.jupiter.api.Test; + +import static io.restassured.RestAssured.given; +import static org.junit.jupiter.api.Assertions.assertTrue; + +@QuarkusIntegrationTest +class CallEchoIT { Review Comment: I think your coverage is good for an example. One enhancement would be to add a test for circuitbreaker "recovery" after 2 minutes, reenabling the service and checking that the circuit is again in half-open state, but as this slows down the testing, probably it's out of the scope for this example. ########## serverless-workflow-examples/serverless-workflow-fault-tolerance/src/main/docker/Dockerfile.legacy-jar: ########## @@ -0,0 +1,94 @@ +#### +# This Dockerfile is used in order to build a container that runs the Quarkus application in JVM mode +# +# Before building the container image run: +# +# ./mvnw package -Dquarkus.package.jar.type=legacy-jar +# +# Then, build the image with: +# +# docker build -f src/main/docker/Dockerfile.legacy-jar -t quarkus/serverless-workflow-fault-tolerance-legacy-jar . +# +# Then run the container using: +# +# docker run -i --rm -p 8080:8080 quarkus/serverless-workflow-fault-tolerance-legacy-jar +# +# If you want to include the debug port into your docker image +# you will have to expose the debug port (default 5005 being the default) like this : EXPOSE 8080 5005. +# Additionally you will have to set -e JAVA_DEBUG=true and -e JAVA_DEBUG_PORT=*:5005 +# when running the container +# +# Then run the container using : +# +# docker run -i --rm -p 8080:8080 quarkus/serverless-workflow-fault-tolerance-legacy-jar +# +# This image uses the `run-java.sh` script to run the application. +# This scripts computes the command line to execute your Java application, and +# includes memory/GC tuning. +# You can configure the behavior using the following environment properties: +# - JAVA_OPTS: JVM options passed to the `java` command (example: "-verbose:class") - Be aware that this will override +# the default JVM options, use `JAVA_OPTS_APPEND` to append options +# - JAVA_OPTS_APPEND: User specified Java options to be appended to generated options +# in JAVA_OPTS (example: "-Dsome.property=foo") +# - JAVA_MAX_MEM_RATIO: Is used when no `-Xmx` option is given in JAVA_OPTS. This is +# used to calculate a default maximal heap memory based on a containers restriction. +# If used in a container without any memory constraints for the container then this +# option has no effect. If there is a memory constraint then `-Xmx` is set to a ratio +# of the container available memory as set here. The default is `50` which means 50% +# of the available memory is used as an upper boundary. You can skip this mechanism by +# setting this value to `0` in which case no `-Xmx` option is added. +# - JAVA_INITIAL_MEM_RATIO: Is used when no `-Xms` option is given in JAVA_OPTS. This +# is used to calculate a default initial heap memory based on the maximum heap memory. +# If used in a container without any memory constraints for the container then this +# option has no effect. If there is a memory constraint then `-Xms` is set to a ratio +# of the `-Xmx` memory as set here. The default is `25` which means 25% of the `-Xmx` +# is used as the initial heap size. You can skip this mechanism by setting this value +# to `0` in which case no `-Xms` option is added (example: "25") +# - JAVA_MAX_INITIAL_MEM: Is used when no `-Xms` option is given in JAVA_OPTS. +# This is used to calculate the maximum value of the initial heap memory. If used in +# a container without any memory constraints for the container then this option has +# no effect. If there is a memory constraint then `-Xms` is limited to the value set +# here. The default is 4096MB which means the calculated value of `-Xms` never will +# be greater than 4096MB. The value of this variable is expressed in MB (example: "4096") +# - JAVA_DIAGNOSTICS: Set this to get some diagnostics information to standard output +# when things are happening. This option, if set to true, will set +# `-XX:+UnlockDiagnosticVMOptions`. Disabled by default (example: "true"). +# - JAVA_DEBUG: If set remote debugging will be switched on. Disabled by default (example: +# true"). +# - JAVA_DEBUG_PORT: Port used for remote debugging. Defaults to 5005 (example: "8787"). +# - CONTAINER_CORE_LIMIT: A calculated core limit as described in +# https://www.kernel.org/doc/Documentation/scheduler/sched-bwc.txt. (example: "2") +# - CONTAINER_MAX_MEMORY: Memory limit given to the container (example: "1024"). +# - GC_MIN_HEAP_FREE_RATIO: Minimum percentage of heap free after GC to avoid expansion. +# (example: "20") +# - GC_MAX_HEAP_FREE_RATIO: Maximum percentage of heap free after GC to avoid shrinking. +# (example: "40") +# - GC_TIME_RATIO: Specifies the ratio of the time spent outside the garbage collection. +# (example: "4") +# - GC_ADAPTIVE_SIZE_POLICY_WEIGHT: The weighting given to the current GC time versus +# previous GC times. (example: "90") +# - GC_METASPACE_SIZE: The initial metaspace size. (example: "20") +# - GC_MAX_METASPACE_SIZE: The maximum metaspace size. (example: "100") +# - GC_CONTAINER_OPTIONS: Specify Java GC to use. The value of this variable should +# contain the necessary JRE command-line options to specify the required GC, which +# will override the default of `-XX:+UseParallelGC` (example: -XX:+UseG1GC). +# - HTTPS_PROXY: The location of the https proxy. (example: "[email protected]:8080") +# - HTTP_PROXY: The location of the http proxy. (example: "[email protected]:8080") +# - NO_PROXY: A comma separated lists of hosts, IP addresses or domains that can be +# accessed directly. (example: "foo.example.com,bar.example.com") +# +### +FROM registry.access.redhat.com/ubi9/openjdk-17:1.21 Review Comment: Same here ########## serverless-workflow-examples/serverless-workflow-fault-tolerance/src/test/java/org/kie/kogito/examples/CallEchoIT.java: ########## @@ -0,0 +1,76 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.kie.kogito.examples; + +import io.quarkus.test.junit.QuarkusIntegrationTest; +import io.restassured.http.ContentType; +import io.restassured.path.json.JsonPath; +import io.restassured.response.ValidatableResponse; +import org.junit.jupiter.api.Test; + +import static io.restassured.RestAssured.given; +import static org.junit.jupiter.api.Assertions.assertTrue; + +@QuarkusIntegrationTest +class CallEchoIT { + + private static final String ACCESS_CIRCUIT_BREAKER_ECHO_ERROR = "HTTP 500 Internal Server Error"; + private static final String ACCESS_OPEN_CIRCUIT_ERROR = "org.eclipse.microprofile.faulttolerance.exceptions.CircuitBreakerOpenException"; + + @Test + void circuitBreakerEcho() { + // regular call, no failure. + prepareCircuitBreakerCall().statusCode(201); + + // program the circuitBreakerEcho operation to fail. + given() + .contentType(ContentType.JSON) + .accept(ContentType.JSON) + .body("{\"operation\" : \"circuitBreakerEcho\", \"enabled\" : false}").when() + .post("/external-service/admin") + .then() + .statusCode(200); + + // next 3 calls must fail with "HTTP 500 Internal Server Error" + assertCallEcoStartsWithMessage(ACCESS_CIRCUIT_BREAKER_ECHO_ERROR); + assertCallEcoStartsWithMessage(ACCESS_CIRCUIT_BREAKER_ECHO_ERROR); + assertCallEcoStartsWithMessage(ACCESS_CIRCUIT_BREAKER_ECHO_ERROR); + + // fourth call must fail due to the Open circuit. + assertCallEcoStartsWithMessage(ACCESS_OPEN_CIRCUIT_ERROR); Review Comment: typoes? ```suggestion assertCallEchoStartsWithMessage(ACCESS_CIRCUIT_BREAKER_ECHO_ERROR); assertCallEchoStartsWithMessage(ACCESS_CIRCUIT_BREAKER_ECHO_ERROR); assertCallEchoStartsWithMessage(ACCESS_CIRCUIT_BREAKER_ECHO_ERROR); // fourth call must fail due to the Open circuit. assertCallEchoStartsWithMessage(ACCESS_OPEN_CIRCUIT_ERROR); ``` ########## serverless-workflow-examples/serverless-workflow-fault-tolerance/Readme.md: ########## @@ -0,0 +1,235 @@ +# Kogito Serverless Workflow Fault Tolerance + +This example shows how to configure fault tolerance alternatives when you work with workflows. + +## Circuit Breaker Pattern + +Every REST call executed by a workflow can be configured to use the Circuit Breaker Pattern. + + + +The internals of the pattern configuration and execution are based on the [MicroProfile Fault Tolerance](https://github.com/eclipse/microprofile-fault-tolerance/) specification, +and the corresponding [Smallrye Fault Tolerance](https://github.com/smallrye/smallrye-fault-tolerance) implementation shipped with Quarkus. + +The following example shows how to configure the [call-echo](src/main/resources/call-echo.sw.yml) workflow to use the Circuit Breaker Pattern to execute the `circuitBreakerEcho` operation provided by the [external-service](src/main/resources/specs/external-service.yaml). + +### Build time configurations + + +To enable and configure the Circuit Breaker you must follow this procedure: + +1. Add the following maven dependency to your project: +```` +<dependency> + <groupId>io.quarkus</groupId> + <artifactId>quarkus-smallrye-fault-tolerance</artifactId> +</dependency> +```` + +2. Enable the Circuit Breaker + +When a workflow use REST calls, behind the scene, a set of classes are generated to support these invocations. +In general, the generation is transparent, and you don't need to pay attention on it. + +However, to enable the Circuit Breaker, you must provide some configurations that are related to that generation, and impacts the generated code. + +The first step is to find the generated Java class name that is registered as the Microprofile Rest Client to access the external service. + +The following picture shows how this class name is calculated at code generation time: + + + +We recommend that you build the project and inspect the generated sources under the directory `target/generated-sources/open-api-stream/org/kie/kogito/openapi`: + + + + +When the Circuit Breaker is not configured, the generated signature for the Java method corresponding to the `circuitBreakerEcho` operation will look like this: + +```` [email protected](name="", openApiSpecId="external_service_yaml", operationId="circuitBreakerEcho", method="POST", path="/external-service/circuit-breaker") [email protected] [email protected]("/circuit-breaker") [email protected]({"text/plain"}) [email protected]({"application/json"}) [email protected]("circuitBreakerEcho") +public EchoResponse circuitBreakerEcho( + String body +); +```` + +Given the class name `org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi`, and the method `circuitBreakerEcho`, +to enable the Circuit Breaker, you must add the following entry in the `application.properties`: + +```` +org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho/CircuitBreaker/enabled=true +```` + +> **NOTE:** Every operation must be configured individually, and different operations might be located in different classes. + +After adding the configuration, the next build will generate the following signature: + +```` [email protected](name="", openApiSpecId="external_service_yaml", operationId="circuitBreakerEcho", method="POST", path="/external-service/circuit-breaker") [email protected] [email protected]("/circuit-breaker") [email protected]({"text/plain"}) [email protected]({"application/json"}) [email protected]("circuitBreakerEcho") [email protected] +public EchoResponse circuitBreakerEcho( + String body +); +```` + +If the `@org.eclipse.microprofile.faulttolerance.CircuitBreaker` annotation is present in the generated method signature, +it means that the configuration was set correct. + +If you don't see the annotation, we recommend that you navigate and look into the generated sources to find the correct class name, or any potential typo in the property name, etc. + +3. Configure other behavioural properties: + +The build time behavioural properties are used to define configurations like thresholds and delays, for more information [see](https://quarkus.io/version/3.20/guides/smallrye-fault-tolerance#configuration-reference). + +To set these properties you must use the prefix `quarkus.fault-tolerance."org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho"`. + +Below is the configuration used for the example: + +```` +# Build time property to add the Circuit Breaker capability to the corresponding generated class/method, by annotating +# it with the eclipse microprofile @org.eclipse.microprofile.faulttolerance.CircuitBreaker. +# This property doesn't follow the quarkus.fault-tolerance.xxx prefix, you must use this format. +org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho/CircuitBreaker/enabled=true + +# Configuration values for the sake of current example. Produces a quick circuit Open, and a long delayed transitioning +# to the Half Closed state. Don't consider this as suggested configurations for a production system. + +# Use a rolling window of 4 consecutive requests +quarkus.fault-tolerance."org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho".circuit-breaker.request-volume-threshold=4 +# With a ratio of .5, if 2 requests fail, the circuit is Opened. +quarkus.fault-tolerance."org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho".circuit-breaker.failure-ratio=0.5 + +# Wait 2 minutes before the Open circuit goes to the Half Open state. +quarkus.fault-tolerance."org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho".circuit-breaker.delay=2 +quarkus.fault-tolerance."org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho".circuit-breaker.delay-unit=minutes +```` + +### Executing the example + +#### Prerequisites + +You will need: +- Java 17+ installed +- Environment variable JAVA_HOME set accordingly +- Maven 3.9.6+ installed + +##### Executing in Quarkus Dev mode + +To see the Circuit Breaker behaviour, we recommend that you follow this procedure: + +1. Start the workflow: + +```` +mvn quarkus:dev +```` + +2. Execute the workflow to verify a regular execution (without errors): + +```` +curl -X 'POST' \ +'http://localhost:8080/call-echo' \ +-H 'accept: */*' \ +-H 'Content-Type: application/json' \ +-d '{ "echo" : "Hello!" }' +```` + +You will see an output like this: + +```` +{ + "id": "2de57de7-38f7-4a33-bb7e-670bedefbcf1", + "workflowdata": { + "echo": "Hello!", + "echoResult": { + "id": "cf3405af-c903-4a7f-86cc-d2287d383d36", + "echo": "Hello!", + "createdAt": "2025-08-04T12:03:35.705894795+02:00[Europe/Madrid]" + } + } +} +```` + +3. Configure the external service `circuitBreakerEcho` operation to fail using the following command:\ +The external-service was designed to fail intentionally upon configuration. + +```` +curl -X 'POST' \ + 'http://localhost:8080/external-service/admin' \ + -H 'accept: */*' \ + -H 'Content-Type: application/json' \ + -d '{ + "operation": "circuitBreakerEcho", + "enabled": false +}' +```` + +4. Execute the workflow again with the following command: + +```` +curl -X 'POST' \ +'http://localhost:8080/call-echo' \ +-H 'accept: */*' \ +-H 'Content-Type: application/json' \ +-d '{ "echo" : "Hello!" }' +```` + +This time you will see an output with the HTTP 500 error code. This means that the workflow has executed the regular +call to the external service `circuitBreakerEcho` operation, and has got the error. The circuit is in the `Closed` status. +```` +{ + "errorCode": "500", + "failedNodeId": "6", + "id": "5e731491-8850-44de-a3c5-a68fd2817af6", + "message": "HTTP 500 Internal Server Error" +} +```` + +5. Repeat 3 or more executions, and this time, you will start to see the following result: + +```` +{ + "failedNodeId": "6", + "id": "f3f12ca3-2a1e-4267-9d82-a0ee3d9acd80", + "message": "org.eclipse.microprofile.faulttolerance.exceptions.CircuitBreakerOpenException - org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi#circuitBreakerEcho circuit breaker is open" +} +```` + +This means that circuit has transitioned to the `Open` status, and thus, no call to external service is produced. Review Comment: you could add the name of the operation for being more crystal clear: "no call to the _circuitBreakerEcho_ operation is made, because the circuit is open. ########## serverless-workflow-examples/serverless-workflow-fault-tolerance/Readme.md: ########## @@ -0,0 +1,235 @@ +# Kogito Serverless Workflow Fault Tolerance + +This example shows how to configure fault tolerance alternatives when you work with workflows. + +## Circuit Breaker Pattern + +Every REST call executed by a workflow can be configured to use the Circuit Breaker Pattern. + + + +The internals of the pattern configuration and execution are based on the [MicroProfile Fault Tolerance](https://github.com/eclipse/microprofile-fault-tolerance/) specification, +and the corresponding [Smallrye Fault Tolerance](https://github.com/smallrye/smallrye-fault-tolerance) implementation shipped with Quarkus. + +The following example shows how to configure the [call-echo](src/main/resources/call-echo.sw.yml) workflow to use the Circuit Breaker Pattern to execute the `circuitBreakerEcho` operation provided by the [external-service](src/main/resources/specs/external-service.yaml). + +### Build time configurations + + +To enable and configure the Circuit Breaker you must follow this procedure: + +1. Add the following maven dependency to your project: +```` +<dependency> + <groupId>io.quarkus</groupId> + <artifactId>quarkus-smallrye-fault-tolerance</artifactId> +</dependency> +```` + +2. Enable the Circuit Breaker + +When a workflow use REST calls, behind the scene, a set of classes are generated to support these invocations. +In general, the generation is transparent, and you don't need to pay attention on it. + +However, to enable the Circuit Breaker, you must provide some configurations that are related to that generation, and impacts the generated code. + +The first step is to find the generated Java class name that is registered as the Microprofile Rest Client to access the external service. + +The following picture shows how this class name is calculated at code generation time: + + + +We recommend that you build the project and inspect the generated sources under the directory `target/generated-sources/open-api-stream/org/kie/kogito/openapi`: + + + + +When the Circuit Breaker is not configured, the generated signature for the Java method corresponding to the `circuitBreakerEcho` operation will look like this: + +```` [email protected](name="", openApiSpecId="external_service_yaml", operationId="circuitBreakerEcho", method="POST", path="/external-service/circuit-breaker") [email protected] [email protected]("/circuit-breaker") [email protected]({"text/plain"}) [email protected]({"application/json"}) [email protected]("circuitBreakerEcho") +public EchoResponse circuitBreakerEcho( + String body +); +```` + +Given the class name `org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi`, and the method `circuitBreakerEcho`, +to enable the Circuit Breaker, you must add the following entry in the `application.properties`: + +```` +org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho/CircuitBreaker/enabled=true +```` + +> **NOTE:** Every operation must be configured individually, and different operations might be located in different classes. + +After adding the configuration, the next build will generate the following signature: + +```` [email protected](name="", openApiSpecId="external_service_yaml", operationId="circuitBreakerEcho", method="POST", path="/external-service/circuit-breaker") [email protected] [email protected]("/circuit-breaker") [email protected]({"text/plain"}) [email protected]({"application/json"}) [email protected]("circuitBreakerEcho") [email protected] +public EchoResponse circuitBreakerEcho( + String body +); +```` + +If the `@org.eclipse.microprofile.faulttolerance.CircuitBreaker` annotation is present in the generated method signature, +it means that the configuration was set correct. + +If you don't see the annotation, we recommend that you navigate and look into the generated sources to find the correct class name, or any potential typo in the property name, etc. + +3. Configure other behavioural properties: + +The build time behavioural properties are used to define configurations like thresholds and delays, for more information [see](https://quarkus.io/version/3.20/guides/smallrye-fault-tolerance#configuration-reference). + +To set these properties you must use the prefix `quarkus.fault-tolerance."org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho"`. + +Below is the configuration used for the example: + +```` +# Build time property to add the Circuit Breaker capability to the corresponding generated class/method, by annotating +# it with the eclipse microprofile @org.eclipse.microprofile.faulttolerance.CircuitBreaker. +# This property doesn't follow the quarkus.fault-tolerance.xxx prefix, you must use this format. +org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho/CircuitBreaker/enabled=true + +# Configuration values for the sake of current example. Produces a quick circuit Open, and a long delayed transitioning +# to the Half Closed state. Don't consider this as suggested configurations for a production system. + +# Use a rolling window of 4 consecutive requests +quarkus.fault-tolerance."org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho".circuit-breaker.request-volume-threshold=4 +# With a ratio of .5, if 2 requests fail, the circuit is Opened. +quarkus.fault-tolerance."org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho".circuit-breaker.failure-ratio=0.5 + +# Wait 2 minutes before the Open circuit goes to the Half Open state. +quarkus.fault-tolerance."org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho".circuit-breaker.delay=2 +quarkus.fault-tolerance."org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho".circuit-breaker.delay-unit=minutes +```` + +### Executing the example + +#### Prerequisites + +You will need: +- Java 17+ installed +- Environment variable JAVA_HOME set accordingly +- Maven 3.9.6+ installed + +##### Executing in Quarkus Dev mode + +To see the Circuit Breaker behaviour, we recommend that you follow this procedure: + +1. Start the workflow: + +```` +mvn quarkus:dev +```` + +2. Execute the workflow to verify a regular execution (without errors): + +```` +curl -X 'POST' \ +'http://localhost:8080/call-echo' \ +-H 'accept: */*' \ +-H 'Content-Type: application/json' \ +-d '{ "echo" : "Hello!" }' +```` + +You will see an output like this: + +```` +{ + "id": "2de57de7-38f7-4a33-bb7e-670bedefbcf1", + "workflowdata": { + "echo": "Hello!", + "echoResult": { + "id": "cf3405af-c903-4a7f-86cc-d2287d383d36", + "echo": "Hello!", + "createdAt": "2025-08-04T12:03:35.705894795+02:00[Europe/Madrid]" + } + } +} +```` + +3. Configure the external service `circuitBreakerEcho` operation to fail using the following command:\ +The external-service was designed to fail intentionally upon configuration. + +```` +curl -X 'POST' \ + 'http://localhost:8080/external-service/admin' \ + -H 'accept: */*' \ + -H 'Content-Type: application/json' \ + -d '{ + "operation": "circuitBreakerEcho", + "enabled": false +}' +```` + +4. Execute the workflow again with the following command: + +```` +curl -X 'POST' \ +'http://localhost:8080/call-echo' \ +-H 'accept: */*' \ +-H 'Content-Type: application/json' \ +-d '{ "echo" : "Hello!" }' +```` + +This time you will see an output with the HTTP 500 error code. This means that the workflow has executed the regular +call to the external service `circuitBreakerEcho` operation, and has got the error. The circuit is in the `Closed` status. +```` +{ + "errorCode": "500", + "failedNodeId": "6", + "id": "5e731491-8850-44de-a3c5-a68fd2817af6", + "message": "HTTP 500 Internal Server Error" +} +```` + +5. Repeat 3 or more executions, and this time, you will start to see the following result: + +```` +{ + "failedNodeId": "6", + "id": "f3f12ca3-2a1e-4267-9d82-a0ee3d9acd80", + "message": "org.eclipse.microprofile.faulttolerance.exceptions.CircuitBreakerOpenException - org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi#circuitBreakerEcho circuit breaker is open" +} +```` + +This means that circuit has transitioned to the `Open` status, and thus, no call to external service is produced. +Instead, the fault tolerance layer is producing the error. + +6. Configure the external service `circuitBreakerEcho` operation to go back to normal execution with the following command: + +```` +curl -X 'POST' \ + 'http://localhost:8080/external-service/admin' \ + -H 'accept: */*' \ + -H 'Content-Type: application/json' \ + -d '{ + "operation": "circuitBreakerEcho", + "enabled": true +}' +```` + +This time, the external service will not fail if executed, however, if you repeat the workflow execution during the next 2 minutes, +you will continue getting the org.eclipse.microprofile.faulttolerance.exceptions.CircuitBreakerOpenException, since +the circuit will continues in the `Open` status because of the following configuration: + +```` +# Wait 2 minute2 before an Open circuit goes to the Half Open state. Review Comment: typo ```suggestion # Wait 2 minutes before an Open circuit goes to the Half Open state. ``` ########## serverless-workflow-examples/serverless-workflow-fault-tolerance/Readme.md: ########## @@ -0,0 +1,235 @@ +# Kogito Serverless Workflow Fault Tolerance + +This example shows how to configure fault tolerance alternatives when you work with workflows. + +## Circuit Breaker Pattern + +Every REST call executed by a workflow can be configured to use the Circuit Breaker Pattern. + + + +The internals of the pattern configuration and execution are based on the [MicroProfile Fault Tolerance](https://github.com/eclipse/microprofile-fault-tolerance/) specification, +and the corresponding [Smallrye Fault Tolerance](https://github.com/smallrye/smallrye-fault-tolerance) implementation shipped with Quarkus. + +The following example shows how to configure the [call-echo](src/main/resources/call-echo.sw.yml) workflow to use the Circuit Breaker Pattern to execute the `circuitBreakerEcho` operation provided by the [external-service](src/main/resources/specs/external-service.yaml). + +### Build time configurations + + +To enable and configure the Circuit Breaker you must follow this procedure: + +1. Add the following maven dependency to your project: +```` +<dependency> + <groupId>io.quarkus</groupId> + <artifactId>quarkus-smallrye-fault-tolerance</artifactId> +</dependency> +```` + +2. Enable the Circuit Breaker + +When a workflow use REST calls, behind the scene, a set of classes are generated to support these invocations. +In general, the generation is transparent, and you don't need to pay attention on it. + +However, to enable the Circuit Breaker, you must provide some configurations that are related to that generation, and impacts the generated code. + +The first step is to find the generated Java class name that is registered as the Microprofile Rest Client to access the external service. + +The following picture shows how this class name is calculated at code generation time: + + + +We recommend that you build the project and inspect the generated sources under the directory `target/generated-sources/open-api-stream/org/kie/kogito/openapi`: + + + + +When the Circuit Breaker is not configured, the generated signature for the Java method corresponding to the `circuitBreakerEcho` operation will look like this: + +```` [email protected](name="", openApiSpecId="external_service_yaml", operationId="circuitBreakerEcho", method="POST", path="/external-service/circuit-breaker") [email protected] [email protected]("/circuit-breaker") [email protected]({"text/plain"}) [email protected]({"application/json"}) [email protected]("circuitBreakerEcho") +public EchoResponse circuitBreakerEcho( + String body +); +```` + +Given the class name `org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi`, and the method `circuitBreakerEcho`, +to enable the Circuit Breaker, you must add the following entry in the `application.properties`: + +```` +org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho/CircuitBreaker/enabled=true +```` + +> **NOTE:** Every operation must be configured individually, and different operations might be located in different classes. + +After adding the configuration, the next build will generate the following signature: + +```` [email protected](name="", openApiSpecId="external_service_yaml", operationId="circuitBreakerEcho", method="POST", path="/external-service/circuit-breaker") [email protected] [email protected]("/circuit-breaker") [email protected]({"text/plain"}) [email protected]({"application/json"}) [email protected]("circuitBreakerEcho") [email protected] +public EchoResponse circuitBreakerEcho( + String body +); +```` + +If the `@org.eclipse.microprofile.faulttolerance.CircuitBreaker` annotation is present in the generated method signature, +it means that the configuration was set correct. + +If you don't see the annotation, we recommend that you navigate and look into the generated sources to find the correct class name, or any potential typo in the property name, etc. + +3. Configure other behavioural properties: + +The build time behavioural properties are used to define configurations like thresholds and delays, for more information [see](https://quarkus.io/version/3.20/guides/smallrye-fault-tolerance#configuration-reference). + +To set these properties you must use the prefix `quarkus.fault-tolerance."org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho"`. Review Comment: You could generalize these expressions to make them more clear to understand, something like this: `quarkus.fault-tolerance."<ClassName>/<method>".<property>=<value>` ########## serverless-workflow-examples/serverless-workflow-fault-tolerance/src/test/java/org/kie/kogito/examples/CallEchoIT.java: ########## @@ -0,0 +1,76 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one + * or more contributor license agreements. See the NOTICE file + * distributed with this work for additional information + * regarding copyright ownership. The ASF licenses this file + * to you under the Apache License, Version 2.0 (the + * "License"); you may not use this file except in compliance + * with the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +package org.kie.kogito.examples; + +import io.quarkus.test.junit.QuarkusIntegrationTest; +import io.restassured.http.ContentType; +import io.restassured.path.json.JsonPath; +import io.restassured.response.ValidatableResponse; +import org.junit.jupiter.api.Test; + +import static io.restassured.RestAssured.given; +import static org.junit.jupiter.api.Assertions.assertTrue; + +@QuarkusIntegrationTest +class CallEchoIT { + + private static final String ACCESS_CIRCUIT_BREAKER_ECHO_ERROR = "HTTP 500 Internal Server Error"; + private static final String ACCESS_OPEN_CIRCUIT_ERROR = "org.eclipse.microprofile.faulttolerance.exceptions.CircuitBreakerOpenException"; + + @Test + void circuitBreakerEcho() { + // regular call, no failure. + prepareCircuitBreakerCall().statusCode(201); + + // program the circuitBreakerEcho operation to fail. + given() + .contentType(ContentType.JSON) + .accept(ContentType.JSON) + .body("{\"operation\" : \"circuitBreakerEcho\", \"enabled\" : false}").when() + .post("/external-service/admin") + .then() + .statusCode(200); + + // next 3 calls must fail with "HTTP 500 Internal Server Error" + assertCallEcoStartsWithMessage(ACCESS_CIRCUIT_BREAKER_ECHO_ERROR); + assertCallEcoStartsWithMessage(ACCESS_CIRCUIT_BREAKER_ECHO_ERROR); + assertCallEcoStartsWithMessage(ACCESS_CIRCUIT_BREAKER_ECHO_ERROR); + + // fourth call must fail due to the Open circuit. + assertCallEcoStartsWithMessage(ACCESS_OPEN_CIRCUIT_ERROR); + } + + private static void assertCallEcoStartsWithMessage(String prefix) { + JsonPath result = prepareCircuitBreakerCall() + .statusCode(500) + .extract() + .jsonPath(); + String message = result.get("message"); + assertTrue(message != null && message.startsWith(prefix)); Review Comment: You could add the cause of failure, but up to you: ```suggestion assertTrue(message != null && message.startsWith(prefix), "Expected message to start with: " + prefix + " but got: " + message); ``` ########## serverless-workflow-examples/serverless-workflow-fault-tolerance/Readme.md: ########## @@ -0,0 +1,235 @@ +# Kogito Serverless Workflow Fault Tolerance + +This example shows how to configure fault tolerance alternatives when you work with workflows. + +## Circuit Breaker Pattern + +Every REST call executed by a workflow can be configured to use the Circuit Breaker Pattern. + + + +The internals of the pattern configuration and execution are based on the [MicroProfile Fault Tolerance](https://github.com/eclipse/microprofile-fault-tolerance/) specification, +and the corresponding [Smallrye Fault Tolerance](https://github.com/smallrye/smallrye-fault-tolerance) implementation shipped with Quarkus. + +The following example shows how to configure the [call-echo](src/main/resources/call-echo.sw.yml) workflow to use the Circuit Breaker Pattern to execute the `circuitBreakerEcho` operation provided by the [external-service](src/main/resources/specs/external-service.yaml). + +### Build time configurations + + +To enable and configure the Circuit Breaker you must follow this procedure: + +1. Add the following maven dependency to your project: +```` +<dependency> + <groupId>io.quarkus</groupId> + <artifactId>quarkus-smallrye-fault-tolerance</artifactId> +</dependency> +```` + +2. Enable the Circuit Breaker + +When a workflow use REST calls, behind the scene, a set of classes are generated to support these invocations. +In general, the generation is transparent, and you don't need to pay attention on it. + +However, to enable the Circuit Breaker, you must provide some configurations that are related to that generation, and impacts the generated code. + +The first step is to find the generated Java class name that is registered as the Microprofile Rest Client to access the external service. + +The following picture shows how this class name is calculated at code generation time: + + + +We recommend that you build the project and inspect the generated sources under the directory `target/generated-sources/open-api-stream/org/kie/kogito/openapi`: + + + + +When the Circuit Breaker is not configured, the generated signature for the Java method corresponding to the `circuitBreakerEcho` operation will look like this: + +```` [email protected](name="", openApiSpecId="external_service_yaml", operationId="circuitBreakerEcho", method="POST", path="/external-service/circuit-breaker") [email protected] [email protected]("/circuit-breaker") [email protected]({"text/plain"}) [email protected]({"application/json"}) [email protected]("circuitBreakerEcho") +public EchoResponse circuitBreakerEcho( + String body +); +```` + +Given the class name `org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi`, and the method `circuitBreakerEcho`, +to enable the Circuit Breaker, you must add the following entry in the `application.properties`: + +```` +org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho/CircuitBreaker/enabled=true +```` + +> **NOTE:** Every operation must be configured individually, and different operations might be located in different classes. + +After adding the configuration, the next build will generate the following signature: + +```` [email protected](name="", openApiSpecId="external_service_yaml", operationId="circuitBreakerEcho", method="POST", path="/external-service/circuit-breaker") [email protected] [email protected]("/circuit-breaker") [email protected]({"text/plain"}) [email protected]({"application/json"}) [email protected]("circuitBreakerEcho") [email protected] +public EchoResponse circuitBreakerEcho( + String body +); +```` + +If the `@org.eclipse.microprofile.faulttolerance.CircuitBreaker` annotation is present in the generated method signature, +it means that the configuration was set correct. + +If you don't see the annotation, we recommend that you navigate and look into the generated sources to find the correct class name, or any potential typo in the property name, etc. + +3. Configure other behavioural properties: + +The build time behavioural properties are used to define configurations like thresholds and delays, for more information [see](https://quarkus.io/version/3.20/guides/smallrye-fault-tolerance#configuration-reference). + +To set these properties you must use the prefix `quarkus.fault-tolerance."org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho"`. + +Below is the configuration used for the example: + +```` +# Build time property to add the Circuit Breaker capability to the corresponding generated class/method, by annotating +# it with the eclipse microprofile @org.eclipse.microprofile.faulttolerance.CircuitBreaker. +# This property doesn't follow the quarkus.fault-tolerance.xxx prefix, you must use this format. +org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho/CircuitBreaker/enabled=true + +# Configuration values for the sake of current example. Produces a quick circuit Open, and a long delayed transitioning +# to the Half Closed state. Don't consider this as suggested configurations for a production system. + +# Use a rolling window of 4 consecutive requests +quarkus.fault-tolerance."org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho".circuit-breaker.request-volume-threshold=4 +# With a ratio of .5, if 2 requests fail, the circuit is Opened. +quarkus.fault-tolerance."org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho".circuit-breaker.failure-ratio=0.5 + +# Wait 2 minutes before the Open circuit goes to the Half Open state. +quarkus.fault-tolerance."org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho".circuit-breaker.delay=2 +quarkus.fault-tolerance."org.kie.kogito.openapi.externalservice.api.ExternalServiceResourceApi/circuitBreakerEcho".circuit-breaker.delay-unit=minutes +```` + +### Executing the example + +#### Prerequisites + +You will need: +- Java 17+ installed +- Environment variable JAVA_HOME set accordingly +- Maven 3.9.6+ installed + +##### Executing in Quarkus Dev mode + +To see the Circuit Breaker behaviour, we recommend that you follow this procedure: + +1. Start the workflow: + +```` +mvn quarkus:dev +```` + +2. Execute the workflow to verify a regular execution (without errors): + +```` +curl -X 'POST' \ +'http://localhost:8080/call-echo' \ +-H 'accept: */*' \ +-H 'Content-Type: application/json' \ +-d '{ "echo" : "Hello!" }' +```` + +You will see an output like this: + +```` +{ + "id": "2de57de7-38f7-4a33-bb7e-670bedefbcf1", + "workflowdata": { + "echo": "Hello!", + "echoResult": { + "id": "cf3405af-c903-4a7f-86cc-d2287d383d36", + "echo": "Hello!", + "createdAt": "2025-08-04T12:03:35.705894795+02:00[Europe/Madrid]" + } + } +} +```` + +3. Configure the external service `circuitBreakerEcho` operation to fail using the following command:\ +The external-service was designed to fail intentionally upon configuration. Review Comment: Nitpicking, you could emphasize that external service "exposes the circuitBreakerEcho operation, which was designed to fail..." ########## serverless-workflow-examples/serverless-workflow-fault-tolerance/pom.xml: ########## @@ -0,0 +1,181 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + + Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + +--> +<project xmlns="http://maven.apache.org/POM/4.0.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd";> + <modelVersion>4.0.0</modelVersion> + <parent> + <groupId>org.kie.kogito.examples</groupId> + <artifactId>serverless-workflow-examples-parent</artifactId> + <version>999-SNAPSHOT</version> + <relativePath>../serverless-workflow-examples-parent/pom.xml</relativePath> + </parent> + + <artifactId>serverless-workflow-fault-tolerance</artifactId> + <version>1.0.0-SNAPSHOT</version> + + <name>Kogito Example :: Serverless Workflow Fault Tolerance :: Quarkus</name> + <description>Kogito Serverless Workflow Fault Tolerance - Quarkus</description> + + <properties> + <compiler-plugin.version>3.14.0</compiler-plugin.version> + <maven.compiler.release>17</maven.compiler.release> + <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> + <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding> + <quarkus.platform.artifact-id>quarkus-bom</quarkus.platform.artifact-id> + <quarkus.platform.group-id>io.quarkus.platform</quarkus.platform.group-id> + <quarkus.platform.version>3.20.1</quarkus.platform.version> + <kogito.bom.group-id>org.kie.kogito</kogito.bom.group-id> + <kogito.bom.artifact-id>kogito-bom</kogito.bom.artifact-id> + <kogito.bom.version>999-SNAPSHOT</kogito.bom.version> + <skipITs>true</skipITs> + <surefire-plugin.version>3.5.2</surefire-plugin.version> + </properties> + + <dependencyManagement> + <dependencies> + <dependency> + <groupId>${quarkus.platform.group-id}</groupId> + <artifactId>${quarkus.platform.artifact-id}</artifactId> + <version>${quarkus.platform.version}</version> + <type>pom</type> + <scope>import</scope> + </dependency> + <dependency> + <groupId>${kogito.bom.group-id}</groupId> + <artifactId>${kogito.bom.artifact-id}</artifactId> + <version>${kogito.bom.version}</version> + <type>pom</type> + <scope>import</scope> + </dependency> + </dependencies> + </dependencyManagement> + + <dependencies> + <dependency> + <groupId>io.quarkus</groupId> + <artifactId>quarkus-arc</artifactId> + </dependency> + <dependency> + <groupId>io.quarkus</groupId> + <artifactId>quarkus-resteasy</artifactId> + </dependency> + <dependency> + <groupId>io.quarkus</groupId> + <artifactId>quarkus-resteasy-jackson</artifactId> + </dependency> + <dependency> + <groupId>io.quarkus</groupId> + <artifactId>quarkus-smallrye-openapi</artifactId> + </dependency> + <dependency> + <groupId>io.quarkus</groupId> + <artifactId>quarkus-smallrye-fault-tolerance</artifactId> + </dependency> + <dependency> + <groupId>org.apache.kie.sonataflow</groupId> + <artifactId>sonataflow-quarkus</artifactId> + </dependency> + <dependency> + <groupId>io.quarkus</groupId> + <artifactId>quarkus-junit5</artifactId> + <scope>test</scope> + </dependency> + <dependency> + <groupId>io.rest-assured</groupId> + <artifactId>rest-assured</artifactId> + <scope>test</scope> + </dependency> + </dependencies> + + <build> + <plugins> + <plugin> + <groupId>${quarkus.platform.group-id}</groupId> + <artifactId>quarkus-maven-plugin</artifactId> + <version>${quarkus.platform.version}</version> + <extensions>true</extensions> + <executions> + <execution> + <goals> + <goal>build</goal> + <goal>generate-code</goal> + <goal>generate-code-tests</goal> + <goal>native-image-agent</goal> + </goals> + </execution> + </executions> + </plugin> + <plugin> + <artifactId>maven-compiler-plugin</artifactId> + <version>${compiler-plugin.version}</version> + <configuration> + <parameters>true</parameters> Review Comment: It is not using` ${maven.compiler.release}` here, when it was defined as property (so, let's take advantage of it, adding it into _configuration_). ` <release>${maven.compiler.release}</release>` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
