////
This guide is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/main/docs/src/main/asciidoc
////
= Getting Started with SmallRye Stork
:extension-status: preview

// Temporary until stork in in the BOM
:stork-version: 1.0.0.Beta1
include::./attributes.adoc[]

The essence of distributed systems resides in the interaction between services.
In modern architecture, you often have multiple instances of your service to share the load or improve the resilience by redundancy.
But how do you select the best instance of your service?
That's where https://smallrye.io/smallrye-stork[SmallRye Stork] helps.
Stork is going to choose the most appropriate instance.
It offers:

* Extensible service discovery mechanisms
* Built-in support for Consul and Kubernetes
* Customizable client load-balancing strategies

include::./status-include.adoc[]

== Prerequisites

:prerequisites-docker:
include::includes/devtools/prerequisites.adoc[]

== Architecture

In this guide, we will build an application composed of:

* A simple blue service exposed on port 9000
* A simple red service exposed on port 9001
* A REST Client calling the blue or red service (the selection is delegated to Stork)
* A REST endpoint using the REST client and calling the services
* The blue and red services are registered in https://www.consul.io/[Consul].

image::stork-getting-started-architecture.png[Architecture of the application,width=50%, align=center]

For the sake of simplicity, everything (except Consul) will be running in the same Quarkus application.
Of course, each component will run in its own process in the real world.

== Solution

We recommend that you follow the instructions in the next sections and create the applications step by step.
However, you can go right to the completed example.

Clone the Git repository: `git clone {quickstarts-clone-url}`, or download an {quickstarts-archive-url}[archive].

The solution is located in the `stork-quickstart` {quickstarts-tree-url}/stork-quickstart[directory].

== Discovery and selection

Before going further, we need to discuss discovery vs. selection.

- Service discovery is the process of locating service instances.
It produces a list of service instances that is potentially empty (if no service matches the request) or contains multiple service instances.

- Service selection, also called load-balancing, chooses the best instance from the list returned by the discovery process.
The result is a single service instance or an exception when no suitable instance can be found.

Stork handles both discovery and selection.
However, it does not handle the communication with the service but only provides a service instance.
The various integrations in Quarkus extract the location of the service from that service instance.

image::stork-process.png[Discovery and Selection of services,width=50%, align=center]

== Bootstrapping the project

Create a Quarkus project importing the quarkus-rest-client-reactive and quarkus-resteasy-reactive extensions using your favorite approach:

:create-app-artifact-id: stork-quickstart
:create-app-extensions: quarkus-rest-client-reactive,quarkus-resteasy-reactive
include::includes/devtools/create-app.adoc[]

In the generated project, also add the following dependencies:

[source,xml,role="primary asciidoc-tabs-target-sync-cli asciidoc-tabs-target-sync-maven"]
.pom.xml
----
<dependency>
  <groupId>io.smallrye.stork</groupId>
  <artifactId>stork-service-discovery-consul</artifactId>
</dependency>
<dependency>
  <groupId>io.smallrye.reactive</groupId>
  <artifactId>smallrye-mutiny-vertx-consul-client</artifactId>
</dependency>
----

[source,gradle,role="secondary asciidoc-tabs-target-sync-gradle"]
.build.gradle
----
implementation("io.smallrye.stork:stork-service-discovery-consul")
implementation("io.smallrye.reactive:smallrye-mutiny-vertx-consul-client")
----

`stork-service-discovery-consul` provides an implementation of service discovery for Consul.
`smallrye-mutiny-vertx-consul-client` is a Consul client which we will use to register our services in Consul.

== The Blue and Red services

Let's start with the very beginning: the service we will discover, select and call.

Create the `src/main/java/org/acme/services/BlueService.java` with the following content:

[source, java]
----
package org.acme.services;

import io.quarkus.runtime.StartupEvent;
import io.vertx.mutiny.core.Vertx;
import org.eclipse.microprofile.config.inject.ConfigProperty;

import javax.enterprise.context.ApplicationScoped;
import javax.enterprise.event.Observes;

@ApplicationScoped
public class BlueService {

    @ConfigProperty(name = "blue-service-port", defaultValue = "9000") int port;

    /**
     * Start an HTTP server for the blue service.
     *
     * Note: this method is called on a worker thread, and so it is allowed to block.
     */
    public void init(@Observes StartupEvent ev, Vertx vertx) {
        vertx.createHttpServer()
                .requestHandler(req -> req.response().endAndForget("Hello from Blue!"))
                .listenAndAwait(port);
    }
}
----

It creates a new HTTP server (using Vert.x) and implements our simple service when the application starts.
For each HTTP request, it sends a response with "Hello from Blue!" as the body.

Following the same logic, create the `src/main/java/org/acme/services/RedService.java` with the following content:

[source, java]
----

package org.acme.services;

import io.quarkus.runtime.StartupEvent;
import io.vertx.mutiny.core.Vertx;
import org.eclipse.microprofile.config.inject.ConfigProperty;

import javax.enterprise.context.ApplicationScoped;
import javax.enterprise.event.Observes;

@ApplicationScoped
public class RedService {
    @ConfigProperty(name = "red-service-port", defaultValue = "9001") int port;

    /**
     * Start an HTTP server for the red service.
     *
     * Note: this method is called on a worker thread, and so it is allowed to block.
     */
    public void init(@Observes StartupEvent ev, Vertx vertx) {
        vertx.createHttpServer()
                .requestHandler(req -> req.response().endAndForget("Hello from Red!"))
                .listenAndAwait(port);
    }

}
----

This time, it writes "Hello from Red!".

== Service registration in Consul

Now that we have implemented our services, we need to register them into Consul.

NOTE: Stork is not limited to Consul and integrates with other service discovery mechanisms.

Create the `src/main/java/org/acme/services/Registration.java` file with the following content:

[source, java]
----
package org.acme.services;

import io.quarkus.runtime.StartupEvent;
import io.vertx.ext.consul.ServiceOptions;
import io.vertx.mutiny.ext.consul.ConsulClient;
import io.vertx.ext.consul.ConsulClientOptions;
import io.vertx.mutiny.core.Vertx;
import org.eclipse.microprofile.config.inject.ConfigProperty;

import javax.enterprise.context.ApplicationScoped;
import javax.enterprise.event.Observes;

@ApplicationScoped
public class Registration {

    @ConfigProperty(name = "consul.host") String host;
    @ConfigProperty(name = "consul.port") int port;

    @ConfigProperty(name = "blue-service-port", defaultValue = "9000") int red;
    @ConfigProperty(name = "red-service-port", defaultValue = "9001") int blue;

    /**
     * Register our two services in Consul.
     *
     * Note: this method is called on a worker thread, and so it is allowed to block.
     */
    public void init(@Observes StartupEvent ev, Vertx vertx) {
        ConsulClient client = ConsulClient.create(vertx, new ConsulClientOptions().setHost(host).setPort(port));

        client.registerServiceAndAwait(
                new ServiceOptions().setPort(blue).setAddress("localhost").setName("my-service").setId("blue"));
        client.registerServiceAndAwait(
                new ServiceOptions().setPort(red).setAddress("localhost").setName("my-service").setId("red"));

    }
}
----

When the application starts, it connects to Consul using the Vert.x Consul Client and registers our two instances.
Both registration uses the same name (`my-service`), but different ids to indicate that it's two instances of the same _service_.

== The REST Client interface and the front end API

So far, we didn't use Stork; we just scaffolded the services we will be discovering, selecting, and calling.

We will call the services using the Reactive REST Client.
Create the `src/main/java/org/acme/MyService.java` file with the following content:

[source, java]
----
package org.acme;

import org.eclipse.microprofile.rest.client.inject.RegisterRestClient;

import javax.ws.rs.GET;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

/**
 * The REST Client interface.
 *
 * Notice the `baseUri`. It uses `stork://` as URL scheme indicating that the called service uses Stork to locate and
 * select the service instance. The `my-service` part is the service name. This is used to configure Stork discovery
 * and selection in the `application.properties` file.
 */
@RegisterRestClient(baseUri = "stork://my-service")
public interface MyService {

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    String get();
}
----

It's a straightforward REST client interface containing a single method. However, note the `baseUri` attribute.
It starts with `stork://`.
It instructs the REST client to delegate the discovery and selection of the service instances to Stork.
Notice the `my-service` part in the URL.
It is the service name we will be using in the application configuration.

It does not change how the REST client is used.
Create the `src/main/java/org/acme/FrontendApi.java` file with the following content:

[source, java]
----
package org.acme;

import org.eclipse.microprofile.rest.client.inject.RestClient;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

/**
 * A frontend API using our REST Client (which uses Stork to locate and select the service instance on each call).
 */
@Path("/api")
public class FrontendApi {

    @RestClient MyService service;

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String invoke() {
        return service.get();
    }

}
----

It injects and uses the REST client as usual.

== Stork configuration

The system is almost complete. We only need to configure Stork and the `Registration` bean.

In the `src/main/resources/application.properties`, add:

[source, properties]
----
consul.host=localhost
consul.port=8500

stork.my-service.service-discovery=consul
stork.my-service.service-discovery.consul-host=localhost
stork.my-service.service-discovery.consul-port=8500
stork.my-service.load-balancer=round-robin
----

The first two lines provide the Consul location used by the `Registration` bean.

The other properties are related to Stork.
`stork.my-service.service-discovery` indicates which type of service discovery we will be using to locate the `my-service` service.
In our case, it's `consul`.
`stork.my-service.service-discovery.consul-host` and `stork.my-service.service-discovery.consul-port` configures the access to Consul.
Finally, `stork.my-service.load-balancer` configures the service selection.
In our case, we use a `round-robin`.

== Running the application

We're done!
So, let's see if it works.

First, start Consul:

[source, shell script]
----
docker run --rm --name consul -p 8500:8500 -p 8501:8501 consul:1.7 agent -dev -ui -client=0.0.0.0 -bind=0.0.0.0 --https-port=8501
----

If you start Consul differently, do not forget to edit the application configuration.

Then, package the application:

include::includes/devtools/build.adoc[]

And run it:

[source, shell script]
----
> java -jar target/quarkus-app/quarkus-run.jar
----

In another terminal, run:

[source, shell script]
----
> curl http://localhost:8080/api
...
> curl http://localhost:8080/api
...
> curl http://localhost:8080/api
...
----

The responses alternate between `Hello from Red!` and `Hello from Blue!`.

You can compile this application into a native executable:

include::includes/devtools/build-native.adoc[]

And start it with:

[source, shell script]
----
> ./target/stork-getting-started-1.0.0-SNAPSHOT-runner
----

== Going further

This guide has shown how to use SmallRye Stork to discover and select your services.
You can find more about Stork in:

- the xref:stork-reference.adoc[Stork reference guide],
- the https://smallrye.io/smallrye-stork[SmallRye Stork website].
