Skip to content

armgit / dbx

Public Imported from GitHub
0

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。

19.0 KB
Raw Blame
use base64::engine::general_purpose::STANDARD;
use base64::Engine;
use reqwest::{Method, StatusCode};
use serde::{Deserialize, Serialize};

use crate::agent_kv::{KvInt64, KvValue, KvValueEncoding};
use crate::connection::AppState;

use super::client::{client_for_state, ensure_writable_core, ConsulClient};
use super::response::{decode_json_response, ensure_success};

pub const MAX_TXN_OPERATIONS: usize = 64;

#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "kebab-case")]
pub enum ConsulTxnVerb {
    Get,
    GetTree,
    Set,
    Cas,
    Delete,
    DeleteCas,
    DeleteTree,
    Lock,
    Unlock,
    CheckIndex,
    CheckNotExists,
    CheckSession,
}

impl ConsulTxnVerb {
    fn as_str(self) -> &'static str {
        match self {
            Self::Get => "get",
            Self::GetTree => "get-tree",
            Self::Set => "set",
            Self::Cas => "cas",
            Self::Delete => "delete",
            Self::DeleteCas => "delete-cas",
            Self::DeleteTree => "delete-tree",
            Self::Lock => "lock",
            Self::Unlock => "unlock",
            Self::CheckIndex => "check-index",
            Self::CheckNotExists => "check-not-exists",
            Self::CheckSession => "check-session",
        }
    }

    fn writes(self) -> bool {
        matches!(
            self,
            Self::Set | Self::Cas | Self::Delete | Self::DeleteCas | Self::DeleteTree | Self::Lock | Self::Unlock
        )
    }
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ConsulTxnKvOperation {
    pub verb: ConsulTxnVerb,
    pub key: String,
    pub value: Option<KvValue>,
    pub flags: Option<KvInt64>,
    pub index: Option<KvInt64>,
    pub session: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ConsulTxnRequest {
    pub operations: Vec<ConsulTxnKvOperation>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ConsulTxnError {
    pub op_index: usize,
    pub message: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(rename_all = "camelCase")]
pub struct ConsulTxnResult {
    pub committed: bool,
    pub errors: Vec<ConsulTxnError>,
    pub results: Vec<ConsulTxnKvResult>,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub struct ConsulTxnKvResult {
    pub key: String,
    pub value: Option<KvValue>,
    pub flags: KvInt64,
    pub create_index: KvInt64,
    pub modify_index: KvInt64,
    pub lock_index: KvInt64,
    pub session: Option<String>,
}

#[derive(Debug, Deserialize)]
#[serde(rename_all = "PascalCase")]
struct RawTxnResponse {
    #[serde(default)]
    errors: Option<Vec<RawTxnError>>,
    #[serde(default)]
    results: Option<Vec<RawTxnResult>>,
}

#[derive(Debug, Deserialize)]
#[serde(rename_all = "PascalCase")]
struct RawTxnResult {
    #[serde(rename = "KV", alias = "Kv")]
    kv: Option<RawTxnKvResult>,
}

#[derive(Debug, Deserialize)]
#[serde(rename_all = "PascalCase")]
struct RawTxnKvResult {
    #[serde(default)]
    key: String,
    value: Option<String>,
    #[serde(default)]
    flags: u64,
    #[serde(default)]
    create_index: u64,
    #[serde(default)]
    modify_index: u64,
    #[serde(default)]
    lock_index: u64,
    session: Option<String>,
}

#[derive(Debug, Deserialize)]
#[serde(rename_all = "PascalCase")]
struct RawTxnError {
    op_index: usize,
    what: String,
}

impl ConsulClient {
    pub(super) async fn txn(&self, request: ConsulTxnRequest) -> Result<ConsulTxnResult, String> {
        validate_operations(&request.operations)?;
        let body = serde_json::to_vec(&request.operations.iter().map(operation_json).collect::<Result<Vec<_>, _>>()?)
            .map_err(|error| format!("Failed to encode Consul transaction: {error}"))?;
        let mut url = self.api_url("/v1/txn")?;
        self.append_scope(&mut url, false);
        let response = self.send(Method::PUT, url, Some(body)).await?;
        let status = response.status();
        let response = if is_txn_result_status(response.status()) {
            response
        } else {
            ensure_success(response, "execute transaction", self.token()).await?
        };
        let response = decode_json_response::<RawTxnResponse>(response, "execute transaction").await?;
        map_txn_response(status, response)
    }
}

fn map_txn_response(status: StatusCode, response: RawTxnResponse) -> Result<ConsulTxnResult, String> {
    let errors = response
        .errors
        .unwrap_or_default()
        .into_iter()
        .map(|error| ConsulTxnError { op_index: error.op_index, message: error.what })
        .collect::<Vec<_>>();
    let results = response
        .results
        .unwrap_or_default()
        .into_iter()
        .filter_map(|result| result.kv)
        .map(txn_result)
        .collect::<Result<_, _>>()?;
    Ok(ConsulTxnResult { committed: status.is_success() && errors.is_empty(), errors, results })
}

fn is_txn_result_status(status: StatusCode) -> bool {
    status.is_success() || status == StatusCode::CONFLICT
}

pub async fn consul_txn_core(
    state: &AppState,
    connection_id: &str,
    request: ConsulTxnRequest,
) -> Result<ConsulTxnResult, String> {
    validate_public_operations(&request.operations)?;
    if request.operations.iter().any(|operation| operation.verb.writes()) {
        ensure_writable_core(state, connection_id, "execute Consul transaction").await?;
    }
    let client = client_for_state(state, connection_id).await?;
    for operation in request
        .operations
        .iter()
        .filter(|operation| matches!(operation.verb, ConsulTxnVerb::Cas | ConsulTxnVerb::DeleteCas))
    {
        let current = client.get_key(&operation.key).await?;
        if current
            .metadata
            .as_ref()
            .and_then(|metadata| metadata.session.as_deref())
            .is_some_and(|session| !session.is_empty())
        {
            return Err(format!("CONSUL_KEY_LOCKED: The Consul KV key '{}' is held by a Session", operation.key));
        }
    }
    client.txn(request).await
}

pub async fn consul_rename_key_core(
    state: &AppState,
    connection_id: &str,
    source: &str,
    target: &str,
    expected_modify_index: KvInt64,
    copy: bool,
) -> Result<ConsulTxnResult, String> {
    ensure_writable_core(state, connection_id, if copy { "copy Consul KV key" } else { "rename Consul KV key" })
        .await?;
    if source.is_empty() || target.is_empty() || source == target {
        return Err("CONSUL_RENAME_INVALID: Source and target keys must be distinct and non-empty".to_string());
    }
    let expected = parse_index(&expected_modify_index)?;
    let client = client_for_state(state, connection_id).await?;
    let current = client.get_key(source).await?;
    if !current.found {
        return Err("CONSUL_KEY_NOT_FOUND: Source key no longer exists".to_string());
    }
    let current_index = current
        .metadata
        .as_ref()
        .and_then(|metadata| metadata.mod_revision.as_ref())
        .ok_or("CONSUL_CAS_REQUIRED: Source key has no ModifyIndex")?;
    if parse_index(current_index)? != expected {
        return Err("CONSUL_CAS_CONFLICT: Source key changed before the transaction".to_string());
    }
    if current.metadata.as_ref().and_then(|metadata| metadata.session.as_deref()).is_some_and(|value| !value.is_empty())
    {
        return Err("CONSUL_KEY_LOCKED: Source key is held by a Consul Session".to_string());
    }
    let mut operations = vec![
        ConsulTxnKvOperation {
            verb: ConsulTxnVerb::CheckIndex,
            key: source.to_string(),
            value: None,
            flags: None,
            index: Some(expected_modify_index.clone()),
            session: None,
        },
        operation(ConsulTxnVerb::CheckNotExists, target),
        ConsulTxnKvOperation {
            verb: ConsulTxnVerb::Cas,
            key: target.to_string(),
            value: current.value,
            flags: current.metadata.as_ref().and_then(|metadata| metadata.flags.clone()),
            index: Some(KvInt64("0".to_string())),
            session: None,
        },
    ];
    if !copy {
        operations.push(ConsulTxnKvOperation {
            verb: ConsulTxnVerb::DeleteCas,
            key: source.to_string(),
            value: None,
            flags: None,
            index: Some(expected_modify_index),
            session: None,
        });
    }
    client.txn(ConsulTxnRequest { operations }).await
}

pub(crate) fn cas_operation(key: String, value: KvValue, flags: KvInt64, index: KvInt64) -> ConsulTxnKvOperation {
    ConsulTxnKvOperation {
        verb: ConsulTxnVerb::Cas,
        key,
        value: Some(value),
        flags: Some(flags),
        index: Some(index),
        session: None,
    }
}

pub(crate) fn delete_cas_operation(key: String, index: KvInt64) -> ConsulTxnKvOperation {
    ConsulTxnKvOperation {
        verb: ConsulTxnVerb::DeleteCas,
        key,
        value: None,
        flags: None,
        index: Some(index),
        session: None,
    }
}

fn operation(verb: ConsulTxnVerb, key: &str) -> ConsulTxnKvOperation {
    ConsulTxnKvOperation { verb, key: key.to_string(), value: None, flags: None, index: None, session: None }
}

fn validate_operations(operations: &[ConsulTxnKvOperation]) -> Result<(), String> {
    if operations.is_empty() {
        return Err("CONSUL_TXN_EMPTY: A transaction requires at least one operation".to_string());
    }
    if operations.len() > MAX_TXN_OPERATIONS {
        return Err(format!(
            "CONSUL_TXN_LIMIT_EXCEEDED: Consul transactions support at most {MAX_TXN_OPERATIONS} operations"
        ));
    }
    for operation in operations {
        if operation.key.is_empty() {
            return Err("CONSUL_TXN_KEY_REQUIRED: Transaction keys cannot be empty".to_string());
        }
        if operation.index.as_ref().is_some_and(|index| parse_index(index).is_err()) {
            return Err(format!("CONSUL_TXN_INDEX_INVALID: Invalid Index for key {}", operation.key));
        }
        if operation.flags.as_ref().is_some_and(|flags| parse_index(flags).is_err()) {
            return Err(format!("CONSUL_TXN_FLAGS_INVALID: Invalid Flags for key {}", operation.key));
        }
        if matches!(operation.verb, ConsulTxnVerb::Lock | ConsulTxnVerb::Unlock | ConsulTxnVerb::CheckSession)
            && operation.session.as_deref().map(str::trim).is_none_or(str::is_empty)
        {
            return Err(format!(
                "CONSUL_TXN_SESSION_REQUIRED: {:?} requires a Session for key {}",
                operation.verb, operation.key
            ));
        }
        if matches!(operation.verb, ConsulTxnVerb::Lock) && operation.value.is_none() {
            return Err(format!("CONSUL_TXN_VALUE_REQUIRED: lock requires a value for key {}", operation.key));
        }
    }
    Ok(())
}

fn validate_public_operations(operations: &[ConsulTxnKvOperation]) -> Result<(), String> {
    validate_operations(operations)?;
    for operation in operations {
        match operation.verb {
            ConsulTxnVerb::Set | ConsulTxnVerb::Delete | ConsulTxnVerb::DeleteTree => {
                return Err(format!(
                    "CONSUL_TXN_UNSAFE_VERB: Public transactions cannot use unconditional {:?}; use CAS or a dedicated prefix workflow",
                    operation.verb
                ));
            }
            ConsulTxnVerb::Cas | ConsulTxnVerb::DeleteCas if operation.index.is_none() => {
                return Err(format!(
                    "CONSUL_CAS_REQUIRED: {:?} requires an Index for key {}",
                    operation.verb, operation.key
                ));
            }
            ConsulTxnVerb::Cas if operation.value.is_none() => {
                return Err(format!("CONSUL_TXN_VALUE_REQUIRED: cas requires a value for key {}", operation.key));
            }
            _ => {}
        }
    }
    Ok(())
}

fn txn_result(raw: RawTxnKvResult) -> Result<ConsulTxnKvResult, String> {
    let value = raw
        .value
        .as_deref()
        .map(|encoded| {
            let bytes = STANDARD
                .decode(encoded)
                .map_err(|error| format!("CONSUL_INVALID_RESPONSE: Invalid transaction Value: {error}"))?;
            Ok::<_, String>(match String::from_utf8(bytes.clone()) {
                Ok(value) => KvValue { encoding: KvValueEncoding::Utf8, data: value },
                Err(_) => KvValue { encoding: KvValueEncoding::Base64, data: STANDARD.encode(bytes) },
            })
        })
        .transpose()?;
    Ok(ConsulTxnKvResult {
        key: raw.key,
        value,
        flags: KvInt64(raw.flags.to_string()),
        create_index: KvInt64(raw.create_index.to_string()),
        modify_index: KvInt64(raw.modify_index.to_string()),
        lock_index: KvInt64(raw.lock_index.to_string()),
        session: raw.session.filter(|session| !session.is_empty()),
    })
}

fn operation_json(operation: &ConsulTxnKvOperation) -> Result<serde_json::Value, String> {
    let mut kv = serde_json::Map::new();
    kv.insert("Verb".to_string(), operation.verb.as_str().into());
    kv.insert("Key".to_string(), operation.key.clone().into());
    if let Some(value) = &operation.value {
        let bytes = match value.encoding {
            KvValueEncoding::Utf8 => value.data.as_bytes().to_vec(),
            KvValueEncoding::Base64 => STANDARD
                .decode(value.data.chars().filter(|character| !character.is_whitespace()).collect::<String>())
                .map_err(|error| format!("CONSUL_VALUE_ENCODING_INVALID: {error}"))?,
        };
        kv.insert("Value".to_string(), STANDARD.encode(bytes).into());
    }
    if let Some(flags) = &operation.flags {
        kv.insert("Flags".to_string(), parse_index(flags)?.into());
    }
    if let Some(index) = &operation.index {
        kv.insert("Index".to_string(), parse_index(index)?.into());
    }
    if let Some(session) = &operation.session {
        kv.insert("Session".to_string(), session.clone().into());
    }
    Ok(serde_json::json!({ "KV": kv }))
}

fn parse_index(value: &KvInt64) -> Result<u64, String> {
    value.as_str().parse::<u64>().map_err(|_| format!("Invalid unsigned 64-bit integer: {}", value.as_str()))
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::consul::test_support::{serve_once, test_client};

    #[test]
    fn enforces_transaction_limit() {
        let operations =
            (0..65).map(|index| operation(ConsulTxnVerb::Get, &format!("key-{index}"))).collect::<Vec<_>>();
        assert!(validate_operations(&operations).unwrap_err().contains("CONSUL_TXN_LIMIT_EXCEEDED"));
    }

    #[test]
    fn serializes_u64_as_json_number_and_value_as_base64() {
        let value = KvValue { encoding: KvValueEncoding::Utf8, data: "hello".to_string() };
        let encoded = operation_json(&cas_operation(
            "a b".to_string(),
            value,
            KvInt64(u64::MAX.to_string()),
            KvInt64("0".to_string()),
        ))
        .unwrap();
        assert_eq!(encoded["KV"]["Value"], "aGVsbG8=");
        assert_eq!(encoded["KV"]["Flags"], u64::MAX);
    }

    #[test]
    fn public_transactions_reject_unconditional_writes_and_require_cas_fields() {
        for verb in [ConsulTxnVerb::Set, ConsulTxnVerb::Delete, ConsulTxnVerb::DeleteTree] {
            assert!(validate_public_operations(&[operation(verb, "key")]).unwrap_err().contains("UNSAFE_VERB"));
        }
        assert!(validate_public_operations(&[operation(ConsulTxnVerb::Cas, "key")])
            .unwrap_err()
            .contains("CAS_REQUIRED"));
        let mut cas = cas_operation(
            "key".into(),
            KvValue { encoding: KvValueEncoding::Utf8, data: "value".into() },
            KvInt64("0".into()),
            KvInt64("0".into()),
        );
        assert!(validate_public_operations(&[cas.clone()]).is_ok());
        cas.value = None;
        assert!(validate_public_operations(&[cas]).unwrap_err().contains("VALUE_REQUIRED"));
    }

    #[test]
    fn transaction_results_preserve_kv_data_and_indexes() {
        let result = txn_result(RawTxnKvResult {
            key: "binary".into(),
            value: Some("AP+A".into()),
            flags: u64::MAX,
            create_index: 2,
            modify_index: 3,
            lock_index: 4,
            session: Some("session-1".into()),
        })
        .unwrap();
        assert_eq!(result.value.unwrap().encoding, KvValueEncoding::Base64);
        assert_eq!(result.flags.as_str(), u64::MAX.to_string());
        assert_eq!(result.modify_index.as_str(), "3");
        assert_eq!(result.session.as_deref(), Some("session-1"));
    }

    #[test]
    fn transaction_conflicts_are_decoded_as_results() {
        assert!(is_txn_result_status(StatusCode::OK));
        assert!(is_txn_result_status(StatusCode::CONFLICT));
        assert!(!is_txn_result_status(StatusCode::BAD_REQUEST));
        assert!(!is_txn_result_status(StatusCode::INTERNAL_SERVER_ERROR));
    }

    #[test]
    fn empty_conflict_response_is_never_committed() {
        let result =
            map_txn_response(StatusCode::CONFLICT, RawTxnResponse { errors: Some(vec![]), results: Some(vec![]) })
                .unwrap();
        assert!(!result.committed);
        assert!(result.errors.is_empty());
        assert!(result.results.is_empty());
    }

    #[test]
    fn committed_delete_response_accepts_consul_null_collections() {
        // Consul returns this exact shape for a successful delete-cas transaction.
        let raw: RawTxnResponse = serde_json::from_str(r#"{"Results":[],"Errors":null}"#).unwrap();
        let result = map_txn_response(StatusCode::OK, raw).unwrap();
        assert!(result.committed);
        assert!(result.errors.is_empty());
        assert!(result.results.is_empty());
    }

    #[tokio::test]
    async fn conflict_response_preserves_results_errors_and_wire_contract() {
        let body = r#"{"Results":[{"KV":{"Key":"source","Value":"aGVsbG8=","Flags":7,"CreateIndex":2,"ModifyIndex":3,"LockIndex":0}}],"Errors":[{"OpIndex":1,"What":"target exists"}]}"#;
        let response = format!(
            "HTTP/1.1 409 Conflict\r\nContent-Type: application/json\r\nContent-Length: {}\r\nConnection: close\r\n\r\n{body}",
            body.len()
        );
        let (url, request_rx) = serve_once(response).await;
        let client = test_client(url).await;
        let result =
            client.txn(ConsulTxnRequest { operations: vec![operation(ConsulTxnVerb::Get, "source")] }).await.unwrap();

        assert!(!result.committed);
        assert_eq!(result.errors[0].op_index, 1);
        assert_eq!(result.results[0].key, "source");
        assert_eq!(result.results[0].value.as_ref().unwrap().data, "hello");

        let request = request_rx.await.unwrap();
        let (headers, body) = request.split_once("\r\n\r\n").unwrap();
        assert!(headers.starts_with("PUT /proxy/v1/txn?dc=dc1&ns=team-a&partition=partition-a HTTP/1.1"));
        assert!(headers.to_ascii_lowercase().contains("x-consul-token: fixture-token"));
        let wire: serde_json::Value = serde_json::from_str(body).unwrap();
        assert_eq!(wire[0]["KV"]["Verb"], "get");
        assert_eq!(wire[0]["KV"]["Key"], "source");
    }
}