{"id":22377173,"url":"https://github.com/kiwiproject/consul-client","last_synced_at":"2026-03-08T02:17:29.537Z","repository":{"id":166177931,"uuid":"641643948","full_name":"kiwiproject/consul-client","owner":"kiwiproject","description":"A Consul Client for Java","archived":false,"fork":false,"pushed_at":"2026-03-05T03:36:55.000Z","size":1875,"stargazers_count":13,"open_issues_count":7,"forks_count":3,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-03-05T07:52:51.567Z","etag":null,"topics":["client","consul","java"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kiwiproject.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-05-16T21:42:24.000Z","updated_at":"2026-03-05T03:36:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"e6041bc1-056f-4630-8c24-945d327f197a","html_url":"https://github.com/kiwiproject/consul-client","commit_stats":null,"previous_names":[],"tags_count":132,"template":false,"template_full_name":null,"purl":"pkg:github/kiwiproject/consul-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiwiproject%2Fconsul-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiwiproject%2Fconsul-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiwiproject%2Fconsul-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiwiproject%2Fconsul-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kiwiproject","download_url":"https://codeload.github.com/kiwiproject/consul-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kiwiproject%2Fconsul-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30242406,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-08T00:58:18.660Z","status":"online","status_checked_at":"2026-03-08T02:00:06.215Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","consul","java"],"created_at":"2024-12-04T22:13:02.730Z","updated_at":"2026-03-08T02:17:29.509Z","avatar_url":"https://github.com/kiwiproject.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"Consul Client for Java\n======================\n\n[![build](https://github.com/kiwiproject/consul-client/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/kiwiproject/consul-client/actions/workflows/build.yml?query=branch%3Amain)\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=kiwiproject_consul-client\u0026metric=alert_status)](https://sonarcloud.io/summary/new_code?id=kiwiproject_consul-client)\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=kiwiproject_consul-client\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=kiwiproject_consul-client)\n[![CodeQL](https://github.com/kiwiproject/consul-client/actions/workflows/codeql.yml/badge.svg)](https://github.com/kiwiproject/consul-client/actions/workflows/codeql.yml)\n[![javadoc](https://javadoc.io/badge2/org.kiwiproject/consul-client/javadoc.svg)](https://javadoc.io/doc/org.kiwiproject/consul-client)\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Maven Central](https://img.shields.io/maven-central/v/org.kiwiproject/consul-client)](https://central.sonatype.com/artifact/org.kiwiproject/consul-client/)\n\n---\n\n🥝 _We have now transitioned consul-client from rickfast to kiwiproject. It is released to Maven Central. See the [releases](https://github.com/kiwiproject/consul-client/releases) for more information._ 🥝\n\n---\n\nIntroduction\n------------\n\nSimple client for the Consul HTTP API.  For more information about the Consul HTTP API, go [here](https://developer.hashicorp.com/consul/api-docs).\n\nBackground\n----------\nThis library was imported from [rickfast/consul-client](https://github.com/rickfast/consul-client), which is no longer\nbeing maintained per a [note](https://github.com/rickfast/consul-client#notes-from-the-maintainer) from the original\nmaintainer.\n\nSince we are still using this library in services which use Dropwizard and Consul, we decided to import the original\nrepository and continue maintaining it for our own use, and anyone else who might want to use it. We make no guarantees\nwhatsoever about how long we will maintain it, and also plan to make our own changes such as changing the base package\nname to `org.kiwiproject` to be consistent with our other libraries.\n\nAll other [kiwiproject](https://github.com/kiwiproject/) projects are MIT-licensed. However, because the original\n`consul-client` uses the Apache 2.0 license, we are keeping the Apache 2.0 license (otherwise to switch to MIT we\nwould have to gain consent of all contributors, which we do not want to do).\n\nAnother thing to note is that we _imported_ this repository from the original, so that it is a \"disconnected fork\". We\ndid not want a reference to the original repository since it is no longer maintained and no changes here will never\nbe pushed back upstream. Thus, while we maintain the history that this is a fork, it is completely disconnected and is\nnow a standalone (normal) repository.\n\nMigrating from rickfast/consul-client\n--------------------------------------------\nFor the initial version [0.5.0](https://github.com/kiwiproject/consul-client/releases/tag/v0.5.0), most likely\nthe only thing you need to change in your POM is the group ID and the version number.\nHowever, you should instead go directly to [0.6.0](https://github.com/kiwiproject/consul-client/releases/tag/v0.6.0),\nsince there was an issue in the initial release in which the compile time dependencies were not included in the\nPOM released to Maven Central. Other than the POM dependencies and a few minor documentation and minor changes in tests,\n0.5.0 and 0.6.0 are basically the same.\n\nIf you are using `PolicyResponse` and/or `PolicyListResponse`, then you will need to change your code,\nsince `datacenters` changed from `Optional\u003cString\u003e` to `Optional\u003cList\u003cString\u003e\u003e`,\nso code using either of those will no longer compile.\nThis change was not avoidable, since the original type was incorrect.\n\nStarting with version [0.7.0](https://github.com/kiwiproject/consul-client/releases/tag/v0.7.0), the base package\nchanges from `com.orbitz` to `org.kiwiproject`. The class\nnames are the same, so existing code only needs to change the base package and recompile.\n\n[0.8.0](https://github.com/kiwiproject/consul-client/releases/tag/v0.8.0) removes all deprecated methods\nfrom `AgentClient` and `KeyValueClient`.\nThe methods in `AgentClient` would have always failed anyway, since Consul no longer has the\nHTTP endpoints they were calling. Last, there is no direct replacement for the method removed from `KeyValueClient`.\n\nInstallation\n-----------\n\nUse the following to include `consul-client` as a dependency in your project.\n\n### Gradle:\n\n#### Groovy:\n\n```groovy\ndependencies {\n    implementation 'org.kiwiproject:consul-client:[version]'\n}\n```\n\n#### Kotlin:\n\n```kotlin\ndependencies {\n    implementation(\"org.kiwiproject:consul-client:[version]\")\n}\n```\n\n### Maven:\n\n```xml\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eorg.kiwiproject\u003c/groupId\u003e\n        \u003cartifactId\u003econsul-client\u003c/artifactId\u003e\n        \u003cversion\u003e[version]\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n### Shaded JAR\n\nA shaded JAR is also provided using the [Maven Shade Plugin](https://maven.apache.org/plugins/maven-shade-plugin/) to\ncreate an \"uber-jar\" that includes dependencies.\nTo use the shaded JAR, add a classifier, e.g. in Maven:\n\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eorg.kiwiproject\u003c/groupId\u003e\n    \u003cartifactId\u003econsul-client\u003c/artifactId\u003e\n    \u003cversion\u003e[version]\u003c/version\u003e\n    \u003cclassifier\u003eshaded\u003c/classifier\u003e\n\u003c/dependency\u003e\n```\n\nBasic Usage\n-----------\n\n### Example 1: Connect to Consul.\n\n```java\nConsul client = Consul.builder().build(); // connect on localhost to default port 8500\n```\n\n### Example 2: Register and check your service in with Consul.\n\n```java\nAgentClient agentClient = client.agentClient();\n\nString serviceId = \"1\";\nRegistration service = ImmutableRegistration.builder()\n        .id(serviceId)\n        .name(\"myService\")\n        .port(8080)\n        .check(Registration.RegCheck.ttl(3L)) // registers with a TTL of 3 seconds\n        .tags(List.of(\"tag1\"))\n        .meta(Map.of(\"version\", \"1.0\"))\n        .build();\n\nagentClient.register(service);\n\n// Check in with Consul (serviceId required only).\n// Client will prepend \"service:\" for service level checks.\n// Note that you need to continually check in before the TTL expires; otherwise your service's state will be marked as \"critical\".\nagentClient.pass(serviceId);\n```\n\n### Example 3: Find available (healthy) services.\n\n```java\nHealthClient healthClient = client.healthClient();\n\n// Discover only \"passing\" nodes\nList\u003cServiceHealth\u003e nodes = healthClient.getHealthyServiceInstances(\"DataService\").getResponse();\n```\n\n### Example 4: Store key/values.\n\n```java\nKeyValueClient kvClient = client.keyValueClient();\n\nkvClient.putValue(\"foo\",\"bar\");\n        String value=kvClient.getValueAsString(\"foo\").orElseThrow(); // bar\n```\n\n### Example 5: Subscribe to value change.\n\nYou can use the ConsulCache implementations to easily subscribe to Key-Value changes.\n\n```java\nfinal KeyValueClient kvClient = client.keyValueClient();\n\nkvClient.putValue(\"foo\", \"bar\");\n\nKVCache cache = KVCache.newCache(kvClient, \"foo\");\ncache.addListener(newValues -\u003e {\n    // Cache notifies all paths with \"foo\" the root path\n    // If you want to watch only \"foo\" value, you must filter other paths\n    Optional\u003cValue\u003e newValue = newValues.values().stream()\n            .filter(value -\u003e value.getKey().equals(\"foo\"))\n            .findAny();\n\n    newValue.ifPresent(value -\u003e {\n        // Values are encoded in key/value store, decode it if needed\n        Optional\u003cString\u003e decodedValue=newValue.get().getValueAsString();\n        decodedValue.ifPresent(v-\u003eSystem.out.printf(\"Value is: %s%n\",v)); //prints \"bar\"\n        });\n});\ncache.start();\n// ...\ncache.stop();\n```\n\n### Example 6: Subscribe to healthy services\n\nYou can also use the ConsulCache implementations to easily subscribe to healthy service changes.\n\n```java\nHealthClient healthClient = client.healthClient();\nString serviceName = \"my-service\";\n\nServiceHealthCache svHealth = ServiceHealthCache.newCache(healthClient, serviceName);\nsvHealth.addListener((Map\u003cServiceHealthKey, ServiceHealth\u003e newValues) -\u003e {\n    // do something with updated server map\n});\nsvHealth.start();\n// ...\nsvHealth.stop();\n```\n\n### Example 7: Find Raft peers.\n\n```java\nStatusClient statusClient = client.statusClient();\nstatusClient.getPeers().forEach(System.out::println);\n```\n\n### Example 8: Find Raft leader.\n\n```java\nStatusClient statusClient = client.statusClient();\nSystem.out.println(statusClient.getLeader()); // 127.0.0.1:8300\n```\n\nDevelopment Notes\n-----------\n\n`consul-client` makes use of [Immutables](https://immutables.github.io/) to generate code for many of the value classes.\nThis provides a lot of functionality and benefit for little code, but it does require some additional development setup.\n\nOfficial instructions are [here](https://immutables.github.io/apt.html), although you may want to change the target\ndirectories to the more gradle-like \"generated/source/apt/main\" and \"generated/source/apt/test\" targets.\n\n### Integration Tests\n\nRuns consul with [Testcontainers](https://www.testcontainers.org/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiwiproject%2Fconsul-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkiwiproject%2Fconsul-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkiwiproject%2Fconsul-client/lists"}