:ci: https://github.com/smallrye/smallrye-stork/actions?query=workflow%3A%22SmallRye+Build%22 :sonar: https://sonarcloud.io/dashboard?id=smallrye_smallrye-stork

== SmallRye Stork

image:https://img.shields.io/maven-central/v/io.smallrye.stork/stork-api?color=green["Maven"] image:https://javadoc.io/badge2/io.smallrye.stork/stork-api/javadoc.svg[javadoc] image:https://img.shields.io/github/license/smallrye/smallrye-stork.svg["License", link="http://www.apache.org/licenses/LICENSE-2.0"] image:https://github.com/smallrye/smallrye-stork/workflows/SmallRye%20Build/badge.svg?branch=main[link={ci}] image:https://sonarcloud.io/api/project_badges/measure?project=smallrye_smallrye-stork&metric=alert_status["Quality Gate Status", link={sonar}]

SmallRye Stork, Stork, in short, is a Service Discovery and Client-Side Load Balancer framework.

=== Main features

• Extensible service discovery mechanisms
• Built-in support for Consul and Kubernetes
• Customizable client load-balancing strategy
• API and managed approaches
• Quarkus integration, but can be used in any environment
• Imperative and Reactive

=== Example

Let's imagine you use https://www.consul.io/[Consul]. Consul stores the list of service instances you have and lets you locate them.

Stork bridges your application and Consul and lets you retrieve the services stored in Consul and select the most appropriate one:

[source, java]

Stork.initialize(); // <1> Stork stork = Stork.getInstance(); // <2> Service service = stork.getService("my-service"); // <3> ServiceInstance instance = service.selectServiceInstance() // <4> .await().atMost(Duration.ofSeconds(1)); String url = "http://" + instance.getHost() + instance.getPort(); // <5>

1. Initializes Stork - you need to do that only once.
2. Gets the Stork instance.
3. Gets the Service object for my-service.
4. Retrieves the service instance for my-service. This performs a lookup in Consul and a selection using a load-balancer.
5. Builds your URL.

That example uses the programmatic API. When integrated into the framework, all these steps can be omitted, and you only need to configure the application:

[source, properties]

stork.my-service.service-discovery.type=consul # <1> stork.my-service.load-balancer.type=least-response-time # <2>

hello/mp-rest/url=stork://my-service/hello # <3>

1. Configures that the my-service service uses Consul as service discovery backend
2. Configures the load balancer for my-service
3. Uses the stork scheme and indicates which service is targeted. When accessed, it will select the service instance using Stork.

=== Contributing

Check the link:CONTRIBUTING.md[contribution guide] to get build and contribution instructions.

=== Sponsors

Stork is part of the https://smallrye.io[SmallRye project]. Red Hat sponsors the development of this project.