Documentation de l’outil

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 champ did qui 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 est https://bsky.app/profile/<créateur>/feed/<rkey>.
  • Le générateur de flux, un serveur identifié par ce DID (un did:web ou un did:plc). Son document DID contient un service dont l’id est #bsky_fg et le type BskyFeedGenerator, et dont le serviceEndpoint est 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.

json
{
  "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 :

json
{
  "@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 :

  1. DID du service. Le did de l’enregistrement doit être un did:web sur un nom d’hôte seul (sans port ni chemin) ou un did:plc. Sinon, publiez à nouveau l’enregistrement avec le bon DID.
  2. Service #bsky_fg. Le document DID doit exister, être un JSON valide dont l’id est le DID, et contenir un service #bsky_fg de type BskyFeedGenerator avec un point d’accès https.
  3. describeFeedGenerator. GET <point d’accès>/xrpc/app.bsky.feed.describeFeedGenerator doit répondre 200 avec un did égal au DID du service et une liste feeds.
  4. 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.
  5. getFeedSkeleton. GET <point d’accès>/xrpc/app.bsky.feed.getFeedSkeleton?feed=<uri>&limit=1 doit répondre 200 avec un tableau feed. 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 de https://, 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 feed d’é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:web qui a changé d’hôte doit mettre à jour son document DID ; un générateur did:plc a 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.

Inspecteur de flux

Prévisualisez un flux personnalisé et découvrez pourquoi il n’affiche rien.