25 MB lightweight cross-platform database client for 100+ databases, including MySQL, PostgreSQL, SQLite, Redis, MongoDB, DuckDB, SQL Server, and Dameng. Built-in AI, MCP Server, CLI, desktop and Docker. | 轻量级跨平台数据库管理工具,支持 MySQL、PostgreSQL、SQLite、Redis、MongoDB、达梦等 100+ 数据库,提供桌面端、Docker、CLI、内置 AI 助手和 MCP。
TypeScript aicliclickhousedatabasedatabase-clientdatabase-managementdockerguimcpmongodbmysqlpostgresqlredisrustsql-serversqlitetaurivue
use base64::engine::general_purpose::{STANDARD, URL_SAFE_NO_PAD};
use base64::Engine;
use percent_encoding::{utf8_percent_encode, NON_ALPHANUMERIC};
use reqwest::{Method, Url};
use serde::{Deserialize, Serialize};
use crate::agent_kv::{
KvDeleteOptions, KvDeleteResponse, KvGetResponse, KvInt64, KvKeyMetadata, KvKeySummary, KvListPrefixResponse,
KvPutOptions, KvPutResponse, KvValue, KvValueEncoding, KvWriteMode,
};
use crate::connection::AppState;
use super::client::{client_for_state, ensure_writable_core, ConsulClient};
use super::response::{
decode_json_body, decode_json_response, decode_text_response, ensure_success, is_consul_kv_not_found,
ConsulResponseMetadata, MAX_RESPONSE_BYTES,
};
use super::types::ConsulKvEntry;
const MAX_VALUE_BYTES: usize = 512 * 1024;
pub const MAX_RECURSIVE_ENTRIES: usize = 10_000;
pub const MAX_RECURSIVE_VALUE_BYTES: usize = 32 * 1024 * 1024;
const MAX_RECURSIVE_RESPONSE_BYTES: usize = MAX_RESPONSE_BYTES;
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct ConsulKvRecord {
pub key: String,
pub value: KvValue,
pub flags: KvInt64,
pub create_index: KvInt64,
pub modify_index: KvInt64,
pub lock_index: KvInt64,
pub session: Option<String>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct ConsulRecursiveListResponse {
pub entries: Vec<ConsulKvRecord>,
pub index: Option<KvInt64>,
pub filtered_by_acls: Option<bool>,
pub total_value_bytes: u64,
pub complete: bool,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct ConsulLockRequest {
pub key: String,
pub session: String,
pub value: KvValue,
pub flags: Option<KvInt64>,
pub expected_modify_index: Option<KvInt64>,
}
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct ConsulLockResponse {
pub acquired: bool,
pub key: String,
pub session: String,
}
impl ConsulClient {
pub(super) async fn acquire_lock(&self, request: ConsulLockRequest) -> Result<ConsulLockResponse, String> {
let session = required_lock_field(&request.session, "session")?;
let bytes = value_bytes(&request.value)?;
if bytes.len() > MAX_VALUE_BYTES {
return Err(format!("CONSUL_VALUE_TOO_LARGE: Consul KV values cannot exceed {MAX_VALUE_BYTES} bytes"));
}
let current = match self.get_required_entry(&request.key).await {
Ok(current) => Some(current),
Err(error) if error.starts_with("CONSUL_KEY_NOT_FOUND:") => None,
Err(error) => return Err(error),
};
if let Some(current) = ¤t {
if let Some(owner) = current.session.as_deref().filter(|owner| !owner.is_empty()) {
if owner != session {
return Err("CONSUL_LOCK_CONFLICT: The key is held by a different Consul Session".to_string());
}
}
let expected = request
.expected_modify_index
.as_ref()
.ok_or("CONSUL_CAS_REQUIRED: Acquiring an existing Consul lock requires its ModifyIndex")?;
if parse_u64(expected)? != current.modify_index {
return Err("CONSUL_CAS_CONFLICT: The Consul KV key changed before lock acquisition".to_string());
}
} else if request.expected_modify_index.as_ref().is_some_and(|value| value.as_str() != "0") {
return Err("CONSUL_CAS_CONFLICT: The Consul KV key no longer exists".to_string());
}
let cas = current.as_ref().map(|entry| entry.modify_index).unwrap_or(0);
let flags = request
.flags
.as_ref()
.map(parse_u64)
.transpose()?
.unwrap_or_else(|| current.as_ref().map(|entry| entry.flags).unwrap_or(0));
let mut url = self.kv_url(&request.key)?;
self.append_scope(&mut url, false);
url.query_pairs_mut()
.append_pair("acquire", session)
.append_pair("cas", &cas.to_string())
.append_pair("flags", &flags.to_string());
let response =
ensure_success(self.send(Method::PUT, url, Some(bytes)).await?, "acquire Consul KV lock", self.token())
.await?;
let acquired = decode_text_response(response, "acquire Consul KV lock").await?;
if acquired.trim() != "true" {
return Err("CONSUL_LOCK_CONFLICT: Consul refused lock acquisition".to_string());
}
Ok(ConsulLockResponse { acquired: true, key: request.key, session: session.to_string() })
}
pub(super) async fn release_lock(&self, key: &str, session: &str) -> Result<ConsulLockResponse, String> {
let session = required_lock_field(session, "session")?;
let current = self.get_required_entry(key).await?;
if current.session.as_deref() != Some(session) {
return Err("CONSUL_LOCK_SESSION_MISMATCH: Only the Session holding this key can release it".to_string());
}
let bytes = decode_consul_value(current.value.as_deref())?;
let mut url = self.kv_url(key)?;
self.append_scope(&mut url, false);
url.query_pairs_mut()
.append_pair("release", session)
.append_pair("cas", ¤t.modify_index.to_string())
.append_pair("flags", ¤t.flags.to_string());
let response =
ensure_success(self.send(Method::PUT, url, Some(bytes)).await?, "release Consul KV lock", self.token())
.await?;
let released = decode_text_response(response, "release Consul KV lock").await?;
if released.trim() != "true" {
return Err("CONSUL_LOCK_CONFLICT: Consul refused lock release".to_string());
}
Ok(ConsulLockResponse { acquired: false, key: key.to_string(), session: session.to_string() })
}
pub async fn list_recursive(
&self,
prefix: &str,
max_entries: usize,
max_value_bytes: usize,
) -> Result<ConsulRecursiveListResponse, String> {
self.list_recursive_with_control(prefix, max_entries, max_value_bytes, None).await
}
pub(super) async fn list_recursive_with_control(
&self,
prefix: &str,
max_entries: usize,
max_value_bytes: usize,
control: Option<&(dyn Fn(usize) -> Result<(), String> + Send + Sync)>,
) -> Result<ConsulRecursiveListResponse, String> {
let max_entries = max_entries.clamp(1, MAX_RECURSIVE_ENTRIES);
let max_value_bytes = max_value_bytes.clamp(MAX_VALUE_BYTES, MAX_RECURSIVE_VALUE_BYTES);
let mut url = self.kv_url(prefix)?;
self.append_scope(&mut url, true);
url.query_pairs_mut().append_pair("recurse", "");
let mut response = self.send(Method::GET, url, None).await?;
let metadata = ConsulResponseMetadata::from_response(&response);
if is_consul_kv_not_found(&response) {
return Ok(ConsulRecursiveListResponse {
entries: Vec::new(),
index: metadata.index,
filtered_by_acls: metadata.filtered_by_acls,
total_value_bytes: 0,
complete: true,
});
}
if !response.status().is_success() {
return ensure_success(response, "list Consul KV prefix recursively", self.token())
.await
.map(|_| unreachable!());
}
let mut body = Vec::new();
while let Some(chunk) = response
.chunk()
.await
.map_err(|error| format!("Failed to read Consul recursive KV response: {}", error.without_url()))?
{
control.map(|check| check(0)).transpose()?;
if body.len().saturating_add(chunk.len()) > MAX_RECURSIVE_RESPONSE_BYTES {
return Err(format!(
"CONSUL_SCAN_LIMIT_EXCEEDED: Consul recursive KV response exceeds {} MiB",
MAX_RECURSIVE_RESPONSE_BYTES / 1024 / 1024
));
}
body.extend_from_slice(&chunk);
}
let raw_entries = decode_json_body::<Vec<ConsulKvEntry>>(&body, "list Consul KV prefix recursively")?;
if raw_entries.len() > max_entries {
return Err(format!("CONSUL_SCAN_LIMIT_EXCEEDED: Consul prefix contains more than {max_entries} keys"));
}
let mut entries = Vec::with_capacity(raw_entries.len());
let mut total_value_bytes = 0usize;
for (index, entry) in raw_entries.into_iter().enumerate() {
control.map(|check| check(index + 1)).transpose()?;
let bytes = decode_consul_value(entry.value.as_deref())?;
total_value_bytes = total_value_bytes.saturating_add(bytes.len());
if total_value_bytes > max_value_bytes {
return Err(format!(
"CONSUL_SCAN_LIMIT_EXCEEDED: Consul prefix values exceed {} MiB",
max_value_bytes / 1024 / 1024
));
}
entries.push(ConsulKvRecord {
key: entry.key,
value: value_from_bytes(&bytes),
flags: KvInt64(entry.flags.to_string()),
create_index: KvInt64(entry.create_index.to_string()),
modify_index: KvInt64(entry.modify_index.to_string()),
lock_index: KvInt64(entry.lock_index.to_string()),
session: entry.session.filter(|session| !session.is_empty()),
});
}
Ok(ConsulRecursiveListResponse {
entries,
index: metadata.index,
filtered_by_acls: metadata.filtered_by_acls,
total_value_bytes: total_value_bytes as u64,
complete: true,
})
}
pub async fn list_prefix(
&self,
prefix: &str,
limit: usize,
continuation: Option<&str>,
) -> Result<KvListPrefixResponse, String> {
let mut url = self.kv_url(prefix)?;
self.append_scope(&mut url, true);
url.query_pairs_mut().append_pair("keys", "").append_pair("separator", "/");
let response = self.send(Method::GET, url, None).await?;
let metadata = ConsulResponseMetadata::from_response(&response);
if is_consul_kv_not_found(&response) {
return Ok(KvListPrefixResponse {
keys: Vec::new(),
continuation: None,
revision: metadata.index,
filtered_by_acls: metadata.filtered_by_acls,
});
}
let response = ensure_success(response, "list KV keys", self.token()).await?;
let mut keys = decode_json_response::<Vec<String>>(response, "list KV keys").await?;
keys.sort();
keys.dedup();
if !prefix.is_empty() {
keys.retain(|key| key != prefix);
}
let after = continuation.map(decode_continuation).transpose()?;
if let Some(after) = after.as_deref() {
keys.retain(|key| key.as_str() > after);
}
let limit = limit.clamp(1, 500);
let has_more = keys.len() > limit;
keys.truncate(limit);
let next = has_more.then(|| keys.last().map(|key| encode_continuation(key))).flatten();
Ok(KvListPrefixResponse {
keys: keys.into_iter().map(summary_for_key).collect(),
continuation: next,
revision: metadata.index,
filtered_by_acls: metadata.filtered_by_acls,
})
}
pub async fn get_key(&self, key: &str) -> Result<KvGetResponse, String> {
let mut url = self.kv_url(key)?;
self.append_scope(&mut url, true);
let response = self.send(Method::GET, url, None).await?;
if is_consul_kv_not_found(&response) {
return Ok(KvGetResponse { found: false, key: None, key_bytes: None, value: None, metadata: None });
}
let response = ensure_success(response, "read KV key", self.token()).await?;
let mut entries = decode_json_response::<Vec<ConsulKvEntry>>(response, "read KV key").await?;
let entry = entries.pop().ok_or("CONSUL_KEY_NOT_FOUND: Consul returned an empty KV response")?;
let bytes = decode_consul_value(entry.value.as_deref())?;
let value = value_from_bytes(&bytes);
Ok(KvGetResponse {
found: true,
key: Some(entry.key.clone()),
key_bytes: None,
value: Some(value),
metadata: Some(metadata_for_entry(&entry, bytes.len() as u64)),
})
}
pub(super) async fn put_key(
&self,
key: &str,
value: KvValue,
options: KvPutOptions,
) -> Result<KvPutResponse, String> {
let bytes = value_bytes(&value)?;
if bytes.len() > MAX_VALUE_BYTES {
return Err(format!(
"CONSUL_VALUE_TOO_LARGE: Consul KV values cannot exceed {MAX_VALUE_BYTES} bytes (received {})",
bytes.len()
));
}
let creating = matches!(options.write_mode, Some(KvWriteMode::Create))
|| options.expected_create_revision.as_ref().is_some_and(|value| value.as_str() == "0");
let (cas, flags) = if creating {
(0, options.flags.as_ref().map(parse_u64).transpose()?.unwrap_or(0))
} else {
let expected = parse_u64(options.expected_mod_revision.as_ref().ok_or_else(|| {
"CONSUL_CAS_REQUIRED: Updating a Consul KV key requires its ModifyIndex".to_string()
})?)?;
let current = self.get_required_entry(key).await?;
ensure_unlocked(¤t)?;
if current.modify_index != expected {
return Err("CONSUL_CAS_CONFLICT: The Consul KV key changed before it could be saved".to_string());
}
(expected, options.flags.as_ref().map(parse_u64).transpose()?.unwrap_or(current.flags))
};
let mut url = self.kv_url(key)?;
self.append_scope(&mut url, false);
url.query_pairs_mut().append_pair("cas", &cas.to_string()).append_pair("flags", &flags.to_string());
let response =
ensure_success(self.send(Method::PUT, url, Some(bytes)).await?, "write KV key", self.token()).await?;
let written = decode_text_response(response, "write KV key").await?;
if written.trim() != "true" {
return Err(if creating {
"CONSUL_KEY_ALREADY_EXISTS: The Consul KV key already exists".to_string()
} else {
"CONSUL_CAS_CONFLICT: The Consul KV key changed before it could be saved".to_string()
});
}
Ok(KvPutResponse { revision: None, key: Some(key.to_string()), created_key: creating.then(|| key.to_string()) })
}
pub(super) async fn delete_key(&self, key: &str, options: KvDeleteOptions) -> Result<KvDeleteResponse, String> {
let expected =
parse_u64(options.expected_mod_revision.as_ref().ok_or_else(|| {
"CONSUL_CAS_REQUIRED: Deleting a Consul KV key requires its ModifyIndex".to_string()
})?)?;
let current = self.get_required_entry(key).await?;
ensure_unlocked(¤t)?;
if current.modify_index != expected {
return Err("CONSUL_CAS_CONFLICT: The Consul KV key changed before it could be deleted".to_string());
}
let mut url = self.kv_url(key)?;
self.append_scope(&mut url, false);
url.query_pairs_mut().append_pair("cas", &expected.to_string());
let response =
ensure_success(self.send(Method::DELETE, url, None).await?, "delete KV key", self.token()).await?;
let deleted = decode_text_response(response, "delete KV key").await?;
if deleted.trim() != "true" {
return Err("CONSUL_CAS_CONFLICT: The Consul KV key changed before it could be deleted".to_string());
}
Ok(KvDeleteResponse { deleted: 1, revision: None })
}
async fn get_required_entry(&self, key: &str) -> Result<ConsulKvEntry, String> {
let mut url = self.kv_url(key)?;
self.append_scope(&mut url, true);
let response = self.send(Method::GET, url, None).await?;
if is_consul_kv_not_found(&response) {
return Err("CONSUL_KEY_NOT_FOUND: The Consul KV key no longer exists".to_string());
}
let response = ensure_success(response, "read KV metadata", self.token()).await?;
decode_json_response::<Vec<ConsulKvEntry>>(response, "read KV metadata")
.await?
.pop()
.ok_or_else(|| "CONSUL_KEY_NOT_FOUND: Consul returned an empty KV response".to_string())
}
fn kv_url(&self, key: &str) -> Result<Url, String> {
let encoded = key
.split('/')
.map(|segment| utf8_percent_encode(segment, NON_ALPHANUMERIC).to_string())
.collect::<Vec<_>>()
.join("/");
self.api_url(&format!("/v1/kv/{encoded}"))
}
}
pub async fn consul_list_prefix_core(
state: &AppState,
connection_id: &str,
prefix: &str,
limit: usize,
continuation: Option<&str>,
) -> Result<KvListPrefixResponse, String> {
client_for_state(state, connection_id).await?.list_prefix(prefix, limit, continuation).await
}
pub async fn consul_list_recursive_core(
state: &AppState,
connection_id: &str,
prefix: &str,
max_entries: usize,
max_value_bytes: usize,
) -> Result<ConsulRecursiveListResponse, String> {
client_for_state(state, connection_id).await?.list_recursive(prefix, max_entries, max_value_bytes).await
}
pub async fn consul_get_core(state: &AppState, connection_id: &str, key: &str) -> Result<KvGetResponse, String> {
client_for_state(state, connection_id).await?.get_key(key).await
}
pub async fn consul_put_core(
state: &AppState,
connection_id: &str,
key: &str,
value: KvValue,
options: KvPutOptions,
) -> Result<KvPutResponse, String> {
ensure_writable_core(state, connection_id, "write Consul KV key").await?;
client_for_state(state, connection_id).await?.put_key(key, value, options).await
}
pub async fn consul_delete_core(
state: &AppState,
connection_id: &str,
key: &str,
options: KvDeleteOptions,
) -> Result<KvDeleteResponse, String> {
ensure_writable_core(state, connection_id, "delete Consul KV key").await?;
client_for_state(state, connection_id).await?.delete_key(key, options).await
}
pub async fn consul_acquire_lock_core(
state: &AppState,
connection_id: &str,
request: ConsulLockRequest,
) -> Result<ConsulLockResponse, String> {
ensure_writable_core(state, connection_id, "acquire Consul KV lock").await?;
client_for_state(state, connection_id).await?.acquire_lock(request).await
}
pub async fn consul_release_lock_core(
state: &AppState,
connection_id: &str,
key: &str,
session: &str,
) -> Result<ConsulLockResponse, String> {
ensure_writable_core(state, connection_id, "release Consul KV lock").await?;
client_for_state(state, connection_id).await?.release_lock(key, session).await
}
fn required_lock_field<'a>(value: &'a str, field: &str) -> Result<&'a str, String> {
let value = value.trim();
if value.is_empty() {
Err(format!("CONSUL_INVALID_REQUEST: {field} is required"))
} else {
Ok(value)
}
}
fn summary_for_key(key: String) -> KvKeySummary {
KvKeySummary { key, key_bytes: None, value: None, metadata: empty_metadata() }
}
fn metadata_for_entry(entry: &ConsulKvEntry, value_size: u64) -> KvKeyMetadata {
KvKeyMetadata {
create_revision: Some(KvInt64(entry.create_index.to_string())),
mod_revision: Some(KvInt64(entry.modify_index.to_string())),
version: None,
lease: None,
ttl: None,
value_size: Some(value_size),
czxid: None,
mzxid: None,
pzxid: None,
ctime: None,
mtime: None,
cversion: None,
aversion: None,
ephemeral_owner: None,
data_length: None,
num_children: None,
flags: Some(KvInt64(entry.flags.to_string())),
lock_index: Some(KvInt64(entry.lock_index.to_string())),
session: entry.session.clone().filter(|session| !session.is_empty()),
}
}
fn empty_metadata() -> KvKeyMetadata {
KvKeyMetadata {
create_revision: None,
mod_revision: None,
version: None,
lease: None,
ttl: None,
value_size: None,
czxid: None,
mzxid: None,
pzxid: None,
ctime: None,
mtime: None,
cversion: None,
aversion: None,
ephemeral_owner: None,
data_length: None,
num_children: None,
flags: None,
lock_index: None,
session: None,
}
}
fn decode_consul_value(value: Option<&str>) -> Result<Vec<u8>, String> {
match value {
Some(value) => {
STANDARD.decode(value).map_err(|error| format!("Failed to decode Consul KV Base64 value: {error}"))
}
None => Ok(Vec::new()),
}
}
fn value_from_bytes(bytes: &[u8]) -> KvValue {
match std::str::from_utf8(bytes) {
Ok(value) => KvValue { encoding: KvValueEncoding::Utf8, data: value.to_string() },
Err(_) => KvValue { encoding: KvValueEncoding::Base64, data: STANDARD.encode(bytes) },
}
}
fn value_bytes(value: &KvValue) -> Result<Vec<u8>, String> {
match value.encoding {
KvValueEncoding::Utf8 => Ok(value.data.as_bytes().to_vec()),
KvValueEncoding::Base64 => STANDARD
.decode(value.data.chars().filter(|char| !char.is_whitespace()).collect::<String>())
.map_err(|error| format!("Invalid Base64 KV value: {error}")),
}
}
fn parse_u64(value: &KvInt64) -> Result<u64, String> {
value.as_str().parse::<u64>().map_err(|_| format!("Invalid Consul index: {}", value.as_str()))
}
fn ensure_unlocked(entry: &ConsulKvEntry) -> Result<(), String> {
if let Some(session) = entry.session.as_deref().filter(|session| !session.is_empty()) {
return Err(format!("CONSUL_KEY_LOCKED: The Consul KV key is held by session {session}"));
}
Ok(())
}
fn encode_continuation(key: &str) -> String {
URL_SAFE_NO_PAD.encode(key.as_bytes())
}
fn decode_continuation(value: &str) -> Result<String, String> {
let bytes = URL_SAFE_NO_PAD.decode(value).map_err(|_| "Invalid Consul continuation token".to_string())?;
String::from_utf8(bytes).map_err(|_| "Invalid Consul continuation token".to_string())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn u64_fields_accept_the_full_unsigned_range_only() {
assert_eq!(parse_u64(&KvInt64("0".into())).unwrap(), 0);
assert_eq!(parse_u64(&KvInt64(u64::MAX.to_string())).unwrap(), u64::MAX);
assert!(parse_u64(&KvInt64("-1".into())).is_err());
assert!(parse_u64(&KvInt64("18446744073709551616".into())).is_err());
}
#[test]
fn binary_values_round_trip_without_utf8_coercion() {
let bytes = [0, 0xff, 0x80, b'a'];
let value = value_from_bytes(&bytes);
assert_eq!(value.encoding, KvValueEncoding::Base64);
assert_eq!(value_bytes(&value).unwrap(), bytes);
}
}