https://github.com/smallrye/smallrye-stork

SmallRye Stork is a service discovery and client side-load balancing framework.
https://github.com/smallrye/smallrye-stork

Last synced: 8 months ago
JSON representation

SmallRye Stork is a service discovery and client side-load balancing framework.

• Host: GitHub
• URL: https://github.com/smallrye/smallrye-stork
• Owner: smallrye
• License: apache-2.0
• Created: 2021-04-22T06:10:12.000Z (over 4 years ago)
• Default Branch: main
• Last Pushed: 2025-04-30T15:12:12.000Z (9 months ago)
• Last Synced: 2025-04-30T16:25:50.289Z (9 months ago)
• Language: Java
• Homepage: http://smallrye.io/smallrye-stork/
• Size: 8.37 MB
• Stars: 83
• Watchers: 6
• Forks: 26
• Open Issues: 14
• Metadata Files:
  • Readme: README.adoc
  • Changelog: CHANGELOG.md
  • Contributing: CONTRIBUTING.md
  • License: LICENSE

Awesome Lists containing this project

• awesome-java - SmallRye Stork

README

          
: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.