Tesseras

CLI Encontra a Rede: Comandos Publish, Fetch e Status

2026-02-15

Até agora o CLI operava isoladamente: criar uma tessera, verificar, exportar, listar o que você tem. Tudo ficava na sua máquina. Com esta atualização, o tes ganha três comandos que fazem a ponte entre o armazenamento local e a rede P2P — publish, fetch e status — comunicando-se com um tesd em execução através de um socket Unix.

O que foi construído

Crate tesseras-rpc — Um novo crate compartilhado entre CLI e daemon. Define o protocolo RPC usando serialização MessagePack com enquadramento prefixado por tamanho (cabeçalho big-endian de 4 bytes, máximo de 64 MiB). Três tipos de requisição (Publish, Fetch, Status) e suas respostas correspondentes. Um DaemonClient síncrono gerencia a conexão do socket Unix com timeouts configuráveis. O protocolo é deliberadamente simples — uma requisição, uma resposta, conexão fechada — para manter a implementação auditável.

tes publish <hash> — Publica uma tessera na rede. Aceita hashes completos ou prefixos curtos (ex.: tes publish a1b2), que são resolvidos no banco de dados local. O daemon lê todos os arquivos da tessera do armazenamento, empacota em um único buffer MessagePack e entrega ao motor de replicação. Tesseras pequenas (< 4 MB) são replicadas como um único fragmento; maiores passam por codificação de apagamento Reed-Solomon. A saída mostra o hash curto e a contagem de fragmentos:

Published tessera 9f2c4a1b (24 fragments created)
Distribution in progress — use `tes status 9f2c4a1b` to track.

tes fetch <hash> — Busca uma tessera da rede usando o hash de conteúdo completo. O daemon coleta fragmentos disponíveis localmente, reconstrói os dados originais via decodificação de apagamento se necessário, desempacota os arquivos e armazena no CAS (content-addressable store). Retorna o número de memórias e o tamanho total buscado.

tes status <hash> — Exibe a saúde de replicação de uma tessera. A saída mapeia diretamente o modelo interno de saúde do motor de replicação:

Listener RPC no daemon — O daemon agora escuta em um socket Unix (padrão: $XDG_RUNTIME_DIR/tesseras/daemon.sock) com permissões de diretório adequadas (0700), limpeza de sockets obsoletos e shutdown gracioso. Cada conexão é tratada em uma task Tokio — o listener converte o stream assíncrono para I/O síncrono para a camada de enquadramento, despacha para o handler RPC e escreve a resposta de volta.

Pack/unpack no tesseras-core — Um módulo pequeno que serializa uma lista de entradas de arquivo (caminho + dados) em um único buffer MessagePack e vice-versa. Esta é a ponte entre a estrutura de diretórios da tessera e os blobs opacos do motor de replicação.

Decisões de arquitetura

• Socket Unix ao invés de TCP: a comunicação RPC entre CLI e daemon acontece na mesma máquina. Sockets Unix são mais rápidos, não precisam de alocação de porta, e as permissões do sistema de arquivos fornecem controle de acesso sem TLS.
• MessagePack ao invés de JSON: o mesmo formato wire usado em todo o Tesseras. Compacto, sem schema, e já é uma dependência do workspace. Uma ida-e-volta típica de publish request/response ocupa menos de 200 bytes.
• Cliente síncrono, daemon assíncrono: o DaemonClient usa I/O bloqueante porque o CLI não precisa de concorrência — envia uma requisição e espera. O listener do daemon é assíncrono (Tokio) para tratar múltiplas conexões. A camada de enquadramento funciona com qualquer impl Read/Write, conectando ambos os mundos.
• Resolução de prefixo no lado do cliente: publish e status resolvem prefixos curtos localmente antes de enviar o hash completo ao daemon. Isso mantém o daemon stateless — ele não precisa acessar o banco de dados do CLI.
• Alinhamento do diretório de dados padrão: o padrão do CLI mudou de ~/.tesseras para ~/.local/share/tesseras (via dirs::data_dir()) para coincidir com o daemon. Um aviso de migração é exibido quando dados no caminho antigo são detectados.

Próximos passos

• Contagem de peers no DHT: o comando status atualmente reporta 0 peers — conectar a contagem real do DHT é o próximo passo
• tes show: exibir o conteúdo de uma tessera (memórias, metadados) sem exportar
• Fetch com streaming: para tesseras grandes, transmitir fragmentos conforme chegam ao invés de esperar por todos