Capabilities Preview em Rust - VillageSQL Server for MySQL

As APIs das capabilities Preview não são estáveis. Uma extensão compilada contra uma capability Preview pode falhar ao carregar após uma atualização do servidor.

As capabilities Preview são recursos do servidor expostos às extensões antes que suas APIs sejam finalizadas. O SDK Rust envolve cinco delas: variáveis de status, variáveis de sistema, threads de trabalho em segundo plano, consultas SQL a partir de uma thread de trabalho e acesso ao keyring. Esta página cobre como declarar e usar cada uma a partir do Rust. Para o conceito, o nível Preview e as capabilities que existem apenas em C++, consulte Capabilities Preview.

Pré-requisitos

Uma extensão que usa qualquer capability Preview só instala quando vsql_allow_preview_extensions está em ON:

SET PERSIST vsql_allow_preview_extensions = ON;

Consulte Habilitando o Nível Preview para os detalhes, incluindo por que SET GLOBAL é rejeitado para essa variável. Você também precisa de uma configuração Rust funcional para extensões — o passo a passo Criando Extensões em Rust cobre a toolchain, o cargo-vsql e o seu primeiro bloco extension!.

O Que o SDK Rust Envolve

Capability	Módulo Rust	Exemplo do SDK
`vsql::status_var`	`villagesql::preview::status_var`	`vsql_status_var`
`vsql::sys_var`	`villagesql::preview::sys_var`	`vsql_sys_var`
`vsql::preview::thread_worker`	`villagesql::preview::thread_worker`	`vsql_thread_worker`
`vsql::preview::sql_query`	`villagesql::preview::sql_query`	`vsql_sql_query`
`vsql::preview::keyring`	`villagesql::preview::keyring`	`vsql_keyring`

As demais capabilities Preview — auth, mysql_services, session_var, statement_event, as capabilities de índice personalizado e a ABI de armazenamento de coluna — são exclusivas do C++ hoje. Use o SDK C++ se você precisar de uma delas.

Padrão de Registro

Declare cada capability como um static e então liste-a por referência na seção requires: de extension! — o equivalente Rust do .with() do SDK C++:

use villagesql::preview::keyring::KeyringCapability;

static KEYRING: KeyringCapability = KeyringCapability::new();

villagesql::extension! {
    funcs: [
        // ...
    ],
    requires: [
        &KEYRING,
    ]
}

O servidor popula o objeto de capability no momento do carregamento; antes disso, seus métodos de acesso relatam a capability como indisponível em vez de travar. O static é obrigatório — o servidor mantém pointers para dentro da capability durante toda a vida da extensão.

Variáveis de Status

A capability status_var expõe contadores de propriedade da extensão através de SHOW GLOBAL STATUS. Sua extensão é dona do armazenamento como atômicos 'static e escreve neles; o servidor lê através dos pointers cada vez que a variável de status é consultada. Declare cada variável como um StatusVarSpec — Int respaldado por um AtomicI64, ou Double respaldado pelo AtomicF64 do SDK (a biblioteca padrão do Rust não tem um f64 atômico, então o SDK fornece um com new, load e store):

use std::sync::atomic::{AtomicI64, Ordering};

use villagesql::preview::status_var::{AtomicF64, StatusVarCapability, StatusVarSpec};
use villagesql::{InValue, VdfReturn};

static REQUESTS: AtomicI64 = AtomicI64::new(0);
static LOAD: AtomicF64 = AtomicF64::new(0.5);

static SPECS: &[StatusVarSpec] = &[
    StatusVarSpec::Int {
        name: c"requests",
        value: &REQUESTS,
    },
    StatusVarSpec::Double {
        name: c"load",
        value: &LOAD,
    },
];

static STATUS_VAR: StatusVarCapability = StatusVarCapability::new(SPECS);

fn bump_impl(_args: &[InValue]) -> VdfReturn {
    let n = REQUESTS.fetch_add(1, Ordering::Relaxed) + 1;
    VdfReturn::int(n)
}

villagesql::extension! {
    funcs: [
        villagesql::func!(bump_impl, "bump", [] -> villagesql::Type::Int),
    ],
    requires: [
        &STATUS_VAR,
    ]
}

Após o INSTALL EXTENSION, as variáveis aparecem com o nome da extensão como prefixo:

SELECT vsql_status_var.bump();
-- 1
SHOW GLOBAL STATUS LIKE 'vsql_status_var%';

Variable_name	Value
vsql_status_var.load	0.500000
vsql_status_var.requests	1

Variáveis de Sistema

A capability sys_var registra variáveis de sistema do MySQL de propriedade da sua extensão. Há suporte para três tipos: Bool, Int (com limites min/max) e Str. Todo spec carrega um nome, um comentário, um valor padrão e um callback on_change opcional. Nomes e valores padrão de string são valores &'static CStr — escreva-os como literais de string C (c"enabled"):

use villagesql::preview::sys_var::{SysVarCapability, SysVarSpec};

static SPECS: &[SysVarSpec] = &[
    SysVarSpec::Bool {
        name: c"enabled",
        comment: c"Enable the feature",
        default: true,
        on_change: None,
    },
    SysVarSpec::Int {
        name: c"threshold",
        comment: c"Threshold in milliseconds",
        default: 1000,
        min: 0,
        max: 60000,
        on_change: None,
    },
    SysVarSpec::Str {
        name: c"log_path",
        comment: c"Path to the log file",
        default: c"/tmp/vsql_sys_var.log",
        on_change: None,
    },
];

static SYS_VAR: SysVarCapability = SysVarCapability::new(SPECS);

villagesql::extension! {
    funcs: [],
    requires: [
        &SYS_VAR,
    ]
}

A seção funcs: deve estar presente antes de requires:, mesmo quando vazia. Após a instalação, as variáveis ficam endereçáveis com o nome da extensão como prefixo:

SELECT @@global.vsql_sys_var.enabled;
-- 1
SELECT @@global.vsql_sys_var.threshold;
-- 1000
SET GLOBAL vsql_sys_var.enabled = 0;

Reagindo a Mudanças

on_change é um callback C bruto, invocado pelo servidor depois que uma variável é definida. O servidor o chama enquanto mantém seu bloqueio global de variáveis de sistema, então mantenha-o rápido e não gere panic — um panic aqui atravessa a fronteira da FFI. O callback recebe um *const vef_sys_var_change_t da camada de ABI bruta:

use std::sync::atomic::{AtomicU64, Ordering};
use villagesql::sys::vef_sys_var_change_t;

static CHANGE_COUNT: AtomicU64 = AtomicU64::new(0);

unsafe extern "C" fn on_enabled_change(_change: *const vef_sys_var_change_t) {
    CHANGE_COUNT.fetch_add(1, Ordering::Relaxed);
}

Chamar SysVarCapability::get ou SysVarCapability::set, executar SQL ou esperar por uma thread que faça qualquer um dos dois causa deadlock nesse bloqueio. Mantenha o callback restrito a operações de controle interno nos seus próprios statics, como acima, e entregue o trabalho que precisa de SQL a uma thread de trabalho.

Conecte-o a um spec com on_change: Some(on_enabled_change).

Lendo e Escrevendo a partir do Código da Extensão

SysVarCapability também expõe get() e set() para acesso programático através do servidor (de forma que a validação de intervalo e a persistência sejam tratadas para você). set() recebe um argumento scope que seleciona a persistência: null altera apenas o valor em execução, então ele reverte na reinicialização; "PERSIST" altera o valor em execução e o escreve na configuração persistida; "PERSIST_ONLY" escreve na configuração persistida sem tocar no valor em execução, então ele se aplica na próxima reinicialização. Ambos são métodos FFI unsafe que recebem strings C terminadas em NUL, e ambos usam a convenção C invertida: Some(false) significa sucesso, Some(true) significa que o servidor relatou um erro, e None significa que a capability está indisponível. Em um get bem-sucedido, o servidor escreve uma string alocada com malloc que você deve liberar com o free() do C. O exemplo vsql_sys_var mostra o padrão completo, incluindo o extern do free e os comentários de segurança.

Thread de Trabalho

A capability thread_worker executa uma função que você fornece em uma thread em segundo plano gerenciada pelo servidor. O servidor registra uma variável de sistema de controle no momento do carregamento; enquanto ela está em ON, sua função de trabalho é chamada em um temporizador periódico, na prontidão de um descritor de arquivo, ou em transições de habilitação/desabilitação. Sua função de trabalho é Rust seguro e simples:

use std::sync::atomic::{AtomicI64, Ordering};
use std::time::Duration;

use villagesql::preview::thread_worker::{
    NextWakeup, ThreadHandle, ThreadWorkerCapability, WakeupReason,
};
use villagesql::{InValue, VdfReturn};

static TICKS: AtomicI64 = AtomicI64::new(0);

fn worker(reason: WakeupReason, _handle: &ThreadHandle) -> NextWakeup {
    if reason == WakeupReason::Periodic {
        TICKS.fetch_add(1, Ordering::Relaxed);
    }
    NextWakeup::unchanged()
}

static WORKER: ThreadWorkerCapability =
    ThreadWorkerCapability::new(worker, "ticker", Duration::from_millis(100), None);

fn ticks_impl(_args: &[InValue]) -> VdfReturn {
    VdfReturn::int(TICKS.load(Ordering::Relaxed))
}

villagesql::extension! {
    funcs: [
        villagesql::func!(ticks_impl, "ticks", [] -> villagesql::Type::Int),
    ],
    requires: [
        &WORKER,
    ]
}

ThreadWorkerCapability::new recebe a função de trabalho, um sufixo de nome de thread, o intervalo inicial de espera e um nome alternativo opcional para a variável de controle. Quando o nome alternativo é None, a variável de controle se chama {suffix}_enabled e é registrada sob o prefixo da extensão:

SHOW GLOBAL VARIABLES LIKE '%ticker%';

Variable_name	Value
vsql_thread_worker.ticker_enabled	OFF

SET GLOBAL vsql_thread_worker.ticker_enabled = ON;
SELECT SLEEP(0.5);
SELECT vsql_thread_worker.ticks();
-- 4  (varies with timing — one tick per 100 ms while enabled)
SET GLOBAL vsql_thread_worker.ticker_enabled = OFF;

Wakeups

WakeupReason diz por que o servidor chamou: Enable, Periodic, PollFd ou Disable. Seu valor de retorno ajusta o próximo wakeup:

NextWakeup::unchanged() — mantém o intervalo de espera e o poll fd atuais.
NextWakeup::after(duration) — acorda novamente após duration.
Defina o campo poll_fd com um descritor de arquivo maior que zero para também acordar quando ele ficar pronto para leitura, ou com -1 para limpar um que tenha sido definido antes.

Uma Duration de comprimento zero colapsa para “sem mudança” — a ABI C subjacente reserva o 0 para isso, então um wakeup instantâneo não pode ser expresso. Se a função de trabalho gerar panic, o SDK captura o panic na fronteira da FFI e trata a chamada como se ela retornasse NextWakeup::unchanged() — o worker continua em execução. Passe o parâmetro handle para SqlQueryCapability::open para executar SQL de dentro do worker.

Consulta SQL

A capability sql_query abre uma sessão SQL a partir de um callback de thread_worker, de modo que um worker em segundo plano pode executar instruções no servidor em que ele está carregado. Declare-a junto com ThreadWorkerCapability e abra uma sessão com o ThreadHandle que o worker recebe:

use std::sync::atomic::{AtomicI64, Ordering};
use std::time::Duration;

use villagesql::preview::sql_query::SqlQueryCapability;
use villagesql::preview::thread_worker::{
    NextWakeup, ThreadHandle, ThreadWorkerCapability, WakeupReason,
};
use villagesql::{InValue, VdfReturn};

static USER_COUNT: AtomicI64 = AtomicI64::new(-1);

static SQL_QUERY: SqlQueryCapability = SqlQueryCapability::new();

fn worker(reason: WakeupReason, handle: &ThreadHandle) -> NextWakeup {
    if reason == WakeupReason::Periodic {
        if let Some(session) = SQL_QUERY.open(handle) {
            if let Some(mut result) = session.execute("SELECT COUNT(*) FROM mysql.user") {
                if !result.has_error() {
                    if let Some(n) = result.next_row().and_then(|row| row.get_int(0)) {
                        USER_COUNT.store(n, Ordering::Relaxed);
                    }
                }
            }
        }
    }
    NextWakeup::unchanged()
}

static WORKER: ThreadWorkerCapability =
    ThreadWorkerCapability::new(worker, "user_count", Duration::from_secs(5), None);

fn user_count_impl(_args: &[InValue]) -> VdfReturn {
    VdfReturn::int(USER_COUNT.load(Ordering::Relaxed))
}

villagesql::extension! {
    funcs: [
        villagesql::func!(user_count_impl, "user_count", [] -> villagesql::Type::Int),
    ],
    requires: [
        &WORKER,
        &SQL_QUERY,
    ]
}

SqlQueryCapability::open(handle) retorna None se a capability não foi populada (preview desligado ou não solicitada), se a ABI é antiga demais ou se o servidor não conseguiu abrir uma sessão — verifique isso antes de usar o resultado. Uma Session oferece duas maneiras de executar uma instrução:

execute(sql) armazena em buffer o conjunto de resultados completo e retorna um QueryResult. Chame next_row() repetidamente até que ela retorne None; cada Row lê colunas com get_int(i), get_str(i), get_real(i) ou get_bytes(i). get_bytes/get_str retornam None para NULL do SQL ou um índice fora do intervalo (e também para bytes que não são UTF-8, no caso de get_str); get_int/get_real analisam a coluna primeiro como texto, então também retornam None para texto que não pode ser analisado. O próprio execute retorna None apenas em falha de configuração (sem sessão, ou sem memória).
for_each(sql, |row: Row<'_>| { ... }) transmite as linhas para uma closure em vez de armazenar em buffer o conjunto de resultados completo. O QueryResult que ele retorna carrega apenas diagnósticos — sem linhas em buffer para iterar — e também retorna None em falha de configuração.

Verifique has_error() e error() (um Option<Diag> com errno, severity, sqlstate e message) em qualquer um dos resultados antes de confiar que uma instrução teve sucesso. warnings() retorna todos os avisos e notas anexados ao resultado. Uma Session e um QueryResult fecham, cada um, seu handle subjacente quando são descartados — não há um método de fechamento para você chamar.

Acesso ao Keyring

A capability keyring lê e escreve segredos armazenados no componente keyring do MySQL — chaves de API, chaves de criptografia, qualquer coisa que não deveria ficar em uma tabela. Um componente keyring (por exemplo, component_keyring_file) deve ser carregado na inicialização do servidor por meio de um manifesto de componente e seu arquivo de configuração, conforme descrito em Keyring Component Installation; INSTALL COMPONENT não o torna disponível. Sem um, toda leitura e escrita falha com KeyringError::NoComponent.

use std::ffi::CString;

use villagesql::preview::keyring::KeyringCapability;
use villagesql::{InValue, VdfReturn};

static KEYRING: KeyringCapability = KeyringCapability::new();

const MAX_SECRET_LEN: usize = 1024;

fn keyring_read_impl(args: &[InValue]) -> VdfReturn {
    let Some(&InValue::String(data_id)) = args.first() else {
        return VdfReturn::null();
    };
    let Ok(data_id) = CString::new(data_id) else {
        return VdfReturn::null();
    };

    let mut buf = [0u8; MAX_SECRET_LEN];
    match KEYRING.read(&data_id, None, &mut buf) {
        Ok(Some(n)) => match std::str::from_utf8(&buf[..n]) {
            Ok(s) => VdfReturn::string(s),
            Err(_) => VdfReturn::null(),
        },
        Ok(None) => VdfReturn::null(),
        Err(e) => VdfReturn::error(format!("keyring: {e}")),
    }
}

villagesql::extension! {
    funcs: [
        villagesql::func!(
            keyring_read_impl, "keyring_read",
            [villagesql::Type::String] -> villagesql::Type::String,
            buffer_size: MAX_SECRET_LEN
        ),
    ],
    requires: [
        &KEYRING,
    ]
}

read(data_id, auth_id, buf) preenche o buffer que você passa e retorna Ok(Some(n)) com o comprimento do segredo, ou Ok(None) quando não existe nenhum segredo sob data_id — um resultado normal, não um erro. write(data_id, auth_id, data) retorna Ok(()) em caso de sucesso. auth_id é o usuário proprietário; passe None para chaves internas não associadas a um usuário específico. Ambos retornam Err(KeyringError) em caso de falha: CapabilityUnavailable (a capability nunca foi conectada), NoComponent (nenhum componente keyring no servidor) ou Other. O keyring não tem uma sondagem de tamanho: um segredo maior que o buffer que você passa para read volta como Ok(None), indistinguível de uma chave inexistente. Dimensione seu buffer para o maior segredo que você espera armazenar.

Próximos Passos

Capabilities Preview (C++)

O índice completo de capabilities, o nível Preview e as capabilities exclusivas do C++: auth, mysql_services, session_var, statement_event, as capabilities de índice personalizado e armazenamento de coluna.

Referência da API Rust

InValue, VdfReturn, extension!, func! e custom_type! — todos os campos.

​Pré-requisitos

​O Que o SDK Rust Envolve

​Padrão de Registro

​Variáveis de Status

​Variáveis de Sistema

​Reagindo a Mudanças

​Lendo e Escrevendo a partir do Código da Extensão

​Thread de Trabalho

​Wakeups

​Consulta SQL

​Acesso ao Keyring

​Próximos Passos

Capabilities Preview (C++)

Referência da API Rust

Pré-requisitos

O Que o SDK Rust Envolve

Padrão de Registro

Variáveis de Status

Variáveis de Sistema

Reagindo a Mudanças

Lendo e Escrevendo a partir do Código da Extensão

Thread de Trabalho

Wakeups

Consulta SQL

Acesso ao Keyring

Próximos Passos