Capabilities Preview em Rust

O SDK Rust está em alpha — espere mudanças incompatíveis de API entre versões. As capabilities Preview são adicionalmente instáveis do lado do servidor: suas ABIs podem mudar entre versões do servidor. 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 quatro delas: variáveis de status, variáveis de sistema, threads de trabalho em segundo plano 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::keyring`	`villagesql::preview::keyring`	`vsql_keyring`

As demais capabilities Preview — auth, mysql_services, sql_query, statement_event 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 mostrado nos metadados de SHOW VARIABLES, 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. O parâmetro ThreadHandle está reservado para abrir sessões SQL a partir do worker assim que a capability sql_query for portada para o Rust; ele ainda não tem métodos.

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 estar instalado no servidor; 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) | Err(_) => VdfReturn::null(),
    }
}

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, sql_query, statement_event e armazenamento de coluna.

Referência da API Rust

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

Getting Started

Server Development

Extensions

Using Extensions

Creating Extensions

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

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

​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

Acesso ao Keyring

Próximos Passos