Blacksky AppView

Questa è la fork di Blacksky dell'implementazione di riferimento del AT Protocol di Bluesky Social PBC. Alimenta l'AppView su api.blacksky.community.

Pubbliciamo questo codice per trasparenza e affinché altre comunità possano beneficiare del lavoro. Questo repository non accetta contributi, issue o PR. Se desideri l'implementazione atproto canonica, utilizza bluesky-social/atproto.

Cosa c'è di diverso

Tutte le modifiche sono in packages/bsky (logica dell'AppView), services/bsky (configurazione runtime) e una migrazione personalizzata. Tutto il resto è upstream.

Perché non il consumatore di firehose integrato?

Il dataplane upstream include un consumatore di firehose TypeScript (subscription.ts) che indicizza gli eventi direttamente. Lo abbiamo sostituito con rsky-wintermute, un indicizzatore Rust, per diverse ragioni:

• Prestazioni su larga scala: Il consumatore TypeScript elabora gli eventi in sequenza. Alla scala della rete (~1000 eventi/secondo, 18,5 miliardi di record totali), un backfill completo a ~90 record/sec richiederebbe 6,5 anni. Wintermute punta a 10.000+ record/sec con elaborazione parallela delle code.
• Architettura del backfill: Wintermute separa l'indicizzazione live dal backfill in code indipendenti (firehose_live, firehose_backfill, repo_backfill, labels). Gli eventi live non vengono mai bloccati dal lavoro di backfill.
• Strumenti operativi: Wintermute include utilità per l'indicizzazione diretta di account specifici, importazione bulk della directory PLC, replay del flusso di etichette, riparazione dei riferimenti blob e gestione delle code – tutto necessario quando si avvia un AppView da zero.

Il dataplane e l'appview di questo repository funzionano ancora così come sono. Leggono dal database PostgreSQL che wintermute scrive. Semplicemente non avviamo la sottoscrizione al firehose integrata.

Ottimizzazioni delle prestazioni e operative

Queste sono ampiamente utili per chiunque ospiti un AppView su larga scala.

Ottimizzazione delle query LATERAL JOIN (packages/bsky/src/data-plane/server/routes/feeds.ts)

• getTimeline e getListFeed riscritti con LATERAL JOIN di PostgreSQL per forzare l'utilizzo degli indici per utente invece di scansioni complete delle tabelle. Miglioramento significativo per utenti che seguono migliaia di account.

Livello di cache Redis (packages/bsky/src/data-plane/server/cache/)

• Profili attori (TTL 60s), record (5m), conteggi interazioni (30s), metadati post (5m)
• Riduce il carico del database sotto traffico di produzione
• Problema noto: La cache degli attori ha un bug di serializzazione dei timestamp protobuf dove gli oggetti Timestamp perdono il metodo .toDate() dopo il round-trip JSON attraverso Redis, causando un'idratazione incompleta del profilo in caso di cache hit. Attualmente eseguiamo con la cache Redis disabilitata. La soluzione è serializzare i timestamp come stringhe ISO durante la scrittura nella cache e ricostruirli in fase di lettura.

Applicazione lato server delle preferenze di notifica (packages/bsky/src/api/app/bsky/notification/listNotifications.ts)

• Quando il client non specifica reasons, il server applica le preferenze di notifica salvate dell'utente. Senza questa funzione, le preferenze vengono applicate solo lato client e non hanno effetto.

Risoluzione della chiave di firma scaduta nel verificatore di autenticazione (packages/bsky/src/auth-verifier.ts)

• Al retry della verifica JWT (forceRefresh, bypassa la cache di identità in memoria del dataplane e risolve il documento DID direttamente dalla directory PLC. Risolve errori di autenticazione dopo la migrazione dell'account quando la chiave di firma viene ruotata ma la cache mantiene la vecchia chiave.

Sanitizzazione JSON (packages/bsky/src/data-plane/server/routes/records.ts)

• Rimuove i byte nulli (\u0000) e i caratteri di controllo dai record memorizzati prima del parsing JSON. Questi sono validi secondo RFC 8259 ma vengono rifiutati da JSON.parse() di Node.js, causando errori silenziosi di parsing rowToRecord nel dataplane che si manifestano come post mancanti.

Post della comunità (specifici di Blacksky)

Infrastruttura per post privati di comunità che risiedono sull'AppView anziché su singoli PDS. Specifica per il funzionamento di Blacksky, ma potrebbe essere di riferimento per altre comunità.

• Namespace del lessico personalizzato community.blacksky.feed.* con endpoint per submit, get, delete, timeline e visualizzazioni thread
• Tabella community_post separata (migrazione: 20260202T120000000Z-add-community-post.ts)
• Controllo dell'appartenenza a livello di dataplane e API
• Integrazione con getPostThreadV2 per thread misti di post standard e comunitari
• Richiede un database di appartenenza separato (BLACKSKY_MEMBERSHIP_DB_URL)

Architettura

Bluesky Relay (bsky.network)
     |
     v
rsky-wintermute -----> PostgreSQL 17 <----- Palomar
  (Indicizzatore Rust)       |                (Ricerca Go)
  - consumatore firehose     |                     |
  - backfiller               |                     v
  - indicizzatore etichette  |               OpenSearch
  - indicizzatore diretto    |
                            v
                    bsky-dataplane (gRPC :2585) <--- Redis (opzionale)
                            |
                            v
                    bsky-appview (HTTP :2584)
                            |
                            v
                    Reverse proxy (Caddy/nginx)

Panoramica dei componenti

rsky-wintermute in dettaglio

Wintermute è un servizio Rust monolitico con quattro percorsi di elaborazione paralleli:

• Ingester: Si connette al firehose di bsky.network tramite WebSocket, scrive eventi nelle code Fjall (key-value store embedded)
• Indexer: Legge dalle code, analizza i record, scrive in PostgreSQL con ON CONFLICT per idempotenza
• Backfiller: Recupera i file CAR completi del repository dai PDS, decomprime i record nella coda di backfill
• Indicizzatore etichette: Si sottoscrive ai flussi WebSocket dei labeler, elabora eventi di creazione/negazione etichette

Strumenti CLI aggiuntivi inclusi nel repository rsky:

• queue_backfill — accoda DID per backfill da CSV, scoperta PDS o elenchi diretti di DID
• direct_index — recupera e indicizza repository specifici bypassando le code (utile per correggere account individuali)
• label_sync — riproduce il flusso delle etichette dal cursore 0 per recuperare negazioni mancate
• plc_import — importa bulk le mappature handle/DID dalla directory PLC
• palomar-sync — sincronizza i conteggi follower e i punteggi PageRank in OpenSearch

rsky-video

Servizio di upload video per utenti il cui PDS non supporta video.bsky.app di Bluesky. Utilizza un proprio DID (did:web:video.blacksky.community) per autenticarsi ai PDS degli utenti tramite JWT di autenticazione del servizio. Flusso:

1. Il client ottiene un token di autenticazione del servizio dal PDS (audience: DID del servizio video)
2. Il client carica i byte del video su rsky-video
3. rsky-video genera un CID, carica il blob nel PDS dell'utente
4. Il video viene inoltrato a Bunny Stream CDN per la transcodifica
5. Al completamento, il client crea il post riferendosi al blob – il PDS verifica che il blob esista

Gestione delle etichette

Le etichette di moderazione provengono dai servizi labeler (es. Ozone di Bluesky) tramite sottoscrizione WebSocket. L'ingester di Wintermute elabora le etichette in una coda dedicata label_live (basso volume, separata dal firehose principale). Lo strumento label_sync può riprodurre il flusso completo di un labeler per recuperare le negazioni mancate (rimozione etichette) senza reinserire le etichette.

Configurazione

Prerequisiti

• Node.js 18+ e pnpm (per compilare dataplane e appview)
• PostgreSQL 17 con lo schema bsky
• Redis (opzionale, per la cache – vedi problema noto sopra)
• rsky-wintermute che consuma il firehose e popola il database
• OpenSearch (se si esegue la ricerca Palomar)

Database

Lo schema bsky viene creato dalle migrazioni del dataplane. Al primo avvio, il dataplane applica automaticamente tutte le migrazioni. L'unica migrazione specifica di Blacksky è 20260202T120000000Z-add-community-post.ts (tabella dei post della comunità). Se non hai bisogno dei post della comunità, puoi rimuoverla.

rsky-wintermute scrive su questo stesso schema. Tutte le sue istruzioni INSERT utilizzano ON CONFLICT, quindi è sicuro eseguire wintermute e le migrazioni del dataplane in qualsiasi ordine.

Build

pnpm install
pnpm build

Eseguire il Dataplane

node services/bsky/dataplane.js

Eseguire l'AppView

node services/bsky/api.js

Operatività su larga scala

Tempistiche del backfill

Un backfill completo della rete (tutti ~42M utenti, ~18,5 miliardi di record) richiede settimane anche con l'elaborazione parallela di wintermute. Prevedi:

• Indicizzazione live: Tiene il passo in tempo reale dal primo giorno (~1000 eventi/sec)
• Backfill completo: 2-4 settimane a 10.000 record/sec a seconda della reattività del PDS e delle condizioni di rete
• Backfill parziale: Da ore a giorni per un sottoinsieme di utenti (es. solo membri della comunità)

Durante il backfill, l'AppView è funzionale ma mostrerà dati incompleti per gli utenti non ancora sottoposti a backfill. Gli eventi live vengono indicizzati immediatamente indipendentemente dall'avanzamento del backfill.

Problemi che abbiamo risolto per arrivare a questo punto

Questi sono problemi che abbiamo incontrato avviando un AppView di rete completa. Se stai facendo lo stesso, probabilmente ne incontrerai alcuni:

Corruzione JSON nel formato di testo COPY: Il protocollo di testo COPY di PostgreSQL tratta il backslash come carattere di escape. Se il tuo caricatore bulk non escape i backslash nelle stringhe JSON, \" diventa " e ottieni record corrotti silenziosamente. La colonna record.json è di tipo text (non jsonb), quindi PostgreSQL non lo rileverà. Abbiamo trovato ~66.000 record corrotti e abbiamo dovuto ripararli recuperandoli dall'API pubblica.

Byte nulli nel JSON: Alcuni record del AT Protocol contengono \u0000 (byte nullo), che è JSON valido secondo RFC 8259 ma rifiutato da JSON.parse() di Node.js. Il dataplane restituisce silenziosamente null per questi record. Rimuovi i byte nulli prima di scrivere nel database.

Sensibilità al formato del timestamp: Il dataplane si aspetta timestamp con precisione al millisecondo e suffisso Z (2026-01-12T19:45:23.307Z). La precisione al nanosecondo o il formato con offset fuso orario (+00:00) causano sottili problemi di ordinamento e confronto.

Gonfiamento della tabella delle notifiche: Senza un vincolo univoco su (did, recordUri, reason), la tabella delle notifiche cresce senza limiti con duplicati. La nostra ha raggiunto 1,3 miliardi di righe (663 GB) prima che lo scoprissimo. Aggiungere ON CONFLICT DO NOTHING agli INSERT aiuta solo se l'indice univoco esiste già, e creare l'indice richiede la deduplicazione dei dati esistenti.

Tabelle degli embed dei post: Le tabelle post_embed_image e post_embed_video non vengono popolate di default se il tuo indicizzatore non le gestisce. Senza di esse, il filtro multimediale su getAuthorFeed non restituisce nulla. Queste devono essere sottoposte a backfill separatamente.

Ordinamento delle negazioni delle etichette: La negazione (rimozione) di un'etichetta fa riferimento all'etichetta originale per sorgente, URI e valore. Se le negazioni arrivano prima dell'etichetta originale (comune durante il backfill), vengono scartate silenziosamente. Lo strumento label_sync riproduce il flusso completo per recuperare queste situazioni.

Avvelenamento della coda Fjall: Il database embedded Fjall (usato per le code di wintermute) può entrare in uno stato "avvelenato" dopo crash, bloccando tutte le operazioni sulle code. La soluzione è eliminare la directory del database della coda e riavviare – wintermute recupererà dal cursore del relay (i relay mantengono circa 72 ore di storia).

Inizializzazione del provider TLS: rustls di Rust richiede l'installazione esplicita di un provider crittografico prima di qualsiasi connessione TLS. Senza rustls::crypto::aws_lc_rs::default_provider().install_default() all'avvio, la prima connessione WebSocket al firehose fallisce con panico.

Rotazione della chiave di firma dopo la migrazione dell'account: Quando gli utenti migrano tra PDS, la loro chiave di firma cambia. Il dataplane memorizza nella cache i dati di identità con uno staleTTL di 1 ora. Durante questa finestra, la verifica JWT fallisce per gli utenti migrati. La soluzione è bypassare la cache durante i retry di verifica e risolvere direttamente dalla directory PLC.

Requisiti di risorse

Basati sull'esecuzione di un AppView di rete completa (tutti ~42M utenti, ~18,5 miliardi di record).

Ripartizione dell'archiviazione (approssimativo, rete completa):

Per una comunità più piccola che esegue un AppView parziale (indicizzando solo i membri della comunità), i requisiti scalano approssimativamente in modo lineare con il numero di account indicizzati.

Sincronizzazione con l'upstream

git remote add upstream https://github.com/bluesky-social/atproto.git
git fetch upstream
git merge upstream/main

I conflitti saranno tipicamente in packages/bsky/src/data-plane/server/routes/ e packages/bsky/src/api/. Risolvi mantenendo le nostre aggiunte insieme alle modifiche upstream.

Licenza

Stessa dell'upstream: dual-licensed sotto MIT e Apache 2.0. Vedi LICENSE-MIT.txt e LICENSE-APACHE.txt.