Cette page est une traduction automatique de la page en anglais, qui fait foi. Lire la page en anglais
Plugins
Un plugin est un programme ou un service distinct que vous exécutez, auquel le serveur confie une tâche précise à travers le réseau. Le serveur se contente de se connecter à une adresse : il ne démarre, n’arrête ni ne surveille le plugin. Exécutez-le comme sidecar, sous systemd, ou sur une autre machine.
Rien n’est délégué par défaut. Un serveur sans adresse de plugin n’ouvre aucune connexion et ne démarre aucun processus.
Du haut du schéma vers le bas :
- Le processus my, avec n’importe quel
role, effectue deux sortes d’appels vers un plugin.- Les ports qu’il confie : un plugin accomplit une tâche à la place d’un composant intégré, et chacun n’est actif que lorsqu’un paramètre nomme
plugin:translator(le paramètre d’instancetranslation_providers = plugin),billing(billing_sourcesinclutplugin),mailer(mail = plugin),media_image,media_videoetmedia_audio(media_image = pluginet ainsi de suite),key_manager(key_manager = plugin) etsearch(search = plugin). - Hooks de décision : un plugin répond à la question d’accepter ou non quelque chose, et il est interrogé sauf si le
mode du hook
hook_<hook>_modeestoff:inbound.statuspour les publications d’autres serveurs,inbound.followpour les abonnements venant d’autres serveurs,signup.checkpour les inscriptions,media.checkpour les envois,local.statuspour les publications des comptes locaux,inbound.actorpour les profils de comptes d’autres serveurs, etlocal.profilepour les modifications de profil des comptes locaux.
- Les ports qu’il confie : un plugin accomplit une tâche à la place d’un composant intégré, et chacun n’est actif que lorsqu’un paramètre nomme
- Le client de plugins effectue tous les appels. Chaque type a une destination,
plugin_<kind>_address, et un délai,plugin_<kind>_timeout, et exécute au plus 8 appels à la fois (2 pour chaque type de média). Il se connecte par un socket Unix,https://ou, pour certains types seulement,http://. - Vos plugins sont des programmes distincts que vous exécutez, comme sidecar, sous systemd ou sur une autre machine. Le serveur ne fait que s’y connecter.
- Quand un appel échoue ou expire (détails) :
billing,maileret les types de média : la tâche qui a fait l’appel s’exécute de nouveau plus tard.translator: le serveur interroge le prestataire suivant, et quand il n’en reste aucun, le lecteur voit que la traduction a échoué.key_manageréchoue en mode fermé : tout ce qui a besoin d’une clé échoue, et le serveur ne démarre pas sans le plugin.search: la tâche d’une écriture s’exécute de nouveau plus tard, et une recherche échoue, la personne voit donc que la recherche est indisponible.- Un hook de décision fait ce que dit
hook_<hook>_on_failure:pass,retryou, pour les inscriptions,require_approval.
Chaque type a sa propre destination, sous les paramètres plugin_<kind>_*. Un point dans le nom d’un type devient _ dans la
clé : inbound.status a donc plugin_inbound_status_address.
| Type | Ce qu’il transporte | TCP simple (http://) |
Protocole par défaut | Délai par défaut |
|---|---|---|---|---|
translator |
Le texte d’une publication qu’un lecteur a demandé à traduire | Refusé | json |
10 s |
search |
Le texte, l’auteur, la visibilité et la langue des publications public et local, ainsi que les requêtes des personnes connectées |
Refusé | json |
10 s |
billing |
Les coûts de l’instance | Autorisé | json |
2 min |
mailer |
Des adresses et des secrets comme les liens de confirmation | Refusé | json |
30 s |
media_image |
Les images envoyées, avec leurs métadonnées, qui peuvent contenir un lieu | Autorisé | proto |
4 min |
media_video |
Les vidéos envoyées, avec leurs métadonnées, qui peuvent contenir un lieu | Autorisé | proto |
4 min |
media_audio |
Les fichiers audio envoyés, avec leurs métadonnées | Autorisé | proto |
4 min |
key_manager |
Les clés de chiffrement des données en clair | Refusé | json |
5 s |
inbound.status |
Le texte des publications entrantes | Refusé | json |
3 s |
local.status |
Le texte des publications locales | Refusé | json |
1 s |
local.profile |
Le profil public des comptes locaux, sans les images | Autorisé | json |
1 s |
inbound.follow |
Les deux parties d’un abonnement | Autorisé | json |
3 s |
inbound.actor |
Les profils publics des comptes d’autres serveurs | Autorisé | json |
3 s |
signup.check |
Adresses e-mail et adresses IP | Refusé | json |
2 s |
media.check |
Une petite version traitée du média, jamais l’original | Autorisé | json |
10 s |
Les paramètres qui font utiliser une destination au serveur appartiennent à chaque fonctionnalité : les cinq derniers types du tableau sont les hooks de décision. Cette page couvre ce qu’ils partagent.
Le serveur envoie au plus la limite fixe d’un type par message et en lit au plus une autre. Un appel au-delà de la limite échoue, et la tâche qui l’a fait réessaie.
La destination
Section intitulée « La destination »Les paramètres n’existent que dans le fichier de configuration et l’environnement (référence de la configuration). Aucun paramètre d’instance, aucune page d’administration ni aucune API ne peut les afficher ni les modifier : un compte administrateur volé ne peut donc pas rediriger les publications ou les clés. Un changement prend effet au redémarrage.
plugin_<kind>_address a l’une de trois formes. Le serveur vérifie la forme au démarrage sans résoudre le nom, et
résout le nom à chaque connexion.
unix:///run/my/mailer.sock: un socket Unix.https://mailer.internal:8443: TLS sur TCP. Le serveur vérifie toujours le certificat, par rapport àplugin_<kind>_tls_ca_fileou aux racines du système, et aucun paramètre ne désactive cela.http://billing.internal:5000: TCP simple.
Authentification
Section intitulée « Authentification »Choisissez-en une :
- Un socket Unix : les permissions du fichier du socket le protègent.
- mTLS :
plugin_<kind>_tls_cert_fileetplugin_<kind>_tls_key_file, avec une adressehttps://. - Un jeton bearer :
plugin_<kind>_token(ouMY_PLUGIN_<KIND>_TOKEN_FILE), envoyé commeAuthorization: Bearer, uniquement parhttps://ou un socket Unix. Un jeton avec une adressehttp://est une erreur de configuration.
Une adresse https:// sans jeton ni certificat client démarre avec un avertissement, car le plugin ne peut pas distinguer le serveur de toute autre personne qui l’atteint.
Le serveur lit les fichiers de plugin_<kind>_tls_ca_file, plugin_<kind>_tls_cert_file et
plugin_<kind>_tls_key_file au démarrage, où un fichier manquant ou illisible l’arrête. Ensuite, il les surveille de nouveau
pour détecter un changement au plus toutes les 5 secondes, à l’ouverture d’une nouvelle connexion : un certificat de courte durée ou une CA qu’un
gestionnaire de certificats comme Vault, cert-manager ou SPIFFE renouvelle sur place fonctionne donc sans redémarrage. Les connexions déjà
ouvertes gardent le certificat avec lequel elles ont démarré jusqu’à leur fermeture. Pendant qu’un renouvellement est à moitié écrit, par exemple un nouveau
certificat dont la clé n’est pas encore en place, le serveur garde les fichiers lus en dernier et réessaie à la connexion suivante. Le jeton n’est lu qu’au démarrage.
TCP simple
Section intitulée « TCP simple »mailer, key_manager, translator, search, inbound.status, local.status et signup.check refusent http:// : le serveur ne démarre pas. Cela vaut aussi pour
le bouclage (http://127.0.0.1), car une adresse de bouclage n’empêche pas les autres processus de l’hôte de lire le
trafic. Placez un tel sidecar sur un socket Unix dans un volume partagé.
Les autres types acceptent http://, et le serveur journalise au démarrage un avertissement qui nomme le type et l’adresse. Rien
ne chiffre ni n’authentifie ce trafic, et aucun jeton bearer ne peut être utilisé dessus. Garder ce réseau fermé est de votre
responsabilité : ce que liste le tableau ci-dessus y circule en clair.
Protocoles
Section intitulée « Protocoles »plugin_<kind>_protocol indique ce que le serveur envoie, et cela doit être ce que le plugin accepte.
| Valeur | Ce que le serveur envoie | Pour |
|---|---|---|
json |
Le protocole unaire de Connect avec application/json, sur HTTP/1.1 pour les connexions simples |
Un plugin construit sur une bibliothèque Connect, ou sur un serveur HTTP et une seule bibliothèque JSON |
proto |
Le protocole de Connect avec application/proto |
Un plugin construit sur une bibliothèque Connect |
grpc |
gRPC sur HTTP/2 | Un plugin qui ne parle que gRPC |
Un plugin répond 415 au mauvais protocole. Les types de média transmettent en flux dans les deux sens, ce qui exige HTTP/2 : ils prennent donc proto
ou grpc, et json est une erreur de configuration.
Les définitions du protocole sont les fichiers .proto sous api/plugin/ du dépôt. Il y a un paquet pour chaque
type de port, et ils ne partagent aucun type ; les hooks de décision partagent tous un seul paquet, my.plugin.hook.v1.
Le protocole des plugins contient la référence de chaque paquet, générée à partir de ces fichiers.
Quand un appel échoue
Section intitulée « Quand un appel échoue »Un appel attend son tour parmi les appels de son type qui s’exécutent en même temps, et l’attente compte dans son délai et dans la
métrique my.plugin.slot_wait. Un appel qui échoue compte dans la métrique my.plugin.failures par type et code Connect. Le serveur abandonne le
message qu’un plugin met dans une erreur : les raisons des échecs d’un plugin se trouvent donc dans le journal du plugin lui-même. Le serveur
ne réessaie pas un appel lui-même : c’est la tâche qui l’a fait qui le fait, un plugin doit donc supporter deux fois le même appel.
Un plugin qui est arrêté au démarrage du serveur n’arrête rien, sauf key_manager : le serveur ne démarre pas sans lui, et
ce qui s’arrête sans lui est une partie de sa configuration à lire en premier.
Un appel a le délai de plugin_<kind>_timeout, et un plugin le reçoit comme Connect-Timeout-Ms (grpc-timeout sur
gRPC). Un plugin peut ignorer cet en-tête : le serveur cesse d’attendre de toute façon. Le délai doit rester inférieur à 30 secondes pour les
types qu’une requête peut attendre (key_manager, translator, search, signup.check, media.check, local.status, inbound.actor et local.profile), et
inférieur à 5 minutes, la durée maximale d’une tâche, pour les autres.
Tester un plugin
Section intitulée « Tester un plugin »my plugin test exécute le contrat d’un type contre un plugin en marche et rapporte chaque cas. Il ne lit aucune configuration :
tout ce qu’il faut, c’est le binaire my.
my plugin test --kind probe unix:///run/my/plugin.sockmy plugin test --kind probe --protocol grpc --tls-ca-file ca.pem --token-file token https://plugin.internal:8443PASS reachablePASS echoFAIL echo_empty: the outcome is OUTCOME_UNSPECIFIED, not OUTCOME_OK2 passed, 1 failed, 0 skippedLe code de sortie est 1 quand un cas échoue. Les options ont le sens des paramètres : --protocol, --token-file, --tls-ca-file,
--tls-cert-file, --tls-key-file et --timeout. Il applique les mêmes règles que le serveur : --kind mailer refuse donc une
adresse http://. Le plugin testé peut être un vrai plugin : un cas qui fait plus que l’appel lui-même ne s’exécute donc que si
une option le demande. Un type dont la version n’a pas encore le contrat rapporte reachable et un SKIP.
--kind billing vérifie seulement que le plugin refuse de dépenser quoi que ce soit quand aucune requête facturée n’est autorisée. --billed effectue aussi
une vraie récupération du mois en cours et du mois précédent, et vérifie la réponse comme le fait un import ; cela peut coûter de l’argent auprès
des prestataires derrière le plugin. Importer les coûts d’utilisation du cloud contient le
contrat de ce type.
--kind mailer n’effectue aucun appel du RPC sauf si --mail-to nomme un destinataire. Avec lui, la commande envoie un vrai message à cette adresse,
depuis --mail-from (par défaut : la même adresse), et vérifie que le plugin refuse une requête sans destinataire.
Envoyer des e-mails contient le contrat de ce type.
--kind translator envoie quelques phrases anglaises fixes, en les traduisant vers le japonais (--translate-from et --translate-to
choisissent une autre paire pour un plugin qui n’en a que certaines). Un service derrière le plugin qui facture au caractère facture aussi ceux-ci,
environ 200 caractères. Il vérifie la forme des réponses, et que le plugin refuse la langue qaa, un code que l’ISO 639
réserve à un usage privé. Il ne peut pas juger les mots : lisez vous-même une traduction du plugin.
Traduire des publications contient le contrat de ce type.
--kind search effectue des recherches, et n’écrit et ne retire que ses propres documents : quelques-uns avec des ID qu’aucune publication n’a, d’un
auteur qui n’est aucun compte, contenant un mot fabriqué pour l’exécution, qu’il retire à la fin. Il vérifie qu’une requête sans
mot ne trouve rien, qu’une requête dans le langage de requête d’un moteur ou en japonais n’échoue pas, que le plugin refuse un
curseur qu’il n’a pas émis, et que les documents sont trouvés du plus récent au plus ancien, page par page, remplacés, et retirés par publication et par
auteur. --clear-index exécute aussi les cas qui retirent tous les documents d’une visibilité et l’index entier : ne l’utilisez que
contre un index de test. Rechercher des publications contient le contrat de ce type.
--kind media_image, --kind media_video et --kind media_audio n’envoient que de petits fichiers de test qu’ils fabriquent eux-mêmes :
une photo, un émoji et un GIF animé, un MP4 avec une piste vidéo et une piste son, ou un MP3. Chacun cache un lieu ou un
titre dans ses métadonnées, et un cas échoue quand cela revient dans une sortie. Ils vérifient chaque sortie comme le fait le serveur.
Convertir des médias contient le contrat de ces types.
--kind key_manager exécute les vérifications que le serveur exécute à chaque démarrage, et vérifie que le plugin refuse une valeur modifiée et une
KEK qu’il ne détient pas. Il n’envoie que des clés qu’il invente et jette, il est donc sûr contre un vrai magasin de clés, qui peut facturer
les appels. Il vérifie que les réponses ont la bonne forme, pas comment le plugin conserve sa KEK.
Gérer la clé contient le contrat de ce type.
probe est le plus petit type, et le serveur ne lui délègue rien. Servez-le en premier, pour vérifier le transport, le
protocole et l’authentification avant d’écrire le reste du plugin.
Traduire des publications
Section intitulée « Traduire des publications »Un plugin du type translator permet au serveur de traduire une publication quand un lecteur le demande, via un service de votre choix
autre que les prestataires intégrés (LibreTranslate, DeepL, Google Cloud Translation et Amazon
Translate). Sans prestataire côté serveur, la seule traduction est celle intégrée au navigateur du lecteur, qui n’existe
que dans Chrome, Edge et Opera sur ordinateur : les lecteurs sur téléphone, dans Firefox ou dans Safari n’ont aucun bouton de traduction tant que vous n’en
activez pas un.
MY_PLUGIN_TRANSLATOR_ADDRESS=unix:///run/my/translator.sockMY_PLUGIN_TRANSLATOR_NAME="Our translator" # what readers see next to a translation- Définissez
plugin_translator_addressetplugin_translator_name, puis redémarrez. Le nom est obligatoire, car les lecteurs jugent une traduction fiable selon son origine. L’adresse ne quitte jamais la configuration. - Mettez à jour votre politique de confidentialité, et nommez le service derrière le plugin comme service de traduction : ce que le plugin transmet est ce qu’il reçoit.
- Activez-le avec le paramètre d’instance
translation_providers = plugin. Un changement prend effet immédiatement.
Avoir une adresse n’active rien : tant que le paramètre ne nomme pas plugin, le serveur n’envoie rien et les lecteurs ne voient aucun bouton.
Le plugin est un prestataire comme un autre. translation_provider_visibilities décide de ce qu’il peut
recevoir, les limites mensuelles comptent ce qui lui est envoyé, et une traduction qu’il a faite reste dans le cache du serveur comme les autres.
Avec translation_reports_to_server activé, il reçoit aussi ce que les modérateurs demandent à traduire dans un signalement, selon les mêmes visibilités.
Il peut venir avant ou après un autre prestataire dans l’ordre de translation_providers.
Ce que reçoit le plugin
Section intitulée « Ce que reçoit le plugin »Le plugin reçoit le texte d’une publication quand un lecteur demande une traduction : son corps, son avertissement de contenu, les options de sondage et les descriptions d’images, ainsi que la langue du texte et la langue cible. Il ne reçoit ni l’adresse de la publication, ni son auteur, ni le lecteur, ni les mentions, hashtags, liens, émojis personnalisés ou code : des marqueurs numérotés les remplacent.
Par défaut, ce sont les publications public, local et unlisted. Les publications private et direct n’atteignent le plugin que si vous les autorisez,
avec translation_provider_visibilities = plugin=public|local|unlisted|private|direct. Le plugin, et tout
service derrière lui, lit alors un texte que l’auteur destinait à peu de personnes : ne les autorisez donc que si vous contrôlez où va le texte,
et dites-le dans votre politique de confidentialité. Le serveur ne peut pas rappeler un texte qu’il a envoyé.
Le serveur refuse http:// pour ce type, y compris sur le bouclage, car le texte est celui de publications. Utilisez un socket Unix ou
https://.
Un LLM derrière un plugin
Section intitulée « Un LLM derrière un plugin »Le serveur n’a aucun prestataire LLM et n’en propose pas, délibérément. N’importe qui peut écrire une publication : le texte à traduire est donc un moyen de donner des instructions à un LLM (une injection de prompt), et les lecteurs prennent une traduction pour ce que dit la publication. L’assainissement protège le HTML d’une page : il ne peut pas empêcher une traduction de dire quelque chose que la publication ne dit pas.
Le serveur ne peut pas voir ce qu’un plugin appelle. Si votre plugin utilise un LLM, ce risque et ses conséquences relèvent de votre propre responsabilité.
Le contrat
Section intitulée « Le contrat »Le RPC est Translate de my.plugin.translator.v1.TranslatorService :
POST /my.plugin.translator.v1.TranslatorService/TranslateContent-Type: application/json
{"fragments":["Good morning ⟦1⟧, this is ⟦2⟧important⟦/2⟧.","⟦3⟧"],"sourceLanguage":"en","targetLanguage":"ja"}HTTP/1.1 200 OKContent-Type: application/json
{"outcome":"OUTCOME_OK","translations":["⟦1⟧さん、おはようございます。これは⟦2⟧重要⟦/2⟧です。","⟦3⟧"],"detectedLanguage":"en"}sourceLanguageest une balise BCP 47, ouundquand le serveur ne connaît pas la langue. Le plugin la détecte alors et la signale dansdetectedLanguage, ou répondOUTCOME_UNSUPPORTED_LANGUAGE.detectedLanguagepeut être absent quand le plugin n’a rien à ajouter, et le serveur ignore une valeur qui n’est pas une balise de langue.translationsa une entrée par fragment, dans l’ordre des fragments, aucune n’étant vide. Un fragment peut n’être composé que de marqueurs, et sa traduction est alors ces marqueurs.⟦1⟧représente un élément ou ouvre une paire que⟦/1⟧ferme. Chaque marqueur d’un fragment revient exactement une fois dans sa traduction, inchangé. Les éléments peuvent se déplacer selon l’ordre des mots, mais une paire reste ouverte avant de se fermer, et les paires s’imbriquent.- Une traduction est du texte brut. Le serveur échappe tout balisage qu’elle contient, et assainit le résultat avant de le stocker ou de l’afficher.
outcome |
Signification | Ce que fait le serveur |
|---|---|---|
OUTCOME_OK |
Les traductions sont dans la réponse | Les vérifie, les stocke et répond au lecteur |
OUTCOME_TEMPORARY |
Le service a échoué ou n’a pas répondu | Essaie le prestataire suivant |
OUTCOME_PROVIDER_LIMIT |
Le service signale sa propre limite de débit ou son quota | Essaie le prestataire suivant |
OUTCOME_UNSUPPORTED_LANGUAGE |
Le service n’a pas la langue source ou cible, ou ne peut pas la détecter | Essaie le prestataire suivant, et le dit au lecteur si aucun ne l’a |
Une réponse qui enfreint ces règles compte comme OUTCOME_TEMPORARY et rien n’en est stocké, comme pour un outcome manquant ou inconnu
et un appel échoué. Quand aucun prestataire ne répond, le lecteur voit que la traduction a échoué et la publication reste telle quelle, sauf si
translation_browser est activé et que le navigateur du lecteur peut traduire la publication : le client web la traduit alors à cet endroit.
Les caractères de chaque appel comptent dans les limites mensuelles, y compris pour un appel qui échoue, car le service peut les avoir reçus.
Le serveur cesse d’attendre après plugin_translator_timeout, et après 20 secondes quelle que soit la valeur de ce paramètre. Tous les
prestataires d’une même requête disposent de 45 secondes en tout. Il ne réessaie pas un
appel échoué, et les mêmes fragments peuvent revenir pour un autre lecteur.
Rechercher des publications
Section intitulée « Rechercher des publications »Un plugin du type search tient l’index de la recherche en texte intégral des publications dans un moteur que le serveur
ne prend pas en charge nativement, comme Groonga ou PGroonga, un index construit avec Sudachi, Typesense, Manticore ou un service de
recherche hébergé. Pour le serveur, c’est un moteur de plus : les mêmes publications entrent dans l’index, les mêmes tâches le tiennent à jour,
et le serveur décide toujours de ce que chaque personne peut voir.
MY_SEARCH=pluginMY_PLUGIN_SEARCH_ADDRESS=unix:///run/my/search.sock- Exécutez le plugin, et vérifiez-le avec
my plugin test --kind search. - Définissez
search = pluginetplugin_search_address, puis suivez L’activer, comme pour tout moteur : l’index se remplit à partir de là, etmy search rebuildajoute les publications existantes. - Si le plugin envoie les publications à un service d’une autre entreprise, nommez ce service dans vos documents de confidentialité.
Le serveur n’ouvre aucune connexion au démarrage : un plugin arrêté n’arrête donc rien d’autre que la recherche. Pour passer au plugin ou le quitter, suivez Désactiver ou changer le moteur.
Ce que reçoit le plugin
Section intitulée « Ce que reçoit le plugin »- Les publications de l’index. Pour chaque publication que l’index contient, le plugin reçoit son texte (le corps, l’avertissement de contenu
et les descriptions d’images, en texte brut), son ID, l’ID de compte de son auteur, sa visibilité, sa langue
et sa date de publication. Il s’agit uniquement de publications
publicetlocal, comme le ditsearch_visibilities, d’auteurs qui autorisent la recherche. Les publicationslocalsont destinées aux seuls comptes de ce serveur : le plugin, et tout service derrière lui, les lit aussi. Les publicationsunlisted,privateetdirectne l’atteignent jamais. - Les requêtes. Quand une personne connectée recherche des publications, le plugin reçoit ce qu’elle a saisi, avec le curseur de la page et le nombre de résultats. Il ne reçoit pas l’identité de la personne qui a cherché.
- Les retraits : d’une publication, de toutes les publications d’un compte, de toutes les publications d’une visibilité, et de l’index entier.
Le plugin ne renvoie que des ID de publications. Le serveur relit chaque publication dans sa base de données et n’affiche que ce que la personne peut voir à cet instant : un plugin ne peut donc pas montrer une publication à qui ne peut pas la voir, et un index en retard ne fait que trouver moins de choses. Le serveur n’affiche en outre jamais les erreurs d’un plugin à qui que ce soit.
Le serveur refuse http:// pour ce type, y compris sur le bouclage, car il transporte le texte des publications et ce que les gens recherchent.
Utilisez un socket Unix ou https://.
Le contrat
Section intitulée « Le contrat »Le service est my.plugin.search.v1.SearchService, avec un RPC par opération :
| RPC | Ce qu’il fait |
|---|---|
Replace |
Ajoute le document d’une publication, ou remplace le document ayant le même statusId |
Remove |
Retire le document d’une publication |
RemoveByAuthor |
Retire tous les documents d’un compte |
RemoveByVisibility |
Retire tous les documents d’une visibilité, VISIBILITY_PUBLIC ou VISIBILITY_LOCAL |
Clear |
Retire tous les documents ; l’index reprend ensuite des documents |
Search |
Renvoie une page des ID des documents qu’une requête trouve, du plus récent au plus ancien |
POST /my.plugin.search.v1.SearchService/ReplaceContent-Type: application/json
{"document":{"statusId":"019a5f3e-8b2c-7d41-9a3e-2f6c1b8d4e07","authorId":"0199c2d4-1e5f-7a3b-8c9d-0e1f2a3b4c5d","visibility":"VISIBILITY_PUBLIC","language":"ja","publishedAt":"2026-11-07T05:12:30Z","text":"週末に図書館で全文検索の本を読んだ"}}HTTP/1.1 200 OKContent-Type: application/json
{"outcome":"OUTCOME_OK"}POST /my.plugin.search.v1.SearchService/SearchContent-Type: application/json
{"text":"全文検索","limit":1}HTTP/1.1 200 OKContent-Type: application/json
{"outcome":"OUTCOME_OK","statusIds":["019a5f3e-8b2c-7d41-9a3e-2f6c1b8d4e07"],"nextCursor":"019a5f3e-8b2c-7d41-9a3e-2f6c1b8d4e07"}- Une requête est du texte brut. Le plugin la découpe en mots et trouve les documents qui contiennent chaque mot. Il ne lit jamais le texte comme le langage de requête de son moteur : un opérateur, un joker, un guillemet ou un nom de champ qu’elle contient n’est que du texte. Une requête sans mot ne trouve rien. La façon dont le plugin trouve des mots en japonais et dans les autres langues écrites sans espaces relève de son propre choix, et c’est la raison d’en avoir un.
- Une page va du plus récent au plus ancien. Les
statusIdssont en ordre décroissant, chacun au plus une fois,limitau plus, et chacun un ID de statut tel que le serveur l’a envoyé (36 caractères minuscules). Les ID sont des UUIDv7 : leur ordre en chaînes est donc l’ordre chronologique. - Le curseur appartient au plugin.
nextCursorest vide sur la dernière page, et sinon fait au plus 256 octets d’ASCII imprimable sans espace, comme le dernier ID de la page. Le serveur le renvoie tel quel pour la page suivante, qui continue après cet ID même si des documents sont arrivés et partis. Une page qui n’est pas la dernière peut contenir moins delimitID. Un curseur que le plugin n’a pas émis reçoitOUTCOME_INVALID_CURSOR. - Une écriture se voit à la recherche suivante, et chaque appel peut arriver deux fois : retirer ce qui n’est pas là réussit. Un moteur qui n’affiche les écritures qu’après un rafraîchissement oblige le plugin à l’attendre.
outcome |
Signification | Ce que fait le serveur |
|---|---|---|
OUTCOME_OK |
L’appel a fait ce qu’il demande | Applique la politique de visibilité aux ID d’une page |
OUTCOME_FAILED |
Le moteur a échoué ou n’a pas répondu | Réessaie une écriture avec sa tâche ; fait échouer une recherche, que la personne peut réessayer |
OUTCOME_INVALID_CURSOR |
Search uniquement : le curseur n’est pas un curseur émis par le plugin |
Indique au client que son curseur est erroné |
Un outcome manquant ou inconnu, un appel échoué et une page qui enfreint ces règles comptent comme OUTCOME_FAILED, et rien
d’une telle page n’est affiché. Un appel dure au plus plugin_search_timeout (10 secondes par défaut), et 10 secondes quelle que soit la valeur de ce
paramètre.
Convertir des médias
Section intitulée « Convertir des médias »Un plugin média accomplit la partie lourde du traitement des envois, afin qu’il puisse tourner sur une autre machine. Il existe trois types, et vous choisissez chacun séparément :
media_imageré-encode les images en leurs variantes.media_videoremuxe les vidéos : des fichiers avec une piste vidéo, avec ou sans son.media_audioremuxe les fichiers audio seuls.
Le serveur fait toujours le reste lui-même. Il détecte le format de chaque envoi, distingue les vidéos des fichiers audio, vérifie chaque
envoi par rapport aux limites à son arrivée, et fabrique les aperçus des médias distants. Un type dont le paramètre reste native est
traité dans le serveur.
# Only videos go to a plugin, on a machine of its own; images and audio stay in the server.MY_MEDIA_VIDEO=pluginMY_PLUGIN_MEDIA_VIDEO_ADDRESS=https://media.internal:9000Définissez media_<kind> = plugin et plugin_media_<kind>_address pour chaque type que vous confiez, puis redémarrez. Un plugin peut
prendre plusieurs types : donnez-lui la même adresse pour chacun. Chaque type exécute au plus deux appels à la fois, et chaque appel dure au plus
plugin_media_<kind>_timeout (4 minutes par défaut), afin qu’une vidéo lente ne retarde pas les images.
- Retirer les métadonnées est le travail du plugin. Les envois parviennent au plugin tels qu’ils ont été envoyés, avec leurs données EXIF et leurs
balises, qui peuvent contenir le lieu où une photo a été prise. Le serveur vérifie le format et la taille de chaque sortie, mais il ne peut pas
savoir si toute trace de métadonnées a disparu.
my plugin test --kind media_imagevérifie que le lieu de ses fichiers de test ne revient pas ; vérifiez le reste dans le plugin. - Le TCP simple envoie les fichiers sans chiffrement. Les types de média acceptent
http://, avec un avertissement au démarrage. Les envois, avec leurs métadonnées, traversent alors le réseau en clair, et rien n’authentifie aucune des extrémités : quiconque se trouve sur ce réseau peut les lire ou répondre à la place du plugin. Utilisez un socket Unix ouhttps://sauf si le réseau n’appartient qu’à vous. - Le serveur ne fait pas confiance à la sortie. Il détecte le format de chaque sortie d’après son contenu, jamais d’après ce que le plugin déclare, et la sert avec le type de contenu et l’extension de fichier de ce format. Il décode chaque sortie sous les mêmes limites qu’un envoi, et vérifie qu’elle respecte sa taille. Une sortie plus grande que déclaré ou que ces limites, d’un format que le plugin n’a pas déclaré, ou d’un format que la variante n’accepte pas, fait échouer l’envoi comme un fichier que le serveur ne peut pas traiter.
- Un échec est un retard. Quand le plugin est arrêté ou échoue, la tâche réessaie plus tard, comme avec le processeur intégré. Une action qui a besoin immédiatement de l’image d’un émoji personnalisé, comme copier un émoji distant ou accepter une demande pour en obtenir un, échoue tant que le plugin échoue.
Le contrat
Section intitulée « Le contrat »Le service est my.plugin.media.v1.MediaService, avec les RPC Process pour une image et Remux pour une vidéo ou un fichier audio.
Les deux transmettent en flux dans les deux sens : le plugin a donc besoin d’une bibliothèque Connect ou gRPC et de HTTP/2 : proto ou grpc, sur TLS avec ALPN
h2, ou sur HTTP/2 en clair (h2c) sur un socket Unix ou en TCP simple.
Un appel est semi-duplex :
- Le serveur envoie un
head: les limites, et pour une image son usage, les boîtes de ses trois tailles, et son point focal. Le fichier suit dans des messageschunkde 1 MiB au plus. Le serveur ferme ensuite son côté. - Le plugin répond par un
headdont l’outcomeest le résultat. AvecOUTCOME_OK, l’en-tête deProcesscontient aussi les dimensions de l’image après son orientation EXIF et le blurhash de la petite sortie fixe. - Pour chaque sortie, le plugin envoie un
part, qui nomme la sortie et déclare son format, ses dimensions et sa longueur, suivi de messageschunkde 1 MiB au plus.
Process renvoie les sorties fixes petite, moyenne et grande, et les trois sorties animées d’une image de plus d’une
image. Les sorties petite et moyenne sont en WebP ; la grande sortie fixe est un JPEG ou un PNG (toujours un PNG pour un émoji personnalisé),
et la grande sortie animée un GIF. Remux renvoie le fichier dans son propre conteneur sans métadonnées, ainsi que l’image de couverture qu’il
intègre, le cas échéant. Le serveur lit au plus deux fois la limite d’image depuis Process, et depuis Remux la limite vidéo pour le
fichier et la limite d’image pour sa couverture.
outcome |
Signification | Ce que fait le serveur |
|---|---|---|
OUTCOME_OK |
Les sorties suivent | Les vérifie et les stocke |
OUTCOME_TEMPORARY |
Le plugin a échoué | Réessaie la tâche plus tard |
OUTCOME_UNSUPPORTED_FORMAT, OUTCOME_UNSUPPORTED_CODEC, OUTCOME_TOO_LARGE, OUTCOME_DIMENSIONS, OUTCOME_CORRUPT, OUTCOME_TOO_LONG |
Le fichier n’est pas acceptable | Marque l’envoi comme échoué |
Un outcome manquant ou inconnu et un appel échoué comptent comme OUTCOME_TEMPORARY.
Un plugin sans bibliothèque
Section intitulée « Un plugin sans bibliothèque »Avec json, un plugin n’a besoin que d’un serveur HTTP et d’une bibliothèque JSON. Un RPC est un POST vers
/<package>.<Service>/<Method> avec Content-Type: application/json, et le plugin répond 200 avec un objet JSON :
POST /my.plugin.probe.v1.ProbeService/EchoContent-Type: application/jsonConnect-Protocol-Version: 1
{"payload":"AP8=","number":"9007199254740993"}HTTP/1.1 200 OKContent-Type: application/json
{"outcome":"OUTCOME_OK","payload":"AP8=","number":"9007199254740993"}Le JSON suit la correspondance standard de proto3 :
- Un
int64est une chaîne décimale, lesbytessont en base64, et une énumération est son nom. - Un champ à sa valeur zéro peut être absent, dans les deux sens. Un plugin doit lire un champ absent comme zéro.
- Le serveur ignore les champs qu’il ne connaît pas.
- Un résultat est l’
outcomede la réponse. Unoutcomemanquant ou inconnu est un échec, jamais un succès. - Un plugin qui échoue répond par une erreur HTTP, ou par
{"code":"unavailable"}de Connect avec le statut correspondant. La tâche réessaie.
Connect-Timeout-Ms et Connect-Protocol-Version peuvent être ignorés.
Pour les LLM et les agents de programmation :llms.txt,llms-full.txt, llms-small.txt