consul

stable

Helper functions for building Consul HTTP API requests — path builders, JSON body generators, KV base64 encode/decode, and response parsers.

use plugin consul::{kv_path, kv_put_path, kv_delete_path, …}

17 functions Cloud

/ filter jk navigate Esc clear

Functions (17)

kv_path Build the KV read/write API path
kv_put_path Build the KV PUT API path
kv_delete_path Build the KV DELETE API path
service_register_path Build the service register API path
service_register_body Build service registration JSON body
service_deregister_path Build the service deregister API path
health_check_body Build a health check JSON body
health_check_register_body Build a check registration JSON body
health_service_path Build the health service query path
encode_kv_value Base64-encode a string for KV PUT
decode_kv_value Base64-decode a KV value string
catalog_service_path Build the catalog service query path
catalog_nodes_path Get the catalog nodes API path
catalog_services_path Get the catalog services API path
agent_self_path Get the agent self-info API path
agent_services_path Get the agent services API path
parse_kv_response Parse a Consul KV GET JSON response

Overview

The consul plugin is a stateless helper library for talking to the Consul HTTP API. It does not open any connections itself — instead it builds the API paths, JSON request bodies, and base64 KV encodings you feed into your own HTTP client, and parses the responses that come back. Every function is a pure transformation of its arguments, so it works the same in the VM, native, and WASM backends.

Reach for this plugin whenever you need to register a service, run a KV read/write/delete, query the catalog, or set up a health check against a Consul agent. Pair the path builders (kv_path, catalog_service_path, health_service_path, …) and body builders (service_register_body, health_check_body) with your HTTP library, and use encode_kv_value / decode_kv_value / parse_kv_response to move values across the base64 boundary that Consul's KV store imposes.

Common patterns

use plugin consul::{service_register_path, service_register_body, service_deregister_path}

let id = "my-api-1"
let body = service_register_body("my-api", id, "10.0.0.5", 8080, #{1: "http", 2: "v2"})

print("PUT {service_register_path()}")
print(body)

// later, on shutdown
print("PUT {service_deregister_path(id)}")

Write a KV value (base64-encoded) and read it back, decoding the response:

use plugin consul::{kv_put_path, encode_kv_value, kv_path, parse_kv_response}

let put = kv_put_path("myapp/env")
let payload = encode_kv_value("production")
print("PUT {put} body={payload}")

// after GET kv_path("myapp/env")
let raw = '[{"Key":"myapp/env","Value":"cHJvZHVjdGlvbg==","Flags":0,"Session":""}]'
let entry = parse_kv_response(raw)
print("{entry["key"]} = {entry["value"]}")

Discover only the healthy nodes of a service, with a check registered for it:

use plugin consul::{health_check_register_body, health_service_path}

let check = health_check_register_body(
  "api-check", "my-api-1", "http://10.0.0.5:8080/health", "15s"
)
print(check)

let healthy = health_service_path("my-api", true)
print("GET {healthy}")

kv_path(key) → string

Build the KV read/write API path

Returns the Consul v1 KV API path for reading a key, e.g. /v1/kv/myapp/config. Leading slashes in the key are stripped.

use plugin consul::{kv_path}

let path = kv_path("myapp/config")
print(path)

A leading slash on the key is stripped, so these produce the same path:

use plugin consul::{kv_path}

print(kv_path("/myapp/config"))
print(kv_path("myapp/config"))

kv_put_path(key) → string

Build the KV PUT API path

Returns the Consul v1 KV API path for writing a key. Identical to kv_path — both map to /v1/kv/{key} (use HTTP PUT to write).

use plugin consul::{kv_put_path}

let path = kv_put_path("myapp/feature-flag")
print(path)

kv_delete_path(key) → string

Build the KV DELETE API path

Returns the Consul v1 KV API path for deleting a key. Use this with an HTTP DELETE request.

use plugin consul::{kv_delete_path}

let path = kv_delete_path("myapp/old-key")
print(path)

service_register_path() → string

Build the service register API path

Returns the fixed path /v1/agent/service/register for registering services with the local agent.

use plugin consul::{service_register_path}

let path = service_register_path()
print(path)

service_register_body(name, id, address, port, tags) → string

Build service registration JSON body

Builds a JSON body for registering a service with the Consul agent. tags is an optional table of tag strings.

use plugin consul::{service_register_body, service_register_path}

let tags = #{1: "http", 2: "v2"}
let body = service_register_body("my-api", "my-api-1", "10.0.0.5", 8080, tags)
print(body)

The tags table is optional — omit it for an untagged service. The body is emitted as pretty-printed JSON ready to PUT to service_register_path():

use plugin consul::{service_register_body, service_register_path}

let body = service_register_body("worker", "worker-1", "10.0.0.9", 9000, #{})
print("PUT {service_register_path()}")
print(body)

service_deregister_path(id) → string

Build the service deregister API path

Returns the deregister API path /v1/agent/service/deregister/{id} for a service instance.

use plugin consul::{service_deregister_path}

let path = service_deregister_path("my-api-1")
print(path)

health_check_body(name, http_url, interval) → string

Build a health check JSON body

Builds a JSON health check body for an HTTP check. The check uses GET and runs at the given interval (e.g. "10s").

use plugin consul::{health_check_body}

let body = health_check_body("api-health", "http://10.0.0.5:8080/health", "10s")
print(body)

health_check_register_body(name, service_id, http_url, interval) → string

Build a check registration JSON body

Builds a JSON body for registering a health check tied to a specific service ID. Includes ServiceID for association.

use plugin consul::{health_check_register_body}

let body = health_check_register_body(
  "api-check", "my-api-1", "http://10.0.0.5:8080/health", "15s"
)
print(body)

health_service_path(service, passing_only) → string

Build the health service query path

Builds the health service query path. If passing_only is true, appends ?passing=true to return only healthy nodes.

use plugin consul::{health_service_path}

let all_path = health_service_path("my-api", false)
print(all_path)

let healthy_path = health_service_path("my-api", true)
print(healthy_path)

passing_only is optional and defaults to false, so a single argument returns the path for all instances regardless of health:

use plugin consul::{health_service_path}

print(health_service_path("redis"))

encode_kv_value(str) → string

Base64-encode a string for KV PUT

Base64-encodes a string so it can be used as a KV PUT request body. Consul stores all KV values as base64.

use plugin consul::{encode_kv_value}

let encoded = encode_kv_value("production")
print(encoded)

encode_kv_value and decode_kv_value are exact inverses, so a value round-trips unchanged:

use plugin consul::{encode_kv_value, decode_kv_value}

let original = "feature-x=on"
let restored = decode_kv_value(encode_kv_value(original))
print(restored)

decode_kv_value(b64) → string

Base64-decode a KV value string

Base64-decodes a KV value as returned by the Consul API. Use this to read the Value field from a KV GET response.

use plugin consul::{decode_kv_value}

let raw = "cHJvZHVjdGlvbg=="
let value = decode_kv_value(raw)
print(value)

catalog_service_path(service) → string

Build the catalog service query path

Returns the catalog service query path /v1/catalog/service/{service} for looking up all nodes providing a service.

use plugin consul::{catalog_service_path}

let path = catalog_service_path("redis")
print(path)

catalog_nodes_path() → string

Get the catalog nodes API path

Returns the fixed path /v1/catalog/nodes for listing all registered nodes in the catalog.

use plugin consul::{catalog_nodes_path}

let path = catalog_nodes_path()
print(path)

catalog_services_path() → string

Get the catalog services API path

Returns /v1/catalog/services for listing all registered services.

use plugin consul::{catalog_services_path}

let path = catalog_services_path()
print(path)

agent_self_path() → string

Get the agent self-info API path

Returns /v1/agent/self, the path for querying the local Consul agent info.

use plugin consul::{agent_self_path}

let path = agent_self_path()
print(path)

agent_services_path() → string

Get the agent services API path

Returns /v1/agent/services for listing all services registered with the local agent.

use plugin consul::{agent_services_path}

let path = agent_services_path()
print(path)

parse_kv_response(json_str) → table

Parse a Consul KV GET JSON response

Parses the JSON body from a Consul KV GET request. Automatically base64- decodes the Value field. Returns a table with key, value, flags, and session.

use plugin consul::{parse_kv_response}

let json = '[{"Key":"myapp/env","Value":"cHJvZHVjdGlvbg==","Flags":0,"Session":""}]'
let entry = parse_kv_response(json)
print("key: {entry["key"]}, value: {entry["value"]}")

The returned table also carries flags (an integer) and session (the lock-session string, empty when the key is unlocked):

use plugin consul::{parse_kv_response}

let json = '[{"Key":"locks/leader","Value":"bm9kZS1h","Flags":42,"Session":"abc-123"}]'
let entry = parse_kv_response(json)
print("flags={entry["flags"]} session={entry["session"]}")

View source code