Comment fonctionne un flux personnalisé Bluesky, et comment le déboguer
Les éléments d’un flux personnalisé Bluesky : l’enregistrement, le DID du service, le service #bsky_fg, flux squelette et hydraté, et comment corriger chaque test.
Les éléments d’un flux personnalisé
Un flux personnalisé a deux moitiés, qui vivent à deux endroits différents :
- L’enregistrement,
app.bsky.feed.generator, sur le compte de son créateur : son nom, sa description, son avatar, et un champdidqui désigne le générateur de flux qui le sert. Son adresse est l’URI AT du flux,at://<créateur>/app.bsky.feed.generator/<rkey>, et son lien bsky.app esthttps://bsky.app/profile/<créateur>/feed/<rkey>. - Le générateur de flux, un serveur identifié par ce DID (un
did:webou undid:plc). Son document DID contient un service dont l’id est#bsky_fget le typeBskyFeedGenerator, et dont leserviceEndpointest l’adresse https du serveur.
Un même générateur peut servir plusieurs flux, chacun à partir de son propre enregistrement.
Flux squelette et flux hydraté
Quand quelqu’un ouvre un flux, l’application demande app.bsky.feed.getFeed à l’AppView de Bluesky. L’AppView lit l’enregistrement, résout le DID du générateur, trouve son point d’accès #bsky_fg et y appelle app.bsky.feed.getFeedSkeleton. Le générateur répond par un squelette : une liste d’URI de posts, rien d’autre.
{
"feed": [
{ "post": "at://did:plc:abc/app.bsky.feed.post/3l2k7yqzx2c2a" }
],
"cursor": "1731567000000"
}L’AppView l’hydrate ensuite : elle récupère chaque post, son auteur et ses chiffres, applique les blocages, les mises en sourdine et les étiquettes, et renvoie des posts complets. Le générateur ne sait pas qui lit le flux, sauf si la personne est connectée : la requête porte alors un jeton qui la désigne.
L’AppView suit aussi chaque générateur : isOnline indique qu’elle l’a joint récemment, isValid que ses réponses avaient la bonne forme. L’inspecteur de flux montre les deux.
Le document DID
Pour un did:web, le document est servi à https://<hôte>/.well-known/did.json ; pour un did:plc, c’est l’annuaire PLC qui le garde. Un document minimal :
{
"@context": ["https://www.w3.org/ns/did/v1"],
"id": "did:web:feed.example.com",
"service": [
{
"id": "#bsky_fg",
"type": "BskyFeedGenerator",
"serviceEndpoint": "https://feed.example.com"
}
]
}Le générateur doit aussi répondre à app.bsky.feed.describeFeedGenerator avec le même DID et l’URI AT de chaque flux qu’il sert.
Le bilan de santé, étape par étape
Le bilan de santé de l’inspecteur ne se lance qu’à votre demande, et suit le même chemin que l’AppView :
- DID du service. Le
didde l’enregistrement doit être undid:websur un nom d’hôte seul (sans port ni chemin) ou undid:plc. Sinon, publiez à nouveau l’enregistrement avec le bon DID. - Service
#bsky_fg. Le document DID doit exister, être un JSON valide dont l’idest le DID, et contenir un service#bsky_fgde typeBskyFeedGeneratoravec un point d’accès https. describeFeedGenerator.GET <point d’accès>/xrpc/app.bsky.feed.describeFeedGeneratordoit répondre 200 avec undidégal au DID du service et une listefeeds.- Le flux est listé. L’URI AT du flux devrait figurer dans cette liste
feeds. Un flux absent donne un avertissement : certains générateurs servent des flux qu’ils ne listent pas. getFeedSkeleton.GET <point d’accès>/xrpc/app.bsky.feed.getFeedSkeleton?feed=<uri>&limit=1doit répondre 200 avec un tableaufeed. Un 401 signifie que le flux demande une personne connectée : il fonctionne dans l’application, mais pas pour les lecteurs non connectés, ni dans l’aperçu de l’inspecteur.
Chaque requête a 4 secondes et 64 Ko, et son temps est affiché. Les requêtes passent par nos contrôles de sécurité : https sur le port 443 uniquement, et jamais vers une adresse privée ou locale. Un générateur sur un réseau domestique ou derrière un tunnel vers localhost échoue donc au bilan, même quand l’application le joint par une adresse publique.
Corrections courantes
- Hors ligne, mais le serveur fonctionne : vérifiez le point d’accès dans le document DID (une faute de frappe,
http://au lieu dehttps://, un chemin en trop) et que le certificat est valide pour cet hôte. - Valide vaut false : le squelette doit être un objet avec un tableau
feedd’éléments{ "post": "<uri at>" }; des champs en plus ne gênent pas, d’autres formes si. - L’aperçu est vide mais pas le squelette : les posts renvoyés sont peut-être supprimés, de comptes bloqués ou retirés, ou d’auteurs qui ne partagent qu’avec les personnes connectées.
- Ça marchait, puis plus rien : un générateur
did:webqui a changé d’hôte doit mettre à jour son document DID ; un générateurdid:plca besoin d’une opération PLC.
Le tutoriel des flux personnalisés du protocole AT et le kit de démarrage de Bluesky expliquent comment en construire un. Bluesky.bot fait tourner son propre générateur pour le flux des bots ; son document DID est à /.well-known/did.json.