Geyser gRPC - Boas práticas

Este guia apresenta os padrões essenciais para criar aplicações robustas e prontas para produção com o Geyser gRPC. O Solana Stream SDK oferece suporte ao Geyser gRPC.

Primeiros passos

Comece pelo simples: use primeiro assinaturas de slot para se familiarizar com o streaming antes de adicionar filtros complexos.
Use filtros com critério: assine apenas o que você precisa para reduzir banda/CPU.

rust

SubscribeRequestFilterTransactions {
    vote: Some(false),   // Exclude vote txs
    failed: Some(false), // Exclude failed txs
    ..Default::default()
}

SubscribeRequestFilterTransactions {
    vote: Some(false),   // Exclude vote txs
    failed: Some(false), // Exclude failed txs
    ..Default::default()
}

Gerenciamento de conexões

Reconexão automática: conte com problemas de rede e reconecte com backoff exponencial.
Tratamento de ping/pong: os servidores Yellowstone gRPC enviam ping. Responda sempre com pong, ou o servidor pode fechar a conexão (causa comum de desconexões após ~30s).

rust

if matches!(update.update_oneof, Some(UpdateOneof::Ping(_))) {
    subscribe_tx.send(SubscribeRequest {
        ping: Some(SubscribeRequestPing { id: 1 }),
        ..Default::default()
    }).await?;
}

if matches!(update.update_oneof, Some(UpdateOneof::Ping(_))) {
    subscribe_tx.send(SubscribeRequest {
        ping: Some(SubscribeRequestPing { id: 1 }),
        ..Default::default()
    }).await?;
}

Recuperação de lacunas: use from_slot após reconectar para evitar perda de dados (duplicatas são aceitáveis).

rust

subscribe_request.from_slot = if tracked_slot > 0 {
    Some(tracked_slot) // Optionally subtract a small buffer to dodge reorgs
} else {
    None
};

subscribe_request.from_slot = if tracked_slot > 0 {
    Some(tracked_slot) // Optionally subtract a small buffer to dodge reorgs
} else {
    None
};

Padrões de arquitetura

Separe a entrada e o processamento com canais, para desacoplar o IO de rede da lógica de negócio e adicionar backpressure.

rust

let (tx, rx) = mpsc::channel::<SubscribeUpdate>(10_000);
// ingress task reads stream and tx.send(...)
// processing task consumes rx and does business logic

let (tx, rx) = mpsc::channel::<SubscribeUpdate>(10_000);
// ingress task reads stream and tx.send(...)
// processing task consumes rx and does business logic

Use canais limitados: escolha a capacidade com base na velocidade de processamento e na tolerância à perda de dados (menor = menos memória e mais descartes; maior = mais memória e menos descartes).

Desempenho e resiliência

Monitore a latência de processamento e registre em log quando os limites forem ultrapassados.
Agrupe as gravações no banco de dados em lotes; faça o flush pelo tamanho do lote ou por intervalo.
Use IO assíncrono para chamadas externas; transfira o processamento pesado para tasks/threads de worker.
Reutilize as requisições de assinatura para reduzir alocações.

Tratamento de erros

Diferencie os tipos de erro (stream vs. processamento vs. canal).
Corrija uma requisição inválida antes de tentar de novo; use backoff exponencial que respeite a pausa apenas quando uma resposta pedir nova tentativa.
Registre em log/métricas as atualizações descartadas para acompanhar situações de consumidor lento.

Corrigir antes de tentar de novo e backoff que respeita a pausa

Guarde o primeiro erro gRPC antes que um loop de reconexão o substitua. Registre seu status e mensagem, além dos metadados presentes x-erpc-error-code, x-erpc-error-reason, x-erpc-doc-url, x-erpc-retry-after-seconds e x-erpc-retry-at. Um fechamento antecipado da conexão pode parecer um erro de transporte genérico e talvez não inclua todos os trailers.

Corrija uma requisição inválida, um formato de filtro rejeitado ou uma divergência no registro de IP antes de tentar de novo. Em uma pausa da ERPC, aguarde o prazo retornado; ele é mais específico que um backoff local. Use backoff exponencial limitado para falhas de disponibilidade e outras respostas que permitem nova tentativa. Não repita várias vezes uma requisição sem mudanças só porque ela retornou um status diferente de zero.

Uso de recursos e capacidade de processamento

As proteções Shared impedem que uma carga de trabalho consuma a capacidade de entrega de que outros clientes ERPC precisam. Um stream pode ficar lento por causa da largura de banda efetiva, da CPU, da memória, da fila do consumidor, das gravações no banco de dados ou de chamadas externas. Os recursos precisam ser suficientes para a carga; um receptor lento não indica sozinho qual parte está limitada.

Meça a taxa máxima de dados no consumidor. Converta MB/s em Mbps com MB/s × 8 e deixe margem acima do pico medido. Não há um mínimo fixo sem medição. Mantenha curto o trabalho de recepção, passe as atualizações para uma fila limitada e escale ou reduza a assinatura se o processamento não acompanhar. Uma fila limitada limita o uso de memória; ela não resolve um consumidor persistentemente lento.

Gerenciamento de dados

Trate duplicatas ao usar from_slot (cache com prazo de validade ou restrições no banco de dados).
Escolha o commitment conforme o caso de uso:
- processed: dashboards mais rápidos, pode haver rollback
- confirmed: bom padrão para a maioria dos apps/indexadores
- finalized: quando é necessária certeza absoluta

Assinaturas dinâmicas

Use o stream bidirecional para atualizar as assinaturas em tempo de execução (trocar filtros a quente, ampliar a cobertura) sem reconectar.

Checklist de produção

✅ Reconexão automática com backoff exponencial
✅ Recuperação de lacunas com from_slot
✅ Tratamento de ping/pong (evita desconexões de 30s)
✅ Entrada e processamento separados com canais limitados/backpressure
✅ Log de erros e métricas/alertas
✅ Acompanhamento da latência de processamento
✅ Tratamento de duplicatas e otimização de filtros
✅ Gravações em lote (se houver persistência)
✅ Desligamento controlado e health checks

Recursos adicionais

Solana Stream SDK (suporte ao Geyser gRPC): https://github.com/ValidatorsDAO/solana-stream