rest-fights

Superheroes Fight Microservice

Table of Contents

• Introduction
• Configuration
• Resiliency
  • Timeouts
  • Fallbacks
  • Retries
    • Hero Client
    • Villain Client
• Testing
• Running the Application
• Running Locally via Docker Compose
  • Only Fights Service
  • Fights Service and all Downstream Dependencies
  • Only Downstream Dependencies
• Deploying to Kubernetes
  • Using pre-built images
  • Deploying directly via Kubernetes Extensions

Introduction

This is the Fight REST API microservice. It is a reactive HTTP microservice exposing an API for performing fights between Heroes and Villains. Each fight is persisted into a PostgreSQL database and can be retrieved via the REST API. This service is implemented using RESTEasy Reactive with reactive endpoints and Quarkus Hibernate Reactive with Panache's active record pattern.

The following table lists the available REST endpoints. The OpenAPI document for the REST endpoints is also available.

Path	HTTP method	Response Status	Response Object	Description
/api/fights	GET	200	List<Fight>	All Fights. Empty array ([]) if none.
/api/fights	POST	200	Fight	Performs a fight.
/api/fights	POST	400		Invalid Fighters passed in request body (or no request body found)
/api/fights/randomfighters	GET	200	Fighters	Finds random fighters
/api/fights/{id}	GET	200	Fight	Fight with id == {id}
/api/fights/{id}	GET	404		No Fight with id == {id} found
/api/fights/hello	GET	200	String	Ping "hello" endpoint

Configuration

The FightConfig stores all the application-specific configuration that can be overridden at runtime.

Resiliency

Timeouts

The FightService class uses timeouts from SmallRye Fault Tolerance to protect against calls to the downstream Hero and Villain services. Tests for these conditions can be found in FightServiceTests.

Fallbacks

The FightService class uses fallbacks from SmallRye Fault Tolerance to protect against calls to the downstream Hero and Villain services. Tests for these conditions can be found in FightServiceTests.

Retries

Retry logic to the downstream Hero and Villain services is implemented in the clients for each service.

Hero Client

The HeroRestClient is implemented using the reactive rest client. All of its configuration can be found in application.properties under the quarkus.rest-client.hero-client key. This client is not exposed outside of the io.quarkus.sample.superheroes.fight.client package.

Instead, the HeroClient class wraps the HeroRestClient and adds some resiliency to it:

• The downstream Hero service returns a 404 if no random Hero is found. HeroClient handles this case and simulates the service returning nothing.
• In the event the downstream Hero service returns an error, HeroClient adds 3 retries with a 200ms delay between each retry.

Villain Client

The VillainClient is implemented using the JAX-RS client API with the RESTEasy Reactive client. All of its configuration can be found in application.properties under the fight.villain.client-base-url key.

• The downstream Villain service returns a 404 if no random Villain is found. VillainClient handles this case and simulates the service returning nothing.
• In the event the downstream Villain service returns an error, VillainClient adds 3 retries with a 200ms delay between each retry.

Testing

This application has a full suite of tests, including an integration test suite.

• The test suite uses Wiremock for mocking http calls (see HeroesVillainsWiremockServerResource) to the downstream Hero and Villain services.
• The test suite configures the application to use the in-memory connector from SmallRye Reactive Messaging (see the %test.mp.messaging.outgoing.fights configuration in application.properties) for verifying interactions with Kafka.
• The integration test suite uses Quarkus Dev Services (see KafkaConsumerResource) to interact with a Kafka instance so messages placed onto the Kafka broker by the application can be verified.

Running the Application

First you need to start up all of the downstream services (Heroes Service and Villains Service - the Event Statistics Service is optional).

The application runs on port 8082 (defined by quarkus.http.port in application.properties).

From the quarkus-super-heroes/rest-fights directory, simply run ./mvnw quarkus:dev to run Quarkus Dev Mode, or running quarkus dev using the Quarkus CLI. The application will be exposed at http://localhost:8082 and the Quarkus Dev UI will be exposed at http://localhost:8082/q/dev.

NOTE: Running the application outside of Quarkus Dev Mode requires standing up a PostgreSQL instance and an Apache Kafka instance and binding them to the app.

Furthermore, since this service also communicates with additional downstream services (rest-heroes and rest-villains), those would need to be stood up as well, although this service does have fallbacks in case those other services aren't available.

By default, the application is configured with the following:

Description	Environment Variable	Java Property	Value
Database URL	QUARKUS_DATASOURCE_REACTIVE_URL	quarkus.datasource.reactive.url	postgresql://localhost:5432/fights_database
Database username	QUARKUS_DATASOURCE_USERNAME	quarkus.datasource.username	superfight
Database password	QUARKUS_DATASOURCE_PASSWORD	quarkus.datasource.password	superfight
Kafka Bootstrap servers	KAFKA_BOOTSTRAP_SERVERS	kafka.bootstrap.servers	PLAINTEXT://localhost:9092
Heroes Service URL	quarkus.rest-client.hero-client.url	quarkus.rest-client.hero-client.url	http://localhost:8083
Villains Service URL	fight.villain.client-base-url	fight.villain.client-base-url	http://localhost:8084

Running Locally via Docker Compose

Pre-built images for this application can be found at quay.io/quarkus-super-heroes/rest-fights.

Only Fights Service

Pick one of the 4 versions of the application from the table below and execute the appropriate docker compose command from the quarkus-super-heroes/rest-fights directory.

NOTE: You may see errors as the applications start up. This may happen if an application completes startup before one if its required services (i.e. database, kafka, etc). This is fine. Once everything completes startup things will work fine.

Description	Image Tag	Docker Compose Run Command
JVM Java 11	java11-latest	docker-compose -f deploy/docker-compose/java11.yml up --remove-orphans
JVM Java 17	java17-latest	docker-compose -f deploy/docker-compose/java17.yml up --remove-orphans
Native compiled with Java 11	native-java11-latest	docker-compose -f deploy/docker-compose/native-java11.yml up --remove-orphans
Native compiled with Java 17	native-java17-latest	docker-compose -f deploy/docker-compose/native-java17.yml up --remove-orphans

Fights Service and all Downstream Dependencies

The above Docker Compose files are meant for standing up this application and the required database and Kafka broker only. If you want to stand up this application and its downstream services (rest-villains and rest-heroes), pick one of the 4 versions from the table below and execute the appropriate docker compose command from the quarkus-super-heroes/rest-fights directory.

NOTE: You may see errors as the applications start up. This may happen if an application completes startup before one if its required services (i.e. database, kafka, etc). This is fine. Once everything completes startup things will work fine.

Description	Image Tag	Docker Compose Run Command
JVM Java 11	java11-latest	docker-compose -f deploy/docker-compose/java11-all-downstream.yml up --remove-orphans
JVM Java 17	java17-latest	docker-compose -f deploy/docker-compose/java17-all-downstream.yml up --remove-orphans
Native compiled with Java 11	native-java11-latest	docker-compose -f deploy/docker-compose/native-java11-all-downstream.yml up --remove-orphans
Native compiled with Java 17	native-java17-latest	docker-compose -f deploy/docker-compose/native-java17-all-downstream.yml up --remove-orphans

Only Downstream Dependencies

If you want to develop the Fights service (i.e. via Quarkus Dev Mode) but want to stand up just it's downstream services (rest-villains and rest-heroes), pick one of the 4 versions from the table below and execute the appropriate docker compose command from the quarkus-super-heroes directory.

NOTE: You may see errors as the applications start up. This may happen if an application completes startup before one if its required services (i.e. database, kafka, etc). This is fine. Once everything completes startup things will work fine.

Description	Image Tag	Docker Compose Run Command
JVM Java 11	java11-latest	docker-compose -f rest-heroes/deploy/docker-compose/java11.yml -f rest-villains/deploy/docker-compose/java11.yml up --remove-orphans
JVM Java 17	java17-latest	docker-compose -f rest-heroes/deploy/docker-compose/java17.yml -f rest-villains/deploy/docker-compose/java17.yml up --remove-orphans
Native compiled with Java 11	native-java11-latest	docker-compose -f rest-heroes/deploy/docker-compose/native-java11.yml -f rest-villains/deploy/docker-compose/native-java11.yml up --remove-orphans
Native compiled with Java 17	native-java17-latest	docker-compose -f rest-heroes/deploy/docker-compose/native-java17.yml -f rest-villains/deploy/docker-compose/native-java17.yml up --remove-orphans

If you want to stand up the entire system, follow these instructions.

Once started the application will be exposed at http://localhost:8082.

Deploying to Kubernetes

The application can be deployed to Kubernetes using pre-built images or by deploying directly via the Quarkus Kubernetes Extension. Each of these is discussed below.

Using pre-built images

Pre-built images for this application can be found at quay.io/quarkus-super-heroes/rest-fights.

Deployment descriptors for these images are provided in the deploy/k8s directory. There are versions for OpenShift, Minikube, Kubernetes, and KNative.

Pick one of the 4 versions of the application from the table below and deploy the appropriate descriptor from the deploy/k8s directory.

Description	Image Tag	OpenShift Descriptor	Minikube Descriptor	Kubernetes Descriptor	KNative Descriptor
JVM Java 11	java11-latest	java11-openshift.yml	java11-minikube.yml	java11-kubernetes.yml	java11-knative.yml
JVM Java 17	java17-latest	java17-openshift.yml	java17-minikube.yml	java17-kubernetes.yml	java17-knative.yml
Native compiled with Java 11	native-java11-latest	native-java11-openshift.yml	native-java11-minikube.yml	native-java11-kubernetes.yml	native-java11-knative.yml
Native compiled with Java 17	native-java17-latest	native-java17-openshift.yml	native-java17-minikube.yml	native-java17-kubernetes.yml	native-java17-knative.yml

The application is exposed outside of the cluster on port 80.

These are only the descriptors for this application and the required database and Kafka broker only. If you want to deploy this application and its downstream services (rest-villains and rest-heroes), pick one of the 4 versions of the application from the table below and deploy the appropriate descriptor from the rest-fights/deploy/k8s directory.

Description	Image Tag	OpenShift Descriptor	Minikube Descriptor	Kubernetes Descriptor	KNative Descriptor
JVM Java 11	java11-latest	java11-openshift-all-downstream.yml	java11-minikube-all-downstream.yml	java11-kubernetes-all-downstream.yml	java11-knative-all-downstream.yml
JVM Java 17	java17-latest	java17-openshift-all-downstream.yml	java17-minikube-all-downstream.yml	java17-kubernetes-all-downstream.yml	java17-knative-all-downstream.yml
Native compiled with Java 11	native-java11-latest	native-java11-openshift-all-downstream.yml	native-java11-minikube-all-downstream.yml	native-java11-kubernetes-all-downstream.yml	native-java11-knative-all-downstream.yml
Native compiled with Java 17	native-java17-latest	native-java17-openshift-all-downstream.yml	native-java17-minikube-all-downstream.yml	native-java17-kubernetes-all-downstream.yml	native-java17-knative-all-downstream.yml

Each application is exposed outside of the cluster on port 80.

If you want to deploy the entire system, follow these instructions.

Deploying directly via Kubernetes Extensions

Following the deployment section of the Quarkus Kubernetes Extension Guide (or the deployment section of the Quarkus OpenShift Extension Guide if deploying to OpenShift), you can run ./mvnw clean package -Dquarkus.kubernetes.deploy=true to deploy the application and any of its dependencies (see Kubernetes (and variants) resource generation of the automation strategy document) to Kubernetes or OpenShift.

You may need to adjust some of the other configuration options as well (see Quarkus Kubernetes Extension configuration options and Quarkus OpenShift Extension configuration options). The do_build function in the generate-k8s-resources.sh script uses these extensions to generate the manifests in the deploy/k8s directory.