• Desempenho em escala: O consumidor TypeScript processa eventos sequencialmente. Em escala de rede (~1.000 eventos/segundo, 18,5 bilhões de registros no total), um backfill completo a ~90 registros/seg levaria 6,5 anos. O Wintermute visa 10.000+ registros/seg com processamento paralelo de filas.
• Arquitetura de backfill: O Wintermute separa a indexação ao vivo do backfill em filas independentes (firehose_live, firehose_backfill, repo_backfill, labels). Eventos ao vivo nunca são bloqueados pelo trabalho de backfill.
• Ferramentas operacionais: O Wintermute inclui utilitários para indexação direta de contas específicas, importação em massa do diretório PLC, reprodução de streams de labels, reparo de referências de blobs e gerenciamento de filas – tudo necessário ao inicializar uma AppView do zero.

O dataplane e a appview deste repositório ainda funcionam como estão. Eles leem do banco de dados PostgreSQL que o wintermute escreve. Apenas não iniciamos a assinatura de firehose embutida.

Correções de desempenho e operacionais

Estas são amplamente úteis para qualquer pessoa que esteja auto-hospedando uma AppView em escala.

Otimização de consulta LATERAL JOIN (packages/bsky/src/data-plane/server/routes/feeds.ts)

• getTimeline e getListFeed foram reescritos com LATERAL JOINs do PostgreSQL para forçar o uso de índice por usuário em vez de varreduras completas de tabela. Melhoria significativa para usuários que seguem milhares de contas.

Camada de cache Redis (packages/bsky/src/data-plane/server/cache/)

• Perfis de atores (TTL de 60s), registros (5m), contagens de interação (30s), metadados de postagens (5m)
• Reduz a carga do banco de dados sob tráfego de produção
• Problema conhecido: O cache de atores tem um bug de serialização de timestamp protobuf onde objetos Timestamp perdem seu método .toDate() após ida e volta JSON pelo Redis, causando hidratação incompleta de perfil em acertos de cache. Atualmente executamos com o cache Redis desabilitado. A correção é serializar timestamps como strings ISO na escrita do cache e reconstruir na leitura.

Aplicação no lado do servidor das preferências de notificação (packages/bsky/src/api/app/bsky/notification/listNotifications.ts)

• Quando o cliente não especifica reasons, o servidor aplica as preferências de notificação salvas do usuário. Sem isso, as preferências são aplicadas apenas no lado do cliente e não têm efeito.

Correção de chave de assinatura obsoleta no verificador de autenticação (packages/bsky/src/auth-verifier.ts)

• Na repetição de verificação JWT (forceRefresh), ignora o cache de identidade em memória do dataplane e resolve o documento DID diretamente do diretório PLC. Corrige falhas de autenticação após migração de conta onde a chave de assinatura é rotacionada, mas o cache mantém a chave antiga.

Sanitização JSON (packages/bsky/src/data-plane/server/routes/records.ts)

• Remove bytes nulos (\u0000) e caracteres de controle dos registros armazenados antes da análise JSON. Estes são válidos de acordo com RFC 8259, mas rejeitados pelo JSON.parse() do Node.js, causando falhas silenciosas de análise rowToRecord no dataplane que se manifestam como postagens ausentes.

Postagens da comunidade (específicas do Blacksky)

Infraestrutura para postagens privadas de comunidade que residem na AppView em vez de PDSes individuais. Específico de como o Blacksky funciona, mas pode servir como referência para outras comunidades.

• Espaço de nomes de léxico personalizado community.blacksky.feed.* com endpoints para submit, get, delete, timeline e visualizações de thread
• Tabela separada community_post (migração: 20260202T120000000Z-add-community-post.ts)
• Controle de adesão (membership) na camada de dataplane e API
• Integração com getPostThreadV2 para threads mistas de postagens padrão/comunitárias
• Requer um banco de dados de adesão separado (BLACKSKY_MEMBERSHIP_DB_URL)

Arquitetura

Visão geral dos componentes

rsky-wintermute em detalhe

Wintermute é um serviço monolítico em Rust com quatro caminhos de processamento paralelo:

• Ingester: Conecta-se ao firehose bsky.network via WebSocket, escreve eventos em filas Fjall (armazenamento chave-valor incorporado)
• Indexador: Lê das filas, analisa registros, escreve no PostgreSQL com ON CONFLICT para idempotência
• Backfiller: Busca arquivos CAR completos de repositórios dos PDSes, desempacota registros na fila de backfill
• Indexador de labels: Assina streams WebSocket de labelers, processa eventos de criação/negação de labels

Ferramentas CLI adicionais incluídas no repositório rsky:

• queue_backfill -- enfileira DIDs para backfill a partir de CSV, descoberta de PDS ou listas diretas de DIDs
• direct_index -- busca e indexa repositórios específicos ignorando filas (útil para corrigir contas individuais)
• label_sync -- reproduz streams de labels a partir do cursor 0 para recuperar negações perdidas
• plc_import -- importa em massa mapeamentos handle/DID do diretório PLC
• palomar-sync -- sincroniza contagens de seguidores e PageRank para o OpenSearch

rsky-video

Serviço de upload de vídeo para usuários cujo PDS não suporta o video.bsky.app do Bluesky. Usa seu próprio DID (did:web:video.blacksky.community) para autenticar-se nos PDSes do usuário via JWTs de autenticação de serviço. Fluxo:

1. Cliente obtém token de autenticação de serviço do PDS (audiência: DID do serviço de vídeo)
2. Cliente envia bytes de vídeo para rsky-video
3. rsky-video gera um CID, envia o blob para o PDS do usuário
4. Vídeo encaminhado para Bunny Stream CDN para transcodificação
5. Na conclusão, o cliente cria a postagem referenciando o blob – o PDS valida que o blob existe

Tratamento de labels

Labels de moderação vêm de serviços labeler (por exemplo, Ozone do Bluesky) via assinatura WebSocket. O ingester do Wintermute processa labels em uma fila dedicada label_live (baixo volume, separada do firehose principal). A ferramenta label_sync pode reproduzir o stream completo de um labeler para recuperar negações perdidas (remoções de labels) sem reinserir labels.

Configuração

Pré-requisitos

• Node.js 18+ e pnpm (para construir o dataplane e a appview)
• PostgreSQL 17 com o esquema bsky
• Redis (opcional, para cache – veja o problema conhecido acima)
• rsky-wintermute consumindo o firehose e populando o banco de dados
• OpenSearch (se estiver executando a busca Palomar)

Banco de dados

O esquema bsky é criado pelas migrações do dataplane. Na primeira execução, o dataplane aplicará todas as migrações automaticamente. A única migração específica do Blacksky é 20260202T120000000Z-add-community-post.ts (tabela de postagens da comunidade). Se você não precisar de postagens da comunidade, pode removê-la.

O rsky-wintermute escreve no mesmo esquema. Todas as suas instruções INSERT usam ON CONFLICT, então é seguro executar wintermute e as migrações do dataplane em qualquer ordem.

Build

Executar o Dataplane

Executar a AppView

Operando em escala

Cronograma de backfill

Um backfill de rede completa (todos ~42M de usuários, ~18,5B de registros) leva semanas mesmo com o processamento paralelo do wintermute. Espere:

• Indexação ao vivo: Mantém-se em tempo real desde o primeiro dia (~1.000 eventos/seg)
• Backfill completo: 2-4 semanas a 10.000 registros/seg, dependendo da responsividade dos PDS e das condições de rede
• Backfill parcial: Horas a dias para um subconjunto de usuários (ex.: apenas membros da comunidade)

Durante o backfill, a AppView é funcional, mas mostrará dados incompletos para usuários que ainda não foram backfilados. Eventos ao vivo são indexados imediatamente, independentemente do progresso do backfill.

Problemas que resolvemos no caminho

Estes são problemas que encontramos ao inicializar uma AppView de rede completa. Se você estiver fazendo o mesmo, provavelmente encontrará alguns deles:

Corrupção de JSON no formato de texto COPY: O protocolo de texto COPY do PostgreSQL trata a barra invertida como caractere de escape. Se seu carregador em massa não escapar barras invertidas em strings JSON, \" se torna " e você obtém registros silenciosamente corrompidos. A coluna record.json é do tipo text (não jsonb), então o PostgreSQL não pegará isso. Encontramos ~66.000 registros corrompidos e tivemos que repará-los buscando novamente da API pública.

Bytes nulos em JSON: Alguns registros do AT Protocol contêm \u0000 (byte nulo), que é JSON válido de acordo com RFC 8259, mas rejeitado pelo JSON.parse() do Node.js. O dataplane retorna silenciosamente nulo para esses registros. Remova bytes nulos antes de escrever no banco de dados.

Sensibilidade ao formato de timestamp: O dataplane espera timestamps com precisão de milissegundos e sufixo Z (2026-01-12T19:45:23.307Z). Precisão de nanossegundos ou formato de fuso horário (+00:00) causa problemas sutis de ordenação e comparação.

Inchaço da tabela de notificações: Sem uma restrição única em (did, recordUri, reason), a tabela de notificações cresce ilimitadamente com duplicatas. A nossa chegou a 1,3 bilhão de linhas (663 GB) antes de percebermos. Adicionar ON CONFLICT DO NOTHING aos INSERTs só ajuda se o índice único existir primeiro, e criar o índice requer deduplicação dos dados existentes.

Tabelas de embed de postagens: As tabelas post_embed_image e post_embed_video não são populadas por padrão se seu indexador não as tratar. Sem elas, o filtro de mídia em getAuthorFeed não retorna nada. Elas precisam ser backfiladas separadamente.

Ordenação de negação de labels: Eventos de negação (remoção) de labels referenciam o label original por origem, URI e valor. Se as negações chegarem antes do label original (comum durante backfill), elas são silenciosamente descartadas. A ferramenta label_sync reproduz o stream completo para capturar essas.

Envenenamento da fila Fjall: O banco de dados Fjall incorporado (usado para as filas do wintermute) pode entrar em estado "envenenado" após falhas, bloqueando todas as operações de fila. A correção é excluir o diretório do banco de dados da fila e reiniciar – o wintermute recuperará a partir do cursor do relay (relays mantêm ~72 horas de histórico).

Inicialização do provedor TLS: O rustls requer a instalação explícita de um provedor criptográfico antes de qualquer conexão TLS. Sem rustls::crypto::aws_lc_rs::default_provider().install_default() na inicialização, a primeira conexão WebSocket com o firehose causará pânico.

Rotação de chave de assinatura após migração de conta: Quando os usuários migram entre PDSes, sua chave de assinatura muda. O dataplane armazena em cache dados de identidade com um staleTTL de 1 hora. Durante essa janela, a verificação JWT falha para usuários migrados. A correção é ignorar o cache na repetição da verificação e resolver diretamente do diretório PLC.

Requisitos de recursos

Baseado na execução de uma AppView de rede completa (todos ~42M de usuários, ~18,5B de registros).

Detalhamento de armazenamento (aproximado, rede completa):

Para uma comunidade menor executando uma AppView parcial (indexando apenas membros da comunidade), os requisitos escalam aproximadamente linearmente com o número de contas indexadas.

Sincronizando com upstream

Conflitos tipicamente ocorrerão em packages/bsky/src/data-plane/server/routes/ e packages/bsky/src/api/. Resolva mantendo nossas adições juntamente com as alterações upstream.

Licença

Mesma que upstream: licenciado duplamente sob MIT e Apache 2.0. Veja LICENSE-MIT.txt e LICENSE-APACHE.txt.