Contrato do SDK Rust
nelcota-client 0.1.x suporta o servidor Nelcota 0.3.0 ou posterior; a versão 0.1.2 é verificada contra o servidor 0.4.0. A tag v0.2.0 publicada é uma base legada sem as rotas OAuth e os geradores mais recentes; veja a matriz de compatibilidade no README. As versões do pacote e do servidor são independentes. Tokio nativo em Linux, Windows e macOS é o alvo suportado; interfaces bloqueantes e WASM não fazem parte da versão 0.1.
| Módulo | Contrato HTTP |
|---|---|
| Leitura REST | GET/HEAD /rest/v1/{table}; select/filter/order/paging, Prefer count, Content-Range |
| Escrita REST | POST/PATCH/DELETE /rest/v1/{table}; minimal/representation, resolução de upsert/on_conflict |
| RPC | POST /rest/v1/rpc/{name} com argumentos JSON nomeados |
| Autenticação | POST signup; concessões de token password/refresh_token/pkce; GET user; POST logout |
| POST recover/magiclink/resend/verify | |
| OAuth | URL de autorização com PKCE S256; troca de código de uso único |
| Objetos | POST/PUT/GET/DELETE /storage/v1/object/{bucket}/{path}, bytes brutos |
| Compartilhamento/listagem | POST object/list e object/sign; construção local de URL object/public |
| Buckets | GET/POST bucket; GET/PUT/DELETE bucket/{id} |
A gramática das consultas e os recursos do servidor correspondem ao contrato TypeScript. As respostas se tornam valores Result em Rust; corpos vazios se tornam JSON null (decodifique para unit ou um Option adequado). Response<T> contém status, contagem e cabeçalhos. Os métodos auxiliares de autenticação/armazenamento retornam o modelo decodificado ou um erro estruturado.
Corpos de erro HTTP maiores que 64 KiB são descartados; o status, um código de erro genérico e Retry-After continuam disponíveis. Respostas bem-sucedidas mantêm o contrato existente de leitura em memória ou streaming.
Um Client e seus clones compartilham a coordenação do ciclo de vida. Clones com tokens explícitos controlam apenas REST/armazenamento e get_user; os outros métodos de autenticação gerenciam a sessão de login compartilhada. As chamadas de renovação compartilham uma tarefa em segundo plano; cancelar ou descartar essas chamadas não deixa uma tarefa por chamada nem interrompe a rotação já aceita. As sessões padrão nunca persistem fora da memória. Armazenamentos compartilhados entre clientes/processos construídos de forma independente exigem coordenação própria.
A renovação sob demanda e em segundo plano limita a margem configurada à metade da validade do token. Sessões novas de curta duração e margens muito grandes não provocam uma rotação a cada requisição ou disparo do temporizador; a renovação explícita continua disponível.
Os modelos gerados fornecem estruturas serde, sem verificar consultas em strings durante a compilação. A ausência de colunas selecionadas obrigatórias causa falha na decodificação. A precisão numérica é preservada por arbitrary_precision; campos omitidos e null na escrita são diferentes.
Escritas REST e RPC rejeitam valores de ponto flutuante não finitos, inclusive em campos aninhados, antes do HTTP. Serde não deve transformar NaN ou infinito em JSON null silenciosamente. Valores null explícitos e campos omitidos mantêm sua semântica, e a serialização ocorre uma única vez sem adicionar dependências.
Verificações de aceitação: testes/doctests/exemplos do SDK, testes de contrato HTTP do servidor, snapshot do gerador Rust e testes de compilação/serialização dos modelos gerados, Clippy/rustfmt, documentação, verificação do pacote e teste básico com consumidor externo.
O pacote publicado 0.1.2 e o checkout atual compartilham o contrato HTTP principal. Mudanças em Unreleased, incluindo correção da margem de renovação, exigem novo build/pacote do cliente. As versões do servidor e SDK permanecem independentes.