Etcd API

Etcd v3 KV helpers are available under ptool.etcd and p.etcd.

ptool.etcd.connect

v0.11.0 - Introduced.

ptool.etcd.connect(options) opens an etcd connection and returns a Connection object.

options fields:

• address (string, required): The etcd HTTP address such as http://127.0.0.1:2379 or 127.0.0.1:2379.
• token (string, optional): Authorization header value sent with requests.
• username (string, optional): etcd auth username.
• password (string, optional): etcd auth password.
• api_prefix (string, optional): API prefix appended under address. Defaults to "v3", which targets the standard v3 gRPC-gateway endpoints.
• timeout_ms (integer, optional): Default request timeout in milliseconds.

Notes:

• token cannot be combined with username or password.
• username and password must be provided together.
• When username and password are used, ptool.etcd.connect(...) authenticates through auth/authenticate and stores the returned token on the connection.

Example:

local etcd = ptool.etcd.connect({
  address = "127.0.0.1:2379",
  username = "root",
  password = p.os.getenv("ETCD_PASSWORD"),
  timeout_ms = 10_000,
})

Connection

v0.11.0 - Introduced.

Connection represents an open etcd connection returned by ptool.etcd.connect().

It is implemented as a Lua userdata.

Methods:

• conn:get(key[, options]) -> table | nil
• conn:put(key, value[, options]) -> table
• conn:delete(key[, options]) -> table
• conn:list([prefix[, options]]) -> table
• conn:request(options) -> Response

KV entry table shape:

• key (string): The decoded raw key bytes as a Lua string.
• value (string): The decoded raw value bytes as a Lua string.
• create_revision (integer): The key creation revision.
• mod_revision (integer): The last modification revision.
• version (integer): The number of times the key has been modified.
• lease (integer): The attached lease ID, or 0 when no lease is attached.

Response header table shape:

• cluster_id (string): The etcd cluster ID rendered as a decimal string.
• member_id (string): The responding member ID rendered as a decimal string.
• revision (integer): The store revision for the response.
• raft_term (string): The raft term rendered as a decimal string.

get

v0.11.0 - Introduced.

Canonical API name: ptool.etcd.Connection:get.

conn:get(key[, options]) reads a single etcd KV entry.

• key (string, required): The raw key bytes.
• options (table, optional):
  • revision (integer, optional): Reads the key at a specific revision.
  • serializable (boolean, optional): Uses serializable reads instead of linearizable reads.
• Returns: table | nil.

Behavior:

• Returns nil when the key does not exist.
• key and value are binary-safe Lua strings.

Example:

local etcd = ptool.etcd.connect({ address = "127.0.0.1:2379" })
local item = etcd:get("/apps/api/config.json")

if item then
  local config = p.json.parse(item.value)
  print(item.mod_revision, config.port)
end

put

v0.11.0 - Introduced.

Canonical API name: ptool.etcd.Connection:put.

conn:put(key, value[, options]) writes an etcd KV entry.

• key (string, required): The raw key bytes.
• value (string, required): The raw value bytes.
• options (table, optional):
  • lease (integer, optional): Lease ID to attach to the key.
  • prev_kv (boolean, optional): When true, include the previous KV entry.
  • ignore_value (boolean, optional): Reuse the current value.
  • ignore_lease (boolean, optional): Reuse the current lease.
• Returns: table.

Return table shape:

• header (table | nil): Response header metadata.
• prev_kv (table | nil): Previous KV entry when prev_kv = true and a previous key existed.

Example:

local etcd = ptool.etcd.connect({ address = "127.0.0.1:2379" })
local resp = etcd:put("/apps/api/version", "v2\n", {
  prev_kv = true,
})

if resp.prev_kv then
  print(resp.prev_kv.value)
end

delete

v0.11.0 - Introduced.

Canonical API name: ptool.etcd.Connection:delete.

conn:delete(key[, options]) deletes one key or a whole key prefix.

• key (string, required): The raw key bytes. When prefix = true, an empty string deletes the full keyspace.
• options (table, optional):
  • prefix (boolean, optional): When true, delete the full prefix range.
  • prev_kv (boolean, optional): When true, include deleted KV entries.
• Returns: table.

Return table shape:

• header (table | nil): Response header metadata.
• deleted (integer): Number of deleted keys.
• prev_kvs (table): Dense Lua array of deleted KV entries.

list

v0.11.0 - Introduced.

Canonical API name: ptool.etcd.Connection:list.

conn:list([prefix[, options]]) lists etcd KV entries under a prefix.

• prefix (string, optional): The prefix to list. When omitted or empty, the whole keyspace is scanned.
• options (table, optional):
  • limit (integer, optional): Maximum number of returned entries.
  • revision (integer, optional): Reads at a specific revision.
  • serializable (boolean, optional): Uses serializable reads.
  • keys_only (boolean, optional): Return keys without values.
  • count_only (boolean, optional): Return only the count.
  • min_mod_revision (integer, optional): Minimum modification revision.
  • max_mod_revision (integer, optional): Maximum modification revision.
  • min_create_revision (integer, optional): Minimum creation revision.
  • max_create_revision (integer, optional): Maximum creation revision.
  • sort_order (string, optional): One of "none", "ascend", or "descend".
  • sort_target (string, optional): One of "key", "version", "create", "mod", or "value".
• Returns: table.

Return table shape:

• header (table | nil): Response header metadata.
• kvs (table): Dense Lua array of KV entries.
• count (integer): Number of matched keys reported by etcd.
• more (boolean): Whether more results remain on the server.

Example:

local etcd = ptool.etcd.connect({ address = "127.0.0.1:2379" })
local resp = etcd:list("/apps/api/", {
  keys_only = true,
  sort_order = "ascend",
  sort_target = "key",
})

for _, item in ipairs(resp.kvs) do
  print(item.key)
end

request

v0.11.0 - Introduced.

Canonical API name: ptool.etcd.Connection:request.

conn:request(options) sends a raw HTTP request through the current etcd connection defaults and returns the same Response object shape as ptool.http.request(...).

options supports the same request fields as ptool.http.request(options), plus:

• path (string, optional): An etcd-relative path such as "/kv/txn" or "/v3/kv/txn".
• url (string, optional): An explicit absolute URL.

Notes:

• Exactly one of path or url is required.
• Connection defaults automatically add the configured authorization header and timeout_ms when they are not overridden by the request.
• Relative path values are resolved against the configured api_prefix.

Example:

local etcd = ptool.etcd.connect({ address = "127.0.0.1:2379" })
local resp = etcd:request({
  path = "/kv/txn",
  json = {
    compare = {},
    success = {},
    failure = {},
  },
  fail_on_http_error = true,
})

print(resp:text())